Polymarket API گائیڈ: CLOB، REST اور ٹریڈنگ بوٹس (2026)

باب 33 میں سے 27

مختصر ورژن

Polymarket تین عوامی APIs پیش کرتا ہے: CLOB (ٹریڈنگ)، Gamma (مارکیٹ دریافت)، اور Data (اینالیٹکس)۔ آفیشل Python SDK py-clob-client 0.34.6 ہے۔ تصدیق کے لیے API key + ECDSA signature استعمال ہوتی ہے، اور آرڈرز EIP-712 کے ذریعے Polygon proxy wallet پر سائن کیے جاتے ہیں۔ Rate limits آپ کو فی key تقریباً 60 آرڈرز/منٹ تک محدود کرتی ہیں۔ نئے developers کے لیے سب سے بڑا مسئلہ condition_id → token_id mapping ہے جو Gamma اور CLOB کے درمیان ہوتا ہے - پہلے اسے حل کریں، پھر باقی سب خود بخود سمجھ آ جائے گا۔ Polymarket پر تقریباً $40M/ماہ کی لیکویڈیٹی (liquidity) انعامات (rewards) اور bot-captured spread کمائی جاتی ہے، اور یہ تقریباً مکمل طور پر API users کے ذریعے ہوتی ہے۔

تین الگ خدمات: CLOB (9,000/10s auth) trading کے لیے، Gamma (4,000/10s public) discovery کے لیے، Data (1,000/10s public) تاریخی analytics کے لیے۔

حصہ 1: تین APIs

Polymarket صاف طور پر ذمہ داریوں کو تین الگ خدمات میں تقسیم کرتا ہے۔ ہر کام کے لیے درست API استعمال کرنے سے آپ کا بوٹ تیز، سادہ، اور rate limits کے اندر رہتا ہے۔

ایک عام بوٹ loop Gamma کو مارکیٹس تلاش کرنے کے لیے، CLOB کو آرڈر بک حاصل کرنے اور trades place کرنے کے لیے، اور Data کو strategy performance کو offline back-test کرنے کے لیے استعمال کرتا ہے۔ Gamma کو "catalog"، CLOB کو "exchange"، اور Data کو "warehouse" سمجھیں۔

L1 chainId 137 کے ساتھ "ClobAuthDomain" EIP-712 struct پر sign کرتا ہے تاکہ credentials derive ہوں۔ L2 HMAC-SHA256 ہر subsequent request کو POLY_SIGNATURE headers کے ساتھ sign کرتا ہے۔

حصہ 2: توثیق اور پراکسی والٹ ماڈل

Polymarket آپ کے مرکزی والٹ کی نجی کلید سے ٹریڈز پر دستخط نہیں کرتا۔ اس کے بجائے، یہ ایک Gnosis Safe طرز کے پراکسی والٹ کا استعمال کرتا ہے: آپ کا مرکزی والٹ ایک پراکسی کو مجاز کرتا ہے، اور پراکسی Polygon پر تمام ٹریڈز انجام دیتا ہے۔ آپ کا API بوٹ اسی پراکسی سے بات کرتا ہے۔

آپ کو کیا درکار ہے

• API key - Polymarket Settings → Developer میں تیار کریں
• Private key - آپ کے trading wallet کی کلید (آپ کے مرکزی MetaMask seed phrase کی نہیں)
• Funder address - آپ کے پراکسی والٹ کا پتہ (Settings → Wallet میں دکھایا گیا)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, retail users کے لیے معیاری)

Magic-link accounts کے لیے Signature type 1 (POLY_PROXY)، browser-wallet proxies کے لیے type 2 (GNOSIS_SAFE)، direct keys کے لیے type 0 (EOA)۔ type 1 اور 2 کے لیے Funder درکار ہے۔

حصہ 3: py-clob-client انسٹال کرنا

سرکاری Python SDK صفر سے پہلی آرڈر تک پہنچنے کا سب سے تیز طریقہ ہے۔ ہم ورژن 0.34.6 استعمال کریں گے، جو اپریل 2026 تک موجودہ ہے۔

# پہلے ایک ورچوئل ماحول بنائیں
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# SDK انسٹال کریں
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

بنیادی کلائنٹ کنفیگریشن

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# ایک بار کے لیے: API اسناد derive کریں اور cache کریں
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() کال آپ کی private key کے ساتھ ایک پیغام پر دستخط کرتی ہے اور اس کے بدلے ایک API key، secret، اور passphrase لیتی ہے۔ پہلی بار چلانے کے بعد انہیں اپنے .env میں cache کریں تاکہ ہر startup پر آپ derive endpoint کو hit نہ کریں۔

Gamma /markets outcomePrices، clobTokenIds، volume24hr، tags واپس کرتا ہے۔ بطور ڈیفالٹ بوٹ اسکینر query کے لیے tag_slug + order=volume24hr استعمال کریں۔

حصہ 4: Gamma کے ذریعے مارکیٹس دریافت کرنا

