Polymarket Gamma API: Events, Markets, Tags, Pagination

Polymarket Bot Tutorial · Kabanata 7 ng 32

Polymarket Gamma API deep dive: /events at /markets endpoints, pagination, tag IDs (864 Tennis, 745 NBA, atbp), pag-filter ayon sa 24h volume, rate limits, at Python at Node code samples.

Ni Harley Young, pangunahing manunulat sa Polymarkets.co.il. Huling rebyu: Mayo 2026.

Ano ang sinasaklaw ng kabanatang ito

Ang Gamma ay catalog API ng Polymarket - naglilista nito ng bawat event, bawat market, tag, image, at resolved outcome na ipinapakita ng front-end. Ang CLOB API ay nag-trade; ang Gamma ay naglalarawan kung ano ang tradeable. Karamihan ng bot bugs sa discovery layer ay nanggagaling sa pagkalito ng dalawa, o mula sa pagkawala ng pagination contract. Ang kabanatang ito ay ang field reference para sa mga pangunahing endpoints ng Gamma na may eksaktong parameter behavior na inaasahan ng aming production fetchers.

• Gamma vs CLOB: kailan gamitin alin
• /events endpoint anatomy
• /markets endpoint anatomy
• Tags at tag IDs (verified list)
• Pag-filter: active, closed, volume24hr ordering
• Pagination at limits
• Rate limits at caching
• Code: fetch top 24h-volume markets

Gamma vs CLOB: kailan gamitin alin

Dalawang magkaibang services para sa dalawang magkaibang trabaho.

Gamma (gamma-api.polymarket.com): catalog. Naglilista ng events, markets, tags, descriptions, images, resolved outcomes, 24-hour volume, total volume, end dates. Read-only HTTP. Walang authentication na kinakailangan para sa karamihan ng reads. Patuloy na na-uupdate pero eventually consistent - ang market na kasalimukan lumampas ay maaaring magpakita pa rin ng closed: false para sa ilang segundo.

CLOB (clob.polymarket.com): trading + order book. Naglilista ng kasalukuyang best bid/ask, top-N book depth, recent trades. Authenticated para sa write endpoints (order placement, cancellation). Real-time WebSocket channels available para sa book updates.

Rule of thumb: gamitin ang Gamma para makahanap kung ano ang i-trade; gamitin ang CLOB para i-trade ito. Ang bot na nagbabasa ng prices mula sa Gamma ay gumagamit ng stale data - ang price fields ng Gamma ay nag-uupdate nang mas hindi madalas kaysa sa CLOB order book. Ang bot na nagbabasa ng market metadata mula sa CLOB ay gumagawa ng mas maraming requests kaysa sa kailangan.

/events endpoint anatomy

Ang GET /events ay nagbabalik ng event-level data. Ang "event" ay Polymarket page; ang isang event ay maaaring naglalaman ng maraming markets (e.g. ang 2024 Presidential Election event ay may isang market kada kandidato).

Mga pangunahing fields:

• slug: URL-safe identifier, stable para sa buhay ng event.
• title, description: human display.
• endDate (ISO 8601): kailan magsasara ang event.
• active, closed: booleans; pagsamahin sa query na may ?active=true&closed=false para sa live events.
• volume, volume24hr: USD totals.
• tags: array ng tag objects (tingnan ang tags section sa ibaba).
• markets: array ng child market objects (tingnan ang /markets anatomy).

Ang isang pinakakaraniwang discovery pattern: GET /events?active=true&closed=false&order=volume24hr&ascending=false&limit=100. Nagbabalik ng 100 na pinakamataas-volume na kasalukuyang nabubuhay na events.

/markets endpoint anatomy

Ang GET /markets ay nagbabalik ng market-level data. Ang market ay isang Y/N o multi-outcome contract; nakatira ito sa loob ng event.

Mga pangunahing fields:

• slug: URL-safe identifier.
• question: ang title na ipinapakita sa trading page (e.g. "Will Trump be president on January 1, 2027?").
• outcomes: JSON string ng outcome names, e.g. '["Yes","No"]'. Palaging dalawang elements para sa binary; mas marami para sa NegRisk.
• outcomePrices: JSON string ng kasalukuyang prices bilang decimals, e.g. '["0.62","0.38"]'. Parehong panig ay nagsama sa ~1.0 minus spread.
• clobTokenIds: JSON string ng ERC-1155 token IDs na nakahanay sa outcomes. Ito ang mga tokens na talagang binibili/ibinebenta mo.
• negRisk: boolean; true para sa multi-outcome sum-to-1 markets. Mahalaga para sa order placement (kabanata 11).

Ang outcomes / outcomePrices / clobTokenIds fields ay dumarating bilang JSON strings, hindi parsed arrays - JSON-decode ang mga ito bago gamitin.

Tags at tag IDs (verified list)

Ang tags ay categorical labels (Sports, Crypto, Tennis, NBA, atbp.). Ang verified production tag IDs para sa pinakaginagamit na categories:

Mag-filter ayon sa tag gamit ang ?tag_id=745 para sa partikular na tag, o ?tag_slug=nba gamit ang slug. Ang slug-based filtering ay mas readable sa code pero bahagyang mas mabagal; ang ID-based ay production default.

Pag-filter: active, closed, volume24hr ordering

Ang apat na filter dimensions na gagamitin mo 95% ng oras.

• active=true|false: ang true ay nag-eexclude ng markets na itinago ng Polymarket team mula sa UI.
• closed=true|false: ang false ay nag-eexclude ng resolved markets. Ang kombinasyon na active=true&closed=false ay ang pinakakaraniwang live filter.
• order=volume24hr, order=volume, order=endDate: sort key. Pinaka-kapaki-pakinabang ay volume24hr para sa paghahanap ng kasalukuyang-aktibong markets.
• ascending=true|false: default sa true sa karamihan ng endpoints; halos palagi mong gusto ang false para sa volume orderings.

Caveat: pag-filter ayon sa tag_id na pinagsama sa order=volume24hr at ascending=false ay paminsan-minsan ay nagbabalik ng empty page kapag ang tag ay may kaunting live markets. Palaging mag-over-fetch (mag-request ng higit sa ipinapakita) at mag-post-filter para hawakan ito.

Pagination at limits

Ang limit param ay tumatanggap ng 1-500 per call. Ang default ay 100 kung hindi tinukoy. Sa itaas ng 500 ay tahimik na nag-cap ang server - nakatanggap ka ng 500 pero walang indication ang response ng higit pa.

Ang pagination ay offset-based: ?limit=500&offset=500 para sa pangalawang page. Walang cursor-based pagination, kaya ang concurrent inserts ay maaaring magdulot sa page boundaries na lumipat sa pagitan ng calls. Para sa karamihan ng bot discovery purposes ito ay katanggap-tanggap; para sa archive scrapes, mag-sort ayon sa stable field (endDate o createdAt) at i-detect ang overlap ayon sa slug.

Practical pattern para sa "lahat ng live markets": fetch limit=500&order=volume24hr&ascending=false. Iyon ay sumasaklaw sa top 500 ayon sa volume na essentially ay bawat market na may non-trivial activity. Ang pagpunta sa lampas ng page 1 ay bihirang kapaki-pakinabang - ang markets sa tail ng volume distribution ay sa kahulugan ay hindi kung saan ang aksyon ay.

Rate limits at caching

Ang Gamma ay frontiered ng Cloudflare at may soft rate limits per IP. Empirical thresholds na naobserbahan sa ilalim ng production load:

• Hanggang ~30 req/sec mula sa isang IP sustained: ayos.
• Bursts ng 100+ req/sec: paminsan-minsan 429s, ang retries ay nagtagumpay.
• ~500 req/sec sustained: rate-limit page o temporary block (10-60s).

Ang published response headers ay kasama ang Cache-Control values ng 30-60 segundo para sa karamihan ng endpoints. Igalang ang mga ito - walang benepisyo sa pag-re-fetch ng parehong event 10 beses sa isang minuto. Production caching pattern: in-process LRU + TTL na keyed sa full URL, 30s TTL. Nakakatipid ng request count at binabawasan ang latency.

Para sa high-frequency strategies, mag-mirror ng Gamma data sa local store na ina-update ng isang fetcher process; magkaroon ng maraming consumers na nagbabasa mula sa store na iyon. Isang fetcher × maraming consumers > maraming fetchers × Gamma.

Code: fetch top 24h-volume markets

Reference fetcher sa tatlong languages, nagbabalik ng top 50 live markets ayon sa 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'

Ang Polymarket gamma /events endpoint ay HINDI sumusuporta sa free-text search parameter - ang pagdaragdag ng ?q=foo o ?search=foo ay tahimik na nagbabalik ng default ordering. Mag-filter ayon sa slug o tag sa halip.

Mga madalas na tanong