Polymarket Gamma API: Events, Markets, Tags, Pagination

Polymarket Bot Tutorial · Sura ya 7 kati ya 32

Polymarket Gamma API deep dive: /events na /markets endpoints, pagination, tag IDs (864 Tennis, 745 NBA, n.k.), kuchuja kwa 24h volume, rate limits, na Python na Node code samples.

Na Harley Young, mwandishi mkuu wa Polymarkets.co.il. Marekebisho ya mwisho: Mei 2026.

Sura hii inafunika nini

Gamma ni catalog API ya Polymarket - inaorodhesha kila event, kila market, tag, image, na resolved outcome ambazo front-end inaonyesha. CLOB API inafanya trades; Gamma inadescribe kile kinachoweza ku-tradedwa. Bot bugs nyingi katika discovery layer zinatoka kwa kuchanganya zote mbili, au kwa kukosa pagination contract. Sura hii ni field reference kwa endpoints kuu za Gamma na exact parameter behavior ambayo production fetchers zetu zinategemea.

• Gamma vs CLOB: lini kutumia ipi
• /events endpoint anatomy
• /markets endpoint anatomy
• Tags na tag IDs (orodha iliyothibitishwa)
• Kuchuja: active, closed, volume24hr ordering
• Pagination na limits
• Rate limits na caching
• Code: fetch top 24h-volume markets

Gamma vs CLOB: lini kutumia ipi

Services mbili tofauti kwa kazi mbili tofauti.

Gamma (gamma-api.polymarket.com): catalog. Inaorodhesha events, markets, tags, descriptions, images, resolved outcomes, 24-hour volume, total volume, end dates. Read-only HTTP. Hakuna authentication inayohitajika kwa reads nyingi. Inaupdate kwa kuendelea lakini eventually consistent - market iliyofungwa hivi karibuni inaweza bado kuonyesha closed: false kwa sekunde chache.

CLOB (clob.polymarket.com): trading + order book. Inaorodhesha current best bid/ask, top-N book depth, recent trades. Iliyoauthenticate kwa write endpoints (order placement, cancellation). Real-time WebSocket channels zinapatikana kwa book updates.

Kanuni ya kidole gumba: tumia Gamma kupata cha kufanya trade; tumia CLOB kuitrade. Bot inayosoma prices kutoka Gamma inatumia stale data - price fields za Gamma zinaupdate mara chache kuliko CLOB order book. Bot inayosoma market metadata kutoka CLOB inafanya requests nyingi zaidi kuliko zinazohitajika.

/events endpoint anatomy

GET /events inarudisha event-level data. "Event" ni Polymarket page; event moja inaweza kuwa na markets nyingi (mfano 2024 Presidential Election event ina market moja kwa kila mgombea).

Fields muhimu:

• slug: URL-safe identifier, thabiti kwa maisha ya event.
• title, description: human display.
• endDate (ISO 8601): wakati event inafunga.
• active, closed: booleans; changanya katika query na ?active=true&closed=false kwa live events.
• volume, volume24hr: USD totals.
• tags: array ya tag objects (angalia tags section hapa chini).
• markets: array ya child market objects (angalia /markets anatomy).

Discovery pattern moja ya kawaida zaidi: GET /events?active=true&closed=false&order=volume24hr&ascending=false&limit=100. Inarudisha events 100 za juu zaidi za volume zinazoendesha hivi sasa.

/markets endpoint anatomy

GET /markets inarudisha market-level data. Market ni contract moja Y/N au multi-outcome; inaishi ndani ya event.

Fields muhimu:

• slug: URL-safe identifier.
• question: title inayoonyeshwa kwenye trading page (mfano "Will Trump be president on January 1, 2027?").
• outcomes: JSON string ya outcome names, mfano '["Yes","No"]'. Daima elements mbili kwa binary; zaidi kwa NegRisk.
• outcomePrices: JSON string ya current prices kama decimals, mfano '["0.62","0.38"]'. Pande zote mbili zinajumlisha hadi ~1.0 minus spread.
• clobTokenIds: JSON string ya ERC-1155 token IDs zilizolinganishwa na outcomes. Hizi ni tokens unazonunua/kuuza kweli.
• negRisk: boolean; true kwa multi-outcome sum-to-1 markets. Inajali kwa order placement (sura ya 11).