ٹریڈ کرنے سے پہلے، آپ کو ایسی مارکیٹس تلاش کرنی ہوتی ہیں جن میں ٹریڈ کرنا فائدہ مند ہو۔ Gamma ایسا JSON واپس کرتا ہے جس میں وہ سب کچھ ہوتا ہے جو Polymarket UI دکھاتا ہے: سوال، نتائج، قیمتیں، 24 گھنٹے کا حجم، میعاد ختم ہونا، ٹیگز، اور تصاویر۔

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Gamma کے مفید query parameters

Gamma conditionId ظاہر کرتا ہے (ہر مارکیٹ کے لیے ایک); CLOB token_id پر ٹریڈ کرتا ہے (ہر outcome کے لیے ایک)۔ clobTokenIds ایک JSON-encoded string array ہے جو outcomes کے ساتھ index-matched ہے۔

حصہ 5: condition_id → token_id میپنگ

یہ Polymarket بوٹ ڈیولپمنٹ میں #1 دردِ سر ہے۔ Gamma ایک condition_id واپس کرتا ہے (ہر مارکیٹ کے لیے ایک)۔ CLOB ٹریڈز ایک token_id استعمال کرتی ہیں (ہر نتیجے کے لیے ایک)۔ آپ کو ہمیشہ دونوں کی ضرورت ہوتی ہے۔

# ہر Gamma مارکیٹ آبجیکٹ میں 'clobTokenIds' شامل ہوتے ہیں - ایک JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # پہلا نتیجہ
no_token = token_ids[1] # دوسرا نتیجہ

# متبادل: condition_id استعمال کرکے براہِ راست CLOB سے پوچھیں
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

نتیجے کی ترتیب کا جھنجھٹ

Gamma کا outcomes array اور clobTokenIds array انڈیکس کے لحاظ سے میچ ہوتے ہیں۔ ہمیشہ یہ فرض کرنے کے بجائے کہ index 0 "Yes" ہے، outcome label پڑھیں۔ کثیر نتیجہ مارکیٹوں (NegRisk، Oscars، elections) میں، index 0 "Kamala Harris" یا "Taylor Swift" ہو سکتا ہے - ترتیب طے شدہ ہوتی ہے لیکن مارکیٹ کے لحاظ سے مخصوص ہوتی ہے۔

آرڈر بک bids descending، asks ascending کے طور پر واپس آتی ہے۔ market-like FAK بھیجنے سے پہلے کسی بھی target notional کے لیے fill price کا اندازہ لگانے کو levels پر walk کریں۔

حصہ 6: آرڈر بک پڑھنا

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

آرڈر بکس بطور ترتیب شدہ arrays واپس کی جاتی ہیں (bids نزولی، asks صعودی)۔ ہر سطح میں price اور size ہوتا ہے۔ بڑے آرڈر کے لیے سلپیج کا اندازہ لگانے کے لیے، بک میں آگے بڑھیں اور notional کو جمع کریں یہاں تک کہ آپ اپنے ہدف کے size کو consume کر لیں۔

GTC آرڈر بک پر برقرار رہتا ہے، GTD timestamp پر خود بخود منسوخ ہو جاتا ہے، FOK کو مکمل size fill یا cancel درکار ہوتا ہے، FAK limit پر جتنا ہو سکے لیتا ہے اور باقی منسوخ کر دیتا ہے۔

حصہ 7: آرڈرز لگانا

حدی آرڈر (GTC - ڈیفالٹ)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # حصص، ڈالر نہیں۔ 100 حصص @ $0.45 = $45 زیادہ سے زیادہ لاگت۔
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

create_order کال آپ کی پرائیویٹ key کے ساتھ EIP-712 ساختہ پیغام پر دستخط کرتی ہے۔ post_order اسے CLOB کو بھیجتا ہے۔ آپ کبھی بھی خام پرائیویٹ keys نیٹ ورک پر نہیں بھیجتے - صرف دستخط شدہ آرڈرز۔

آرڈر کی اقسام

منسوخ کرنا

# ایک آرڈر
client.cancel(order_id="0xabc...")

# کسی مخصوص مارکیٹ میں تمام آرڈرز منسوخ کریں
client.cancel_market_orders(market=market['conditionId'])

# آخری آپشن: سب کچھ منسوخ کریں
client.cancel_all()

حصہ 8: WebSocket اسٹریمنگ

ہر سیکنڈ Gamma کو پول کرنا بے کار ہے اور آپ جلد ہی rate limits سے ٹکرا جائیں گے۔ WebSocket فیڈ حقیقی وقت میں آرڈر بک اور ٹریڈ اپڈیٹس اسٹریمنگ کرتی ہے، sub-second latency کے ساتھ۔

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

دو فیڈز موجود ہیں: /market فیڈ (عوامی آرڈر بک + ٹریڈز) اور /user فیڈ (آپ کے اپنے آرڈر اور fill واقعات، authenticated)۔ پروڈکشن بوٹس عموماً دونوں سے کنیکٹ ہوتے ہیں، disconnect پر خودکار طور پر دوبارہ کنیکٹ ہوتے ہیں، اور موجودہ book state کے لیے WebSocket کو source of truth سمجھتے ہیں۔

