Polymarket Gamma API: Events, Markets, Tags, Pagination

Polymarket Bot Tutorial · Chapter 7 of 32

Polymarket Gamma API کی گہری سمجھ: /events اور /markets endpoints، pagination، tag IDs (864 Tennis، 745 NBA، وغیرہ)، 24h volume کے حساب سے filtering، rate limits، اور Python اور Node code samples۔

تحریر: ہارلی ینگ، Polymarkets.co.il کی مرکزی مصنفہ۔ آخری جائزہ: مئی 2026۔

اس chapter میں کیا شامل ہے

Gamma Polymarket کی catalog API ہے - یہ ہر event، ہر market، tag، image، اور resolved outcome کی فہرست دیتی ہے جو front-end دکھاتا ہے۔ CLOB API trading کے لیے ہے؛ Gamma اس بات کی وضاحت کرتی ہے کہ کیا tradeable ہے۔ discovery layer میں زیادہ تر bot bugs دونوں کو آپس میں mix کرنے یا pagination contract miss کرنے کی وجہ سے آتے ہیں۔ یہ chapter Gamma کے main endpoints کے لیے field reference ہے، exact parameter behavior کے ساتھ جس پر ہمارے production fetchers depend کرتے ہیں۔

• Gamma بمقابلہ 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، دو مختلف کاموں کے لیے۔

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 update ہوتی ہے لیکن 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 دستیاب ہیں۔

انگوٹھے کا اصول: trade تلاش کرنے کے لیے Gamma استعمال کریں؛ اسے trade کرنے کے لیے CLOB استعمال کریں۔ جو bot prices Gamma سے پڑھتا ہے وہ 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 کی زندگی بھر stable رہتا ہے۔
• title، description: human display کے لیے۔
• endDate (ISO 8601): event کب close ہوگا۔
• active، closed: booleans؛ live events کے لیے query میں ?active=true&closed=false کے ساتھ combine کریں۔
• volume، volume24hr: USD totals۔
• tags: tag objects کی array (نیچے tags section دیکھیں)۔
• markets: child market objects کی array ( /markets anatomy دیکھیں)۔

سب سے عام discovery pattern: GET /events?active=true&closed=false&order=volume24hr&ascending=false&limit=100۔ یہ 100 سب سے زیادہ volume والے موجودہ 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 کے لیے ہمیشہ دو elements؛ NegRisk کے لیے زیادہ۔
• outcomePrices: current prices کی JSON string decimals میں، مثلاً '["0.62","0.38"]'۔ دونوں sides spread کے بعد تقریباً 1.0 بنتی ہیں۔
• 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، وغیرہ)۔ سب سے زیادہ استعمال ہونے والی categories کے verified production tag IDs:

کسی specific tag کے لیے ?tag_id=745 سے filter کریں، یا slug کے ذریعے ?tag_slug=nba استعمال کریں۔ Slug-based filtering code میں زیادہ readable ہوتا ہے لیکن تھوڑا slower ہے؛ ID-based production default ہے۔

Filtering: active، closed، volume24hr ordering

چار filtering dimensions جنہیں آپ 95% وقت استعمال کریں گے۔

• active=true|false: true ان markets کو exclude کرتا ہے جنہیں Polymarket ٹیم نے UI سے hide کیا ہوتا ہے۔
• closed=true|false: false resolved markets کو exclude کرتا ہے۔ active=true&closed=false کا combination سب سے عام live filter ہے۔
• order=volume24hr، order=volume، order=endDate: sort key۔ currently-active markets ڈھونڈنے کے لیے سب سے مفید volume24hr ہے۔
• ascending=true|false: زیادہ تر endpoints پر default true ہوتا ہے؛ volume orderings کے لیے آپ تقریباً ہمیشہ false چاہتے ہیں۔

نوٹ: tag_id کے ساتھ order=volume24hr اور ascending=false لگانے پر کبھی کبھی empty page آ سکتی ہے جب tag کے live markets بہت کم ہوں۔ ہمیشہ over-fetch کریں (جو دکھانا ہے اس سے زیادہ request کریں) اور اس کا حل post-filtering کے ذریعے کریں۔

Pagination اور limits

limit param ہر call پر 1-500 تک قبول کرتا ہے۔ اگر specify نہ کیا جائے تو default 100 ہے۔ 500 سے اوپر server silently cap کر دیتا ہے - آپ کو 500 ملتے ہیں لیکن response میں مزید ہونے کی کوئی indication نہیں ہوتی۔

Pagination offset-based ہے: دوسری page کے لیے ?limit=500&offset=500۔ Cursor-based pagination موجود نہیں، اس لیے concurrent inserts سے page boundaries calls کے درمیان shift ہو سکتی ہیں۔ bot discovery کے زیادہ تر مقاصد کے لیے یہ قابلِ قبول ہے؛ archive scrapes کے لیے stable field (endDate یا createdAt) کے حساب سے sort کریں اور slug کے ذریعے overlap detect کریں۔

"all live markets" کے لیے عملی pattern: limit=500&order=volume24hr&ascending=false fetch کریں۔ یہ volume کے لحاظ سے top 500 کو cover کرتا ہے، یعنی تقریباً ہر وہ market جس میں کوئی meaningful activity ہو۔ page 1 سے آگے جانا شاذ و نادر ہی مفید ہوتا ہے - volume distribution کے tail میں موجود markets تعریفاً وہ جگہ نہیں جہاں action ہوتا ہے۔

Rate limits اور caching

Gamma Cloudflare کے ذریعے fronted ہے اور 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 کو ایک منٹ میں 10 بار دوبارہ fetch کرنے کا کوئی فائدہ نہیں۔ Production caching pattern: in-process LRU + TTL، full URL کے ساتھ keyed، 30s TTL۔ اس سے request count کم ہوتی ہے اور latency گھٹتی ہے۔

ہائی فریکوئنسی strategies کے لیے Gamma data کو ایک local store میں mirror کریں جسے ایک single fetcher process update کرے؛ متعدد consumers اسی store سے پڑھیں۔ ایک fetcher × many consumers > many fetchers × Gamma۔

Code: top 24h-volume markets fetch کریں

تین languages میں 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 کریں۔

اکثر پوچھے جانے والے سوالات