Scanner Module — Gamma API Ka Complete Wrapper

Bismillah. Chalo shuru karte hain.

COURSE: Pakistan Ka Pehla Professional Trading Bot Course

MODULE 3: Market Data Pipeline — API Se Real-Time Data Kaise Fetch Karein

LESSON 3.1: Scanner Module — Gamma API Ka Complete Wrapper

Assalam-o-Alaikum, future bot masters! Pichle lessons mein humne setup aur basic concepts dekhay. Aaj asal kaam shuru hoga. Aapka bot andha hai, usko aankhein deni hain. The Scanner module is the "eyes and ears" of your trading bot, and Gamma API is our free, powerful data source.

Scene simple hai: agar bot ko yehi nahi pata ke market mein chal kya raha hai, tou woh trade kya khaak karega? This lesson is the foundation. Isko aagaya, tou aage sab मक्खन (makkhan) hai.

Gamma API - Hamara Data Ka Chashma

So, what is an API? Asaan bhasha mein, yeh ek waiter hai. Aap restaurant (aapka code) mein bethay ho, aapko kitchen (Polymarket ke servers) se data chahiye. Aap waiter (API) ko batate ho, "Bhai, zara saare active markets le aana." Woh jaata hai, kitchen se data laata hai, aur aapki table pe rakh deta hai.

Hum Gamma API use kar rahe hain. Kyun?

Free Hai: Koi paisa nahi lagna. Start karne ke liye is se behtar kuch nahi.
No Rate Limits (Practically): Baaqi APIs pe aapko har minute mein calls ki limit hoti hai. Yahan tension nahi. Jab tak aap server ko DDoS karne ki koshish nahi kar rahe, you're good. Pakistani developers ke liye ye ek blessing hai.
Rich Data: Sirf price nahi, volume, expiry, sab kuch milta hai.

Chalo, ab code pe aate hain. We'll build the core of our scanner.py file today.

Core Functions - Asal Code Shuru

Apne project mein ek file banao, scanner.py. Usmein yeh basic setup daalo:

import requests
import json
from datetime import datetime, timezone, timedelta
import time # For retries

# Gamma API ka base URL. Saari requests yahin se jayengi.
GAMMA_BASE = 'https://gamma-api.polymarket.com'

Ab, ek ek karke humare core functions ko samjhein ge.

1. `fetch_active_markets` - Market Dhoondna

Bot ko sab se pehle ye pata karna hai ke trade karne ke liye available kya kya hai. Yeh function humare liye Polymarket se saare active markets utha kar layega.

def fetch_active_markets(limit=100):
    """
    Fetches a list of active markets from the Gamma API, sorted by 24hr volume.
    """
    print('[SCANNER] Fetching active markets...')
    try:
        # API ko GET request bhej rahe hain
        r = requests.get(f'{GAMMA_BASE}/markets', params={
            'active': 'true',         # Sirf active markets
            'closed': 'false',        # Jo band ho gaye hain, woh nahi
            'limit': limit,           # Kitne markets fetch karne hain
            'order': 'volume24hr',    # Volume ke hisaab se sort karo
            'ascending': 'false'      # Ziada volume waale pehle
        }, timeout=15) # 15 second ka intezar, warna give up

        # Check karo ke waiter ne sahi order laya hai (status code 200)
        if r.status_code == 200:
            print(f'[SCANNER] Successfully fetched {len(r.json())} markets.')
            return r.json()
        else:
            # Agar koi masla hai, tou error print karo
            print(f'[SCANNER] Error fetching markets. Status: {r.status_code}, Response: {r.text}')
            return []
            
    except requests.exceptions.RequestException as e:
        # Network ka masla, timeout, etc.
        print(f'[SCANNER] Network error while fetching markets: {e}')
        return []

Code Breakdown:

requests.get(...): Yeh requests library ka function hai jo API ko call karta hai. Hum usko bata rahe hain ke /markets endpoint pe jao.
params={...}: Yeh humara order hai. Imagine filtering products on Daraz.
- 'active': 'true', 'closed': 'false': Hum sirf woh markets maang rahe hain jo abhi live hain.
- 'order': 'volume24hr', 'ascending': 'false': Iska matlab hai ke jin markets mein pichle 24 ghante mein sabse ziada paisa laga hai, woh list mein sabse upar aayenge. Humara bot high-liquidity markets mein interested hai.
timeout=15: Bohat important. Agar Polymarket ka server 15 second mein jawab nahi deta, tou humara code aage barh jayega, phansa nahi rahega.
try...except: Network hamesha reliable nahi hota. Kabhi internet disconnect hojata hai, kabhi API down hoti hai. Yeh block humare code ko crash hone se bachata hai. Agar requests.get fail hota hai, tou except block chalega aur hum ek empty list [] return kar denge.
r.status_code == 200: HTTP protocol mein, 200 OK ka matlab hai "sab theek hai". Agar 404 (Not Found) ya 500 (Server Error) aaye, tou humein pata chal jayega ke kuch garbar hai.

2. `get_market_price` - Sahi Daam Nikalna

Ab humare paas markets ki list hai. Har market ka data ek bare se dictionary jaisa hai. Humein usmein se kaam ki cheez, yaani ke "YES" outcome ki price nikaalni hai.

def get_market_price(market: dict) -> float:
    """
    Extracts the YES price (0-100) from a market data dictionary.
    Handles a common API inconsistency where outcomePrices can be a JSON string.
    """
    # 'outcomePrices' key ko access karo. Agar nahi hai, tou default '[0,0]' use karo.
    prices = market.get('outcomePrices', '[0,0]')
    
    # Common Galti Alert: Kabhi kabhi API yeh string mein bhejta hai
    if isinstance(prices, str):
        try:
            prices = json.loads(prices)
        except json.JSONDecodeError:
            # Agar string ajeeb hai aur parse nahi ho rahi
            print(f"[SCANNER] Warning: Could not parse outcomePrices string: {prices}")
            return 0.0

    # Ensure prices is a list and has at least one element
    if not isinstance(prices, list) or len(prices) == 0:
        return 0.0

    # Index 0 hamesha 'YES' price hoti hai (0.0 to 1.0)
    yes_price_prob = float(prices[0])
    
    # Probability ko 0-100 ki price mein convert karo aur 2 decimal places tak round karo
    return round(yes_price_prob * 100, 2)