Assalam-o-Alaikum, developers!

Welcome to Module 6 of Pakistan's first professional trading bot course. Pichle modules mein humne strategy banayi, signals generate kiye, aur market ko samjha. Lekin strategy aur signal sab bekaar hain agar aap uss information pe act na kar sako. Yeh module asli game hai — jahan rubber meets the road, aur hamara bot paisa banata ya gavata hai.

COURSE: Pakistan Ka Pehla Professional Trading Bot Course

MODULE 6: Execution Engine — Automatically Orders Place Karna

LESSON 6.1: CLOB API 101 — Polymarket Ka Trading Interface

Ab tak sab theory thi, ab practical shuru. Agar aapka bot market mein order place nahi kar sakta, tou woh sirf ek fancy calculator hai. Aaj hum seekhenge ke Polymarket ke trading engine, yaani CLOB, se direct baat kaise karte hain.

CLOB Kya Cheez Hai? Scene Samjho

CLOB ka matlab hai Central Limit Order Book.

Yeh naam sun ke pareshan nahi hona. Agar aapne kabhi Pakistan Stock Exchange (KSE) pe trading ki hai ya dekhi hai, tou aapko CLOB ka concept already pata hai. Yeh bilkul waisa hi system hai.

• Order Book: Ek list hoti hai jisme saare 'buy' (bids) aur 'sell' (asks) orders jama hote hain.
• Limit: Aap order place karte waqt ek specific price batate ho. "Main 'YES' token 0.60 pe khareedna chahta hoon, uss se mehnga nahi." Yeh ek limit order hai.
• Central: Saare orders ek central jagah pe match hote hain. Jab ek buyer ki price ek seller ki price se match karti hai, trade ho jaati hai.

Yeh system AMM (Automated Market Maker) jaise protocols se bohot fast aur efficient hota hai, isliye high-frequency trading ke liye perfect hai.

Sab se important baat: Polymarket ka CLOB Polygon blockchain pe chalta hai. Iska matlab har trade on-chain, transparent, aur immutable hai. Aapki har trade ko aap PolygonScan pe dekh sakte ho. Yeh Web3 ka asli power hai, aur aap Pakistani developers isko practically use karna seekh rahe ho.

The Tools of the Trade: py_clob_client

Khushkhabri yeh hai ke humein blockchain se direct, low-level pe baat nahi karni. Polymarket ne hamare liye ek zabardast Python library banayi hai: py_clob_client.

Pehle isko install karein. Apna terminal kholo aur likho:

pip install py_clob_client

Yeh library hamare liye saari heavy lifting karegi — authentication, order signing, aur CLOB API se communication. Hum bas isko commands denge.

Step 1: Wallet Setup - Apni Tijori Tayyar Karo

Blockchain pe kuch bhi karne ke liye, aapko ek wallet chahiye. Hamare bot ke liye, do cheezein critical hain:

1. Private Key: Yeh aapke wallet ka master password hai. Isko KABHI BHI public code, jaise GitHub, pe share nahi karna. Yeh aapke bank account ka PIN, password, ATM card, sab kuch hai. Hum isko environment variable mein save karenge.
2. Proxy Address: Polymarket CLOB direct aapke main wallet se interact nahi karta. Woh ek special smart contract wallet use karta hai jisko "Proxy" kehte hain. Yeh security ke liye acha hai. Aapka main wallet is proxy ko control karta hai. Agar aapke paas proxy nahi, tou client library aapke liye khud deploy kar degi.

Chalo, client setup karte hain. Ek file banao trader.py aur yeh code likho:

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds

# .env file se environment variables load karo
load_dotenv()

# --- Wallet Configuration ---
# WARNING: Apni private key ko kabhi bhi direct code mein mat likhna.
# .env file mein aise save karo: PRIVATE_KEY="0x..."
private_key = os.getenv("PRIVATE_KEY")
if not private_key:
    raise ValueError("PRIVATE_KEY environment variable set nahi hai!")

# Polymarket CLOB Polygon mainnet pe hai
chain_id = 137

# API credentials (optional, lekin rate limits se bachne ke liye zaroori)
# .env file mein: POLY_API_KEY="your_key", POLY_API_SECRET="your_secret", POLY_API_PASSPHRASE="your_passphrase"
api_creds = ApiCreds(
    key=os.getenv("POLY_API_KEY"),
    secret=os.getenv("POLY_API_SECRET"),
    passphrase=os.getenv("POLY_API_PASSPHRASE"),
)