حصہ 9: Rate Limits اور Backoff

جب آپ HTTP 429 تک پہنچتے ہیں، تو سرور Retry-After header واپس کرتا ہے۔ جٹر کے ساتھ exponential backoff نافذ کریں:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

حصہ 10: ایک حوالہ جاتی بوٹ آرکیٹیکچر

ہر مضبوط Polymarket بوٹ میں وہی چھ اجزاء ہوتے ہیں۔ ہر ایک کو اپنا الگ ماڈیول بنائیں؛ انہیں کم سے کم باہم منسلک رکھیں۔

حصہ 11: عام ناکامی کے طریقے

• Stale WebSocket data - ہر asset کے لیے آخری message کا وقت track کریں؛ اگر active market میں 30s سے زیادہ کوئی update نہ آئے تو REST refresh force کریں۔
• Nonce collisions - py-clob-client آپ کے لیے order nonces handle کرتا ہے، لیکن اگر آپ اپنا signer بنا رہے ہیں تو ہر order پر nonce increment کریں۔
• Insufficient balance - place کرنے سے پہلے ہمیشہ USDC balance چیک کریں؛ book آپ کا order دکھا سکتا ہے لیکن matching اسے reject کر دے گی۔
• Market paused or resolving - trading سے پہلے market.active && !market.closed چیک کریں۔ فیصلہ (resolution) کے آس پاس Gamma updates، CLOB سے چند سیکنڈ پیچھے ہو سکتی ہیں۔
• NegRisk adapter mismatch - کثیر نتیجہ مارکیٹس ایک الگ NegRisk adapter کے ذریعے route ہوتی ہیں۔ SDK اسے handle کرتا ہے، لیکن تصدیق کریں کہ آپ کا order صحیح venue پر گیا ہے۔

حصہ 12: API کے ذریعے Liquidity انعامات (rewards)

Polymarket عام liquidity rewards میں ~$5M/month اور sports-specific rewards میں $5M+/month چلاتا ہے (دیکھیے Liquidity Rewards)۔ اس کا بڑا حصہ API-driven market makers کی طرف جاتا ہے جو ہزاروں مارکیٹس میں تنگ دو طرفہ quotes برقرار رکھ سکتے ہیں۔

reward formula midpoint کے قریب orders، size، اور time-on-book کو reward کرتی ہے۔ ایک minimal market-making loop:

1. Target market کے لیے آرڈر بک (order book) پڑھیں
2. ایک fair midpoint نکالیں (مثلاً دونوں طرف top 3 levels کا VWAP)
3. mid − spread_target/2 پر bid اور mid + spread_target/2 پر ask پوسٹ کریں
4. ہر WebSocket update پر، اگر آپ کا quote target سے ایک tick سے زیادہ drift کرے تو repricing کریں
5. اگر book پتلا ہو جائے یا خبر آئے تو cancel کرکے exit کریں

حصہ 13: Production کی طرف جانا

• Hosting: $6/month کا VPS (Hetzner, DigitalOcean) Europe یا US-East میں زیادہ تر bots کے لیے کافی ہے۔ اگر آپ کو sub-10ms latency درکار ہو تو Polygon RPC کے ساتھ co-locate کریں۔
• RPC: قابلِ اعتماد Polygon RPC کے لیے Alchemy, Infura, یا QuickNode استعمال کریں۔ Free tiers اس وقت تک ٹھیک ہیں جب تک آپ فی منٹ سینکڑوں orders place نہ کرنے لگیں۔
• Monitoring: metrics کے لیے Prometheus + Grafana؛ alerts کے لیے Telegram bot۔ آپ جو بھی order ID بھیجیں اور جو بھی fill وصول کریں، سب log کریں۔
• Backups: ہر منٹ state محفوظ کریں۔ اگر VPS درمیان fill کے دوران مر جائے تو آپ seconds میں resume کرنا چاہیں گے، نہ کہ ہاتھ سے reconcile کرنا۔
• Tax: آپ کا logger آپ کا audit trail بھی ہے - دیکھیے Tax Guide۔

حصہ 14 - Polymarket API کے لیے validated pro tips

Situation → Action Cheat Sheet

اگلا کیا ہے؟

• اوزار اور وسائل - فریقِ ثالث ڈیش بورڈز، اینالیٹکس، اور ڈیٹا فیڈز جو API کی تکمیل کرتے ہیں
• جدید حکمتِ عملیاں - ملٹی لیگ آربٹریج اور آپشنز جیسی ساختیں جو بوٹس کے لیے موزوں ہیں
• لیکویڈیٹی انعامات - مارکیٹ میکنگ ریبیٹس کمانے کے درست فارمولے
• آرڈر بک گائیڈ - اس پر کوڈ لکھنے سے پہلے بک کو پڑھنے کے لیے گہری سمجھ
• لغت - اس گائیڈ میں موجود ہر اصطلاح کی سادہ انگریزی میں تعریفیں