Fields za outcomes / outcomePrices / clobTokenIds zinafika kama JSON strings, sio parsed arrays - JSON-decode kabla ya kuzitumia.

Tags na tag IDs (orodha iliyothibitishwa)

Tags ni categorical labels (Sports, Crypto, Tennis, NBA, n.k.). Production tag IDs zilizothibitishwa kwa categories zinazotumiwa zaidi:

Chuja na tag na ?tag_id=745 kwa tag maalum, au ?tag_slug=nba kutumia slug. Slug-based filtering ni readable zaidi katika code lakini polepole kidogo; ID-based ni production default.

Kuchuja: active, closed, volume24hr ordering

Filter dimensions nne utakazotumia 95% ya muda.

• active=true|false: true inaexclude markets ambazo Polymarket team imeficha kutoka UI.
• closed=true|false: false inaexclude resolved markets. Combination active=true&closed=false ni live filter ya kawaida zaidi.
• order=volume24hr, order=volume, order=endDate: sort key. Muhimu zaidi ni volume24hr kwa kupata currently-active markets.
• ascending=true|false: default true kwa endpoints nyingi; karibu daima unataka false kwa volume orderings.

Caveat: kuchuja kwa tag_id ikichanganywa na order=volume24hr na ascending=false mara nyingine inarudisha empty page wakati tag ina live markets chache sana. Daima over-fetch (request zaidi ya unayoonyesha) na post-filter ku-handle hii.

Pagination na limits

limit param inakubali 1-500 kwa call. Default ni 100 ikiwa haijaspecify. Juu ya 500 server inacap silently - unapokea 500 lakini response haina indication ya zaidi.

Pagination ni offset-based: ?limit=500&offset=500 kwa page ya pili. Hakuna cursor-based pagination, kwa hivyo concurrent inserts inaweza kusababisha page boundaries kuhama kati ya calls. Kwa bot discovery purposes nyingi hii ni acceptable; kwa archive scrapes, sort na stable field (endDate au createdAt) na detect overlap kwa slug.

Practical pattern kwa "live markets zote": fetch limit=500&order=volume24hr&ascending=false. Hiyo inafunika top 500 kwa volume ambayo essentially ni kila market yenye non-trivial activity. Kwenda zaidi ya page 1 mara chache inafaa - markets katika tail ya volume distribution ni by definition sio mahali action ipo.

Rate limits na caching

Gamma inafrontiwa na Cloudflare na ina soft rate limits per IP. Empirical thresholds zilizoobserved chini ya production load:

• Hadi ~30 req/sec kutoka IP moja sustained: sawa.
• Bursts za 100+ req/sec: mara kwa mara 429s, retries zinashinda.
• ~500 req/sec sustained: rate-limit page au temporary block (10-60s).

Published response headers zinajumuisha Cache-Control values za 30-60 sekunde kwa endpoints nyingi. Heshimu - hakuna faida kufetch event ile ile mara 10 kwa dakika. Production caching pattern: in-process LRU + TTL keyed kwenye full URL, 30s TTL. Inahifadhi request count na inapunguza latency.

Kwa high-frequency strategies, mirror Gamma data kwenda kwa local store iliyoupdateiwa na fetcher process moja; kuwa na consumers wengi wakisoma kutoka kwa store hiyo. Fetcher moja × consumers wengi > fetchers wengi × Gamma.

Code: fetch top 24h-volume markets

Reference fetcher katika lugha tatu, inarudisha top 50 live markets kwa 24-hour volume.

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 HAIRUHUSU free-text search parameter - kuongeza ?q=foo au ?search=foo silently inarudisha default ordering. Chuja kwa slug au tag badala yake.

Maswali yanayoulizwa mara kwa mara