# --- Client Initialization ---
# verbose=True se aapko background mein kya ho raha hai, sab nazar aayega. Debugging ke liye best hai.
client = ClobClient(
    chain_id=chain_id,
    private_key=private_key,
    api_creds=api_creds,
    verbose=True 
)

# Client ko start karo. Yeh proxy address check karega aur zaroorat parne par deploy karega.
client.init()

print(f"Bot is ready! Wallet address: {client.get_address()}")
print(f"Proxy address for trading: {client.get_proxy_address()}")

Yeh code chalane se pehle, ek .env file banao aur usmein apni details daalo:

PRIVATE_KEY="0xyour_private_key_here"
POLY_API_KEY="your_polymarket_api_key"
POLY_API_SECRET="your_polymarket_api_secret"
POLY_API_PASSPHRASE="your_polymarket_api_passphrase"

Step 2: The Language of the Market - Token IDs

Har Polymarket market ke do possible outcomes hote hain: YES ya NO.

Example: PSL ka match hai, Lahore Qalandars vs. Karachi Kings. Market hai: "Will Lahore Qalandars win?"

• YES Token: Iski price represent karti hai ke Lahore ke jeetne ka kitna chance hai. Agar price 0.65 hai, iska matlab market 65% chance de rahi hai.
• NO Token: Iski price represent karti hai ke Lahore nahi jeetega (yaani Karachi jeetega). Iski price 1 - YES_price hogi, yaani 0.35.

Trading karne ke liye, humein in YES aur NO tokens ke unique ID chahiye hote hain. Yeh IDs market ke hisaab se alag hote hain. Inko haasil karne ke liye hum Polymarket ki ek doosri API, Gamma API, use karte hain.

Yeh raha function jo hamare Oracle codebase mein scanner.py use karta hai naye markets ke token IDs nikalne ke liye. Isko aaram se samjho:

import os
import json
import requests

# Yeh CLOB trading API ka base URL hai
CLOB_BASE = 'https://clob.polymarket.com'
# Yeh Gamma market data API ka base URL hai
GAMMA_BASE = 'https://gamma-api.polymarket.com'
CHAIN_ID = 137  # Polygon mainnet

def get_token_id(market_id: str, side: str = 'YES'):
    """
    Market ID aur side (YES/NO) ke basis pe correct token ID nikalta hai.
    Yeh function CLOB API se nahi, Gamma API se data leta hai, kyunki market
    ki general information wahan hoti hai.
    """
    print(f"Fetching token ID for market '{market_id}' for side '{side}'...")
    
    # Gamma API ko request bhej rahe hain market details ke liye
    # CLOB API is the gateway to actual trade execution on Polymarket

---

## 📺 Recommended Videos & Resources
- **[CLOB (Central Limit Order Book) Explanation](https://en.wikipedia.org/wiki/Central_limit_order_book)** — Understanding order books
  - Type: Wikipedia
  - Link description: Learn how CLOBs work and market mechanics
- **[Polymarket CLOB API Docs](https://clob.polymarket.com/docs)** — Official API reference
  - Type: Official Documentation
  - Link description: Reference for all CLOB endpoints and parameters
- **[Order Types: Limit vs Market](https://www.youtube.com/results?search_query=limit+order+market+order+difference)** — Order mechanics
  - Type: YouTube
  - Link description: Search "limit order vs market order"
- **[Slippage & Execution Quality](https://www.youtube.com/results?search_query=slippage+trading+execution+quality)** — Understanding execution costs
  - Type: YouTube
  - Link description: Search "slippage and execution quality trading"
- **[Polygon Network Gas Costs](https://polygonscan.com/)** — Understanding blockchain costs
  - Type: Official Website
  - Link description: Monitor actual Polygon gas prices

---

## 🎯 Mini-Challenge
**5-Minute Practical Task:** Query a CLOB endpoint for a specific market. Analyze the order book: (1) Count bids at each price level, (2) Calculate the spread, (3) Estimate slippage for a $500 order. Determine if the market is liquid enough for your bot to trade.

---

## 🖼️ Visual Reference

📊 CLOB Order Book Structure ┌──────────────────────────────┐ │ Bids (buyers) │ Asks │ │ Price | Size │ Price │ ├──────────────────────────────┤ │ 75.00 | 500 shares │ │ │ 74.95 | 1000 shares │ │ │ 74.90 | 2000 shares │ │ │ │ │ │ SPREAD: 75.05 - 75.00 │ │ │ = 0.05 (tight) │ │ │ │ 75.05 │ │ │ 75.10 │ │ │ 75.15 │ └──────────────────────────────┘

Your bot can:

• Place limit order at 75.02 (likely fills, small slippage)
• Place market order (immediate, higher slippage)

---