Polymarket Bot Tutorial · Chapter 7 of 32
Polymarket Gamma API की गहराई से समझ: /events और /markets endpoints, pagination, tag IDs (864 Tennis, 745 NBA, etc), 24h volume के आधार पर filtering, rate limits, और Python तथा Node code samples.
यह अध्याय क्या कवर करता है
Gamma, Polymarket की catalog API है - यह हर event, हर market, tag, image, और resolved outcome की सूची देती है जिसे front-end दिखाता है। CLOB API ट्रेडिंग के लिए है; Gamma यह बताती है कि क्या tradeable है। Discovery layer पर bot bugs का सबसे आम कारण इन दोनों को confuse करना, या pagination contract को miss करना होता है। यह अध्याय Gamma के मुख्य endpoints के लिए field reference है, जिसमें exact parameter behavior शामिल है जिस पर हमारे production fetchers निर्भर करते हैं।
- Gamma vs CLOB: कब किसका उपयोग करें
- /events endpoint anatomy
- /markets endpoint anatomy
- Tags और tag IDs (verified list)
- Filtering: active, closed, volume24hr ordering
- Pagination और limits
- Rate limits और caching
- Code: top 24h-volume markets fetch करें
Gamma vs CLOB: कब किसका उपयोग करें
दो अलग services, दो अलग jobs के लिए।
Gamma (gamma-api.polymarket.com): catalog. Events, markets, tags, descriptions, images, resolved outcomes, 24-hour volume, total volume, end dates की सूची देती है। Read-only HTTP. अधिकांश reads के लिए authentication की आवश्यकता नहीं होती। Continuously updated होती है लेकिन eventually consistent है - अभी-अभी closed हुआ market कुछ seconds तक closed: false दिखा सकता है।
CLOB (clob.polymarket.com): trading + order book. Current best bid/ask, top-N book depth, recent trades की सूची देती है। Write endpoints (order placement, cancellation) के लिए authenticated होती है। Book updates के लिए real-time WebSocket channels उपलब्ध हैं।
Thumb rule: क्या trade करना है, यह जानने के लिए Gamma का उपयोग करें; इसे trade करने के लिए CLOB का उपयोग करें। जो bot Gamma से prices पढ़ता है, वह stale data इस्तेमाल कर रहा है - Gamma के price fields, CLOB के order book की तुलना में कम frequency से update होते हैं। जो bot market metadata के लिए CLOB पढ़ता है, वह ज़रूरत से ज़्यादा requests कर रहा है।
/events endpoint anatomy
GET /events event-level data लौटाता है। एक "event" Polymarket का एक page होता है; एक single event में multiple markets हो सकते हैं (जैसे 2024 Presidential Election event में हर candidate के लिए एक market होता है)।
मुख्य fields:
slug: URL-safe identifier, event की life तक stable रहता है।title,description: human display के लिए।endDate(ISO 8601): event कब close होता है।active,closed: booleans; live events के लिए query में?active=true&closed=falsecombine करें।volume,volume24hr: USD totals।tags: tag objects की array (नीचे tags section देखें)।markets: child market objects की array (/marketsanatomy देखें)।
सबसे common discovery pattern: GET /events?active=true&closed=false&order=volume24hr&ascending=false&limit=100. यह 100 highest-volume currently-live events लौटाता है।
/markets endpoint anatomy
GET /markets market-level data लौटाता है। एक market एक Y/N या multi-outcome contract होता है; यह एक event के अंदर रहता है।
मुख्य fields:
slug: URL-safe identifier.question: trading page पर दिखने वाला title (उदाहरण: "Will Trump be president on January 1, 2027?").outcomes: outcome names का JSON string, जैसे'["Yes","No"]'. Binary markets के लिए हमेशा two elements होते हैं; NegRisk के लिए इससे ज़्यादा।outcomePrices: current prices का JSON string as decimals, जैसे'["0.62","0.38"]'. दोनों sides मिलकर ~1.0 से थोड़ा कम, spread के कारण।clobTokenIds: outcomes के साथ aligned ERC-1155 token IDs का JSON string. यही tokens आप वास्तव में buy/sell करते हैं।negRisk: boolean; multi-outcome sum-to-1 markets के लिए true. Order placement में इसका महत्व है (chapter 11)।
outcomes / outcomePrices / clobTokenIds fields JSON strings के रूप में आते हैं, parsed arrays के रूप में नहीं - उपयोग करने से पहले JSON-decode करें।
Tags और tag IDs (verified list)
Tags categorical labels होते हैं (Sports, Crypto, Tennis, NBA, etc.). सबसे ज़्यादा इस्तेमाल होने वाली categories के verified production tag IDs:
| Tag | ID | Tag | ID |
|---|---|---|---|
| Sports | 1 | NBA | 745 |
| Crypto | 21 | NFL | 450 |
| Politics | 2 | Tennis | 864 |
| Bitcoin | 100196 | Esports | 702 |
| Ethereum | 100383 | Soccer | 1059 |
| Election | 3 | EPL | 739 |
| Middle East | 1432 | UCL | 2186 |
किसी specific tag के लिए ?tag_id=745 से filter करें, या slug का उपयोग करते हुए ?tag_slug=nba से। Slug-based filtering code में ज़्यादा readable है लेकिन थोड़ी धीमी है; ID-based production default है।
Filtering: active, closed, volume24hr ordering
चार filtering dimensions जिनका आप 95% समय उपयोग करेंगे।
active=true|false:trueउन markets को exclude करता है जिन्हें Polymarket टीम ने UI से hide किया है।closed=true|false:falseresolved markets को exclude करता है।active=true&closed=falseका combination सबसे common live filter है।order=volume24hr,order=volume,order=endDate: sort key। Live markets ढूँढने के लिए सबसे उपयोगीvolume24hrहै।ascending=true|false: अधिकांश endpoints पर default true होता है; volume ordering के लिए लगभग हमेशा आपकोfalseचाहिए।
Caveat: tag_id के साथ order=volume24hr और ascending=false कभी-कभी empty page लौटाता है जब tag में बहुत कम live markets होते हैं। हमेशा over-fetch करें (जितना display करना है उससे ज़्यादा request करें) और इसे handle करने के लिए post-filter करें।
Pagination और limits
limit param प्रति call 1-500 स्वीकार करता है। अगर specify न करें तो default 100 है। 500 से ऊपर server silently cap कर देता है - आपको 500 मिलता है लेकिन response में अधिक होने का कोई संकेत नहीं होता।
Pagination offset-based है: दूसरे page के लिए ?limit=500&offset=500. Cursor-based pagination नहीं है, इसलिए concurrent inserts के कारण page boundaries calls के बीच shift हो सकती हैं। अधिकांश bot discovery purposes के लिए यह स्वीकार्य है; archive scrapes के लिए किसी stable field (endDate या createdAt) के अनुसार sort करें और slug के द्वारा overlap detect करें।
"all live markets" के लिए practical pattern: limit=500&order=volume24hr&ascending=false fetch करें। यह volume के हिसाब से top 500 को cover करता है, जो essentially हर वह market है जिसमें meaningful activity है। page 1 से आगे जाना rarely useful होता है - volume distribution की tail में मौजूद markets definition के अनुसार वही जगह नहीं होती जहाँ action है।
Rate limits और caching
Gamma के आगे Cloudflare लगा है और इसमें IP के हिसाब से soft rate limits हैं। production load के तहत देखी गई empirical thresholds:
- एक IP से ~30 req/sec तक sustained: ठीक।
- 100+ req/sec के bursts: कभी-कभी 429s, retries सफल हो जाते हैं।
- ~500 req/sec sustained: rate-limit page या temporary block (10-60s)।
Published response headers में अधिकांश endpoints के लिए Cache-Control values 30-60 seconds की होती हैं। उनका सम्मान करें - एक ही event को एक minute में 10 बार फिर से fetch करने का कोई लाभ नहीं है। Production caching pattern: full URL पर keyed in-process LRU + TTL, 30s TTL। यह request count बचाता है और latency कम करता है।
High-frequency strategies के लिए Gamma data को एक local store में mirror करें, जिसे एक single fetcher process update करे; multiple consumers उस store से read करें। One fetcher × many consumers > many fetchers × Gamma.
Code: top 24h-volume markets fetch करें
तीन भाषाओं में reference fetcher, जो 24-hour volume के आधार पर top 50 live markets लौटाता है।
Python:
import requests
r = requests.get("https://gamma-api.polymarket.com/events",
params={"active":"true","closed":"false",
"order":"volume24hr","ascending":"false","limit":50},
timeout=10)
for ev in r.json()[:50]:
print(ev["slug"], ev.get("volume24hr"))Node:
const url = "https://gamma-api.polymarket.com/events?active=true&closed=false" +
"&order=volume24hr&ascending=false&limit=50";
const events = await fetch(url).then(r => r.json());
for (const ev of events) console.log(ev.slug, ev.volume24hr);Curl:
curl -s "https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume24hr&ascending=false&limit=50" \
| jq '.[].slug'Polymarket gamma /events endpoint free-text search parameter support नहीं करता - ?q=foo या ?search=foo जोड़ने पर भी silently default ordering ही लौटती है। इसके बजाय slug या tag से filter करें।
