Polymarket Bot Tutorial · অধ্যায় ৭ of ৩২

Polymarket Gamma API deep dive: /events এবং /markets endpoints, pagination, tag IDs (864 Tennis, 745 NBA, ইত্যাদি), 24h volume অনুযায়ী filtering, rate limits, এবং Python ও Node code samples।

Harley Young দ্বারা, Polymarkets.co.il এর প্রধান লেখক। সর্বশেষ পর্যালোচনা: মে 2026।

এই অধ্যায়ে কী আছে

Gamma হলো Polymarket-এর catalog API - এটি front-end-এ দেখানো প্রতিটি event, প্রতিটি market, tag, image, এবং resolved outcome তালিকাভুক্ত করে। CLOB API trade করে; Gamma বলে কী tradeable। discovery layer-এ বেশিরভাগ bot bug আসে এই দুটোকে গুলিয়ে ফেলা থেকে, অথবা pagination contract মিস করার কারণে। এই অধ্যায়টি Gamma-এর main endpoints-এর field reference, যেখানে আমাদের production fetchers নির্ভর করে এমন exact parameter behavior দেখানো হয়েছে।

এটি Polymarket trading bot তৈরি নিয়ে আমাদের ৩২-অধ্যায়ের সিরিজের ৭ম অধ্যায়। নিচের sectionগুলোতে আমরা বিষয়টি গভীরভাবে কভার করেছি। প্রতিটি section-এর body content chapter-by-chapter লেখা ও প্রকাশ করা হচ্ছে; FAQ answers এবং references ইতিমধ্যেই সম্পূর্ণ এবং আমাদের own trader চালানোর production experience প্রতিফলিত করে।

  • 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: কখন কোনটি ব্যবহার করবেন

দুটি ভিন্ন কাজের জন্য দুটি ভিন্ন service।

Gamma (gamma-api.polymarket.com): catalog। এটি events, markets, tags, descriptions, images, resolved outcomes, 24-hour volume, total volume, end dates তালিকাভুক্ত করে। Read-only HTTP। বেশিরভাগ read-এর জন্য authentication লাগে না। Continuousভাবে update হয়, তবে eventually consistent - সদ্য closed হওয়া কোনো market কয়েক সেকেন্ডের জন্যও closed: false দেখাতে পারে।

CLOB (clob.polymarket.com): trading + order book। এটি current best bid/ask, top-N book depth, recent trades তালিকাভুক্ত করে। write endpoints-এর জন্য authenticated (order placement, cancellation)। Book updates-এর জন্য real-time WebSocket channels পাওয়া যায়।

Thumb rule: কী trade করবেন তা খুঁজতে Gamma ব্যবহার করুন; trade করতে CLOB ব্যবহার করুন। Gamma থেকে price পড়া bot পুরনো data ব্যবহার করছে - Gamma-এর price field, CLOB-এর order book-এর চেয়ে কম ঘন ঘন update হয়। CLOB থেকে market metadata পড়া মানে অপ্রয়োজনীয় বেশি request করা।

/events endpoint anatomy

GET /events event-level data ফেরত দেয়। একটি "event" হলো একটি Polymarket page; একটি event-এর মধ্যে একাধিক market থাকতে পারে (যেমন 2024 Presidential Election event-এ প্রতিটি candidate-এর জন্য একেকটি market আছে)।

Key fields:

  • slug: URL-safe identifier, event-এর জীবনকাল জুড়ে stable.
  • title, description: human display-এর জন্য।
  • endDate (ISO 8601): কখন event close হবে।
  • active, closed: boolean; live events-এর জন্য query-তে ?active=true&closed=false একসাথে ব্যবহার করুন।
  • volume, volume24hr: USD totals।
  • tags: tag object-এর array (নিচের tags section দেখুন)।
  • markets: child market object-এর array (/markets anatomy দেখুন)।

সবচেয়ে সাধারণ discovery pattern: GET /events?active=true&closed=false&order=volume24hr&ascending=false&limit=100. এটি বর্তমানে live থাকা সর্বোচ্চ volume-এর ১০০টি event ফেরত দেয়।

/markets endpoint anatomy

