Polymarket API गाइड: CLOB, REST और ट्रेडिंग बॉट्स (2026)

अध्याय 27 of 33

संक्षिप्त संस्करण

Polymarket तीन सार्वजनिक APIs प्रदान करता है: CLOB (ट्रेडिंग), Gamma (मार्केट खोज), और Data (एनालिटिक्स)। आधिकारिक Python SDK py-clob-client 0.34.6 है। प्रमाणीकरण API key + ECDSA signature का उपयोग करता है, और ऑर्डर EIP-712 के माध्यम से Polygon प्रॉक्सी वॉलेट से साइन किए जाते हैं। रेट लिमिट्स आपको प्रति key लगभग 60 orders/minute तक सीमित करती हैं। नए डेवलपर्स के लिए सबसे बड़ा अड़चन condition_id → token_id mapping समस्या है जो Gamma और CLOB के बीच होती है - पहले इसे हल करें, और बाकी सब अपने आप ठीक हो जाएगा। लगभग $40M/month की लिक्विडिटी (liquidity) रिवॉर्ड्स (rewards) और bot-captured spread Polymarket पर अर्जित की जाती है, और यह लगभग पूरी तरह API users द्वारा होता है।

तीन अलग सेवाएँ: ट्रेडिंग के लिए CLOB (9,000/10s auth), discovery के लिए Gamma (4,000/10s public), ऐतिहासिक एनालिटिक्स के लिए Data (1,000/10s public)।

भाग 1: तीन APIs

Polymarket तीन अलग-अलग सेवाओं में जिम्मेदारियों को साफ़-साफ़ अलग करता है। हर काम के लिए सही API का उपयोग आपके बॉट को तेज़, सरल, और rate limits के भीतर रखता है।

एक सामान्य बॉट लूप Gamma का उपयोग मार्केट खोजने के लिए, CLOB का उपयोग ऑर्डर बुक फ़ेच करने और ट्रेड लगाने के लिए, और Data का उपयोग ऑफ़लाइन रणनीति प्रदर्शन का बैक-टेस्ट करने के लिए करता है। Gamma को "कैटलॉग," CLOB को "एक्सचेंज," और Data को "वेयरहाउस" के रूप में समझें।

L1, chainId 137 के साथ "ClobAuthDomain" EIP-712 struct पर साइन करता है ताकि credentials निकाले जा सकें। L2 HMAC-SHA256 POLY_SIGNATURE headers के साथ हर अगला अनुरोध साइन करता है।

भाग 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 खातों के लिए signature type 1 (POLY_PROXY), browser-wallet proxies के लिए type 2 (GNOSIS_SAFE), direct keys के लिए type 0 (EOA)। types 1 और 2 के लिए Funder आवश्यक है।

भाग 3: py-clob-client इंस्टॉल करना

आधिकारिक Python SDK शून्य से पहली ऑर्डर तक पहुंचने का सबसे तेज़ तरीका है। हम संस्करण 0.34.6 का उपयोग करेंगे, जो अप्रैल 2026 तक वर्तमान है।

# पहले एक virtual environment बनाएं
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 credentials derive करें और cache करें
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() कॉल आपके private key से एक message पर sign करती है और बदले में आपको एक API key, secret, और passphrase देती है। पहली run के बाद इन्हें अपने .env में cache करें ताकि हर startup पर आपको derive endpoint hit न करना पड़े।

Gamma /markets outcomePrices, clobTokenIds, volume24hr, tags लौटाता है। default bot scanner query के रूप में tag_slug + order=volume24hr का उपयोग करें।

भाग 4: Gamma के माध्यम से मार्केट्स ढूँढ़ना

ट्रेड करने से पहले, आपको ट्रेड करने योग्य मार्केट्स ढूँढ़ने होते हैं। Gamma JSON लौटाता है जिसमें वह सब कुछ होता है जो Polymarket UI दिखाता है: प्रश्न, परिणाम, कीमतें, 24h वॉल्यूम, समाप्ति, टैग, और इमेजें।

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 क्वेरी पैरामीटर

Gamma conditionId को उजागर करता है (प्रति मार्केट एक); CLOB token_id पर ट्रेड करता है (प्रति परिणाम एक)। clobTokenIds एक JSON-एन्कोडेड स्ट्रिंग ऐरे है जो परिणामों के साथ इंडेक्स-मैच्ड है।

भाग 5: condition_id → token_id मैपिंग

यह Polymarket बॉट डेवलपमेंट में #1 परेशानी का बिंदु है। Gamma एक condition_id लौटाता है (प्रति मार्केट एक)। CLOB ट्रेड्स एक token_id का उपयोग करते हैं (प्रति outcome एक)। आपको हमेशा दोनों की जरूरत होती है।

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # पहला outcome
no_token = token_ids[1] # दूसरा outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Outcome क्रम की अड़चन

Gamma का outcomes array और clobTokenIds array index के हिसाब से matched होते हैं। हमेशा outcome label पढ़ें, यह मानकर न चलें कि index 0 "Yes" है। बहु-परिणाम बाज़ारों (NegRisk, Oscars, elections) में, index 0 "Kamala Harris" या "Taylor Swift" हो सकता है - order deterministic है, लेकिन market-specific है।

Book bids descending और asks ascending के रूप में लौटता है। market-like FAK भेजने से पहले किसी भी target notional के लिए fill price का अनुमान लगाने हेतु levels से होकर जाएं।

भाग 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}")

ऑर्डर बुक्स को क्रमबद्ध ऐरे के रूप में लौटाया जाता है (bids अवरोही, asks आरोही)। हर स्तर में price और size होता है। बड़े ऑर्डर के लिए स्लिपेज का अनुमान लगाने के लिए, बुक पर आगे बढ़ें और नॉटिओनल को तब तक जोड़ते रहें जब तक आपने अपना लक्षित आकार उपभोग न कर लिया हो।

GTC बुक पर बना रहता है, GTD टाइमस्टैम्प पर स्वतः रद्द हो जाता है, FOK के लिए पूरा आकार भरना या रद्द करना आवश्यक है, FAK लिमिट पर जितना हो सके उतना लेता है और बाकी रद्द कर देता है।

भाग 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 कॉल आपकी निजी कुंजी के साथ EIP-712 संरचित संदेश पर हस्ताक्षर करता है। post_order इसे CLOB पर सबमिट करता है। आप कभी भी कच्ची निजी कुंजियाँ नेटवर्क पर नहीं भेजते - केवल हस्ताक्षरित ऑर्डर।

ऑर्डर के प्रकार

रद्द करना

# एकल ऑर्डर
client.cancel(order_id="0xabc...")

# किसी विशिष्ट मार्केट पर सभी ऑर्डर रद्द करें
client.cancel_market_orders(market=market['conditionId'])

# अंतिम उपाय: सब कुछ रद्द करें
client.cancel_all()

भाग 8: WebSocket स्ट्रीमिंग

हर सेकंड Gamma को पोल करना बेकार है और आप जल्दी ही रेट लिमिट्स पर पहुंच जाएंगे। WebSocket फ़ीड रीयल-टाइम ऑर्डर बुक और ट्रेड अपडेट्स, सब-सेकंड लेटेंसी के साथ, स्ट्रीम करती है।

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). प्रोडक्शन बॉट्स आमतौर पर दोनों से कनेक्ट होते हैं, डिस्कनेक्ट होने पर स्वतः reconnect करते हैं, और WebSocket को वर्तमान बुक स्थिति के लिए सत्य का स्रोत मानते हैं।

भाग 9: रेट लिमिट्स और बैकऑफ़

जब आपको 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 बॉट के छह ही घटक होते हैं। हर एक को अपना अलग मॉड्यूल बनाइए; उन्हें ढीले रूप से coupled रखें।

भाग 11: आम विफलता मोड

• पुराना WebSocket डेटा - हर asset के लिए आख़िरी संदेश का समय ट्रैक करें; अगर किसी active market पर >30s तक कोई अपडेट न मिले, तो REST refresh ज़बरदस्ती करें।
• Nonce collisions - py-clob-client आपके लिए order nonces संभालता है, लेकिन अगर आप अपना signer बना रहे हैं, तो हर order पर nonce बढ़ाएँ।
• अपर्याप्त बैलेंस - place करने से पहले हमेशा USDC balance जाँचें; book में आपका order दिख सकता है लेकिन matching उसे reject कर देगी।
• बाज़ार paused या resolving हो रहा है - ट्रेड करने से पहले market.active && !market.closed जाँचें। रिज़ॉल्यूशन (resolution) के आसपास Gamma अपडेट CLOB से कुछ सेकंड पीछे रह सकते हैं।
• NegRisk adapter mismatch - बहु-परिणाम बाज़ार अलग NegRisk adapter से route होते हैं। SDK इसे संभालता है, लेकिन पुष्टि करें कि आपका order सही venue पर गया।

भाग 12: API के माध्यम से लिक्विडिटी रिवॉर्ड्स

Polymarket सामान्य लिक्विडिटी रिवॉर्ड्स में ~$5M/month और खेल-विशिष्ट रिवॉर्ड्स में $5M+/month चलाता है (देखें लिक्विडिटी रिवॉर्ड्स)। इसका विशाल बहुमत API-driven market makers को जाता है जो हज़ारों बाज़ारों में tight दो-तरफ़ा quotes बनाए रख सकते हैं।

रिवॉर्ड फ़ॉर्मूला midpoint के पास के orders, size, और time-on-book को reward करता है। एक न्यूनतम market-making loop:

1. लक्षित बाज़ार के लिए ऑर्डर बुक (order book) पढ़ें
2. एक उचित midpoint निकालें (जैसे, दोनों तरफ़ के शीर्ष 3 levels का VWAP)
3. mid - spread_target/2 पर एक bid और mid + spread_target/2 पर एक ask post करें
4. हर WebSocket update पर, अगर आपका quote target से एक tick से अधिक drift करे तो repricing करें
5. अगर book पतला हो जाए या कोई news break हो, तो cancel करें और बाहर निकलें

भाग 13: Production में जाना

• Hosting: यूरोप या US-East में $6/month का VPS (Hetzner, DigitalOcean) अधिकतर bots के लिए काफ़ी है। अगर आपको sub-10ms latency चाहिए, तो Polygon RPC के साथ co-locate करें।
• RPC: भरोसेमंद Polygon RPC के लिए Alchemy, Infura, या QuickNode का उपयोग करें। Free tiers तब तक ठीक हैं जब तक आप प्रति मिनट सैकड़ों orders नहीं लगाते।
• Monitoring: metrics के लिए Prometheus + Grafana; alerts के लिए Telegram bot। आप जो भी order ID भेजें और जो भी fill प्राप्त करें, सब log करें।
• Backups: हर मिनट state persist करें। अगर VPS बीच में fill के दौरान मर जाए, तो आप चाहते हैं कि कुछ सेकंड में resume हो जाए, न कि हाथ से reconcile करना पड़े।
• Tax: आपका logger आपका audit trail भी है - देखें Tax Guide।

भाग 14 - Polymarket API के लिए सत्यापित Pro Tips

स्थिति → कार्रवाई चीट शीट

आगे क्या?

• टूल्स & संसाधन - तृतीय-पक्ष डैशबोर्ड, एनालिटिक्स, और डेटा फ़ीड्स जो API को पूरक करते हैं
• उन्नत रणनीतियाँ - मल्टी-लेग आर्बिट्राज और बॉट्स के लिए उपयुक्त विकल्प-जैसी संरचनाएँ
• लिक्विडिटी रिवार्ड्स - मार्केट-मेकिंग रिबेट्स कमाने के लिए सटीक फ़ॉर्मूले
• ऑर्डर बुक गाइड - उस पर कोड करने से पहले ऑर्डर बुक पढ़ने के लिए गहरी समझ
• शब्दावली - इस गाइड के हर शब्द की सरल अंग्रेज़ी में परिभाषाएँ