GET /markets market-level data ফেরত দেয়। একটি market হলো একটি Y/N বা multi-outcome contract; এটি একটি event-এর ভিতরে থাকে।

Key fields:

  • slug: URL-safe identifier.
  • question: trading page-এ দেখানো title (যেমন "Will Trump be president on January 1, 2027?").
  • outcomes: outcome name-এর JSON string, যেমন '["Yes","No"]'. Binary-এর জন্য সবসময় দুইটি element; NegRisk-এর জন্য আরও বেশি।
  • outcomePrices: decimal আকারে current price-এর JSON string, যেমন '["0.62","0.38"]'. উভয় side-এর যোগফল spread বাদে প্রায় 1.0।
  • clobTokenIds: outcomes-এর সাথে aligned ERC-1155 token ID-এর JSON string। এগুলোই আপনি আসলে buy/sell করেন।
  • negRisk: boolean; multi-outcome sum-to-1 market-এর জন্য true। Order placement-এর ক্ষেত্রে গুরুত্বপূর্ণ (chapter 11)।

outcomes / outcomePrices / clobTokenIds field-গুলো parsed array হিসেবে নয়, JSON string হিসেবে আসে - ব্যবহার করার আগে JSON-decode করুন।

Tags এবং tag IDs (verified list)

Tags হলো categorical label (Sports, Crypto, Tennis, NBA, ইত্যাদি)। সবচেয়ে বেশি ব্যবহৃত category-গুলোর verified production tag ID:

TagIDTagID
Sports1NBA745
Crypto21NFL450
Politics2Tennis864
Bitcoin100196Esports702
Ethereum100383Soccer1059
Election3EPL739
Middle East1432UCL2186

?tag_id=745 ব্যবহার করে নির্দিষ্ট tag-এ filter করুন, অথবা slug ব্যবহার করে ?tag_slug=nba দিন। Slug-based filtering code-এ বেশি readable, কিন্তু একটু ধীর; production default হলো ID-based।

Filtering: active, closed, volume24hr ordering

যে চারটি filter dimension আপনি 95% সময় ব্যবহার করবেন।

  • active=true|false: true দিলে Polymarket team UI থেকে hide করা market বাদ পড়ে।
  • closed=true|false: false দিলে resolved market বাদ পড়ে। active=true&closed=false combination-টি live filter-এর মধ্যে সবচেয়ে সাধারণ।
  • order=volume24hr, order=volume, order=endDate: sort key। বর্তমানে active market খুঁজতে সবচেয়ে উপযোগী হলো volume24hr।
  • ascending=true|false: বেশিরভাগ endpoint-এ default হলো true; volume ordering-এ প্রায় সবসময় false চাইবেন।

Caveat: tag_id দিয়ে filter করার সঙ্গে order=volume24hr এবং ascending=false একত্রে দিলে, tag-এ live market খুব কম থাকলে কখনও কখনও empty page ফেরত আসতে পারে। এ ক্ষেত্রে সবসময় over-fetch করুন (যা দেখাবেন তার চেয়ে বেশি request করুন) এবং post-filter করুন।

Pagination এবং limits

limit param প্রতি call-এ 1-500 পর্যন্ত গ্রহণ করে। উল্লেখ না করলে default হলো 100। 500-এর বেশি দিলে server নীরবে cap করে - আপনি 500 পাবেন, কিন্তু response-এ আর বেশি আছে কি না তার কোনো ইঙ্গিত থাকবে না।

Pagination offset-based: দ্বিতীয় page-এর জন্য ?limit=500&offset=500। এখানে cursor-based pagination নেই, তাই concurrent insert-এর ফলে call-এর মধ্যে page boundary সরে যেতে পারে। অধিকাংশ bot discovery-এর জন্য এটি গ্রহণযোগ্য; archive scrape-এর জন্য stable field (endDate বা createdAt) দিয়ে sort করুন এবং slug দিয়ে overlap detect করুন।

"all live markets" পাওয়ার ব্যবহারিক pattern: limit=500&order=volume24hr&ascending=false fetch করুন। এতে volume অনুযায়ী top 500 cover হয়, যা মূলত non-trivial activity থাকা প্রায় সব market। Page 1-এর বাইরে যাওয়া খুব কমই দরকার - volume distribution-এর tail-এ থাকা market-গুলো সংজ্ঞাগতভাবেই action-এর জায়গা নয়।

Rate limits এবং caching

Gamma-এর সামনে Cloudflare আছে এবং IP অনুযায়ী soft rate limit প্রয়োগ করে। production load-এ দেখা empirical threshold:

  • একটি IP থেকে ~30 req/sec পর্যন্ত sustained: ঠিক আছে।
  • 100+ req/sec burst: মাঝে মাঝে 429 আসে, retry সফল হয়।
  • ~500 req/sec sustained: rate-limit page বা temporary block (10-60s)।

Published response header-এ বেশিরভাগ endpoint-এর জন্য Cache-Control value 30-60 seconds থাকে। এটি মানুন - একই event এক মিনিটে 10 বার re-fetch করার কোনো লাভ নেই। Production caching pattern: full URL key করে in-process LRU + TTL, 30s TTL। এতে request count বাঁচে এবং latency কমে।

High-frequency strategy-এর জন্য, Gamma data-কে একটি local store-এ mirror করুন যা একটি single fetcher process দ্বারা update হবে; একাধিক consumer সেই store থেকে পড়বে। One fetcher × many consumers > many fetchers × Gamma।

Code: top 24h-volume markets fetch করুন

তিনটি ভাষায় reference fetcher, যা 24-hour volume অনুযায়ী top 50 live market ফেরত দেয়।

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 সমর্থন করে না - ?q=foo বা ?search=foo যোগ করলে নীরবে default ordering ফেরত আসে। Slug বা tag দিয়ে filter করুন।

প্রায়শই জিজ্ঞাসিত প্রশ্ন

Polymarket Gamma API কী?
Gamma হলো Polymarket-এর metadata এবং discovery API। এটি event/market list, title, description, end date, tag, এবং aggregate volume দেয়। এটি real-time order book data দেয় না - সেটি থাকে CLOB API-তে। বেশিরভাগ discovery এবং analytics use case-এ আপনি Gamma থেকেই শুরু করবেন।
Polymarket-এ event এবং market-এর মধ্যে পার্থক্য কী?
একটি event এক বা একাধিক market-কে group করে, যেগুলো একই question theme ভাগ করে। একটি market হলো নির্দিষ্ট Yes/No outcome, যার নিজস্ব order book এবং token ID আছে। "2026 NBA Champion" event-এ ৩০টি market থাকে (প্রতিটি team-এর জন্য একটি করে)। Binary Yes/No event-এ event-এর নিচে ১টি underlying market থাকে।
Polymarket tag ID কীভাবে খুঁজব?
Tags gamma /tags endpoint-এর মাধ্যমে exposed হয়। আমরা production-এ যেসব verified ID ব্যবহার করি: 864 Tennis, 745 NBA. URL-এ tag slug (?tag_slug=tennis) এবং free-text query (?q=tennis) নির্ভরযোগ্য নয় - শুধু numerical tag_id ব্যবহার করুন। Slug-এর উপর নির্ভর করার আগে /tags পরীক্ষা করুন।
Polymarket event-কে 24h volume অনুযায়ী কীভাবে sort করব?
/events?order=volume24hr&ascending=false - এটিই বেশিরভাগ "trending markets" widget-এর ভিত্তি। Expired বা paused market বাদ দিতে active=true&closed=false-এর সাথে combine করুন। Limit default হলো 25; সর্বোচ্চ 500 প্রতি call।
Gamma-তে pagination limit আছে কি?
হ্যাঁ। /events এবং /markets endpoint limit (প্রতি call-এ max 500) এবং pagination-এর জন্য offset গ্রহণ করে। বেশিরভাগ library স্বয়ংক্রিয়ভাবে paginate করে না - সম্পূর্ণ universe দরকার হলে `limit`-এর চেয়ে কম result পাওয়া পর্যন্ত offset দিয়ে loop করুন।
Gamma কি WebSocket support করে?
না। Gamma শুধু REST-only। Real-time update (price change, নতুন market, order book) এর জন্য CLOB WebSocket ব্যবহার করুন - এই সিরিজের chapter 8-এ তা covered।