Polymarket Gamma API টিউটোরিয়াল

এই Polymarket Gamma API টিউটোরিয়ালে দেখানো হবে কিভাবে Polymarket-এর Gamma সারফেস থেকে মার্কেট ও ইভেন্ট ফেচ করা যায়, কিভাবে পেজিনেশন হ্যান্ডেল করবেন, এবং সাধারণ ফিল্টার কীভাবে প্রয়োগ করবেন। উদাহরণগুলোতে curl এবং TypeScript ব্যবহার করা হয়েছে যাতে আপনি বট, ড্যাশবোর্ড, বা অ্যানালিটিক্স পাইপলাইনে রিড ইন্টিগ্রেট করতে পারেন।

গুরুত্বপূর্ণ সারসংক্ষেপ

• Gamma-এর বেস URL হলো https://gamma-api.polymarket.com এবং রিড-অপারেশনের জন্য কোনো auth এর প্রয়োজন নেই।
• /markets এবং /events এন্ডপয়েন্টগুলো ব্যবহার করুন এবং keyset পেজিনেশনের জন্য after_cursor ব্যবহার করুন; offset ব্যবহার করবেন না।
• রেট লিমিট শ্রদ্ধা করুন: /markets এর জন্য 300 req / 10 s; /markets + /events মিলিয়ে লিস্টিংের সীমা 900 req / 10 s। মোট API সীমা 4000 req / 10 s।
• condition_ids, clob_token_ids, slug, এবং tag_id মত ফিল্ডগুলো দিয়ে ফিল্টার করলে পোলোড কমে এবং লিমিট ভাঙার ঝুঁকি কমে।
• প্রোডাকশনে ছোট পেজ সাইজ এবং এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করা উচিত।

1. Gamma বেসিক্স: এন্ডপয়েন্ট এবং লিমিট

Gamma রিড বেস URL হল:

https://gamma-api.polymarket.com

এই টিউটোরিয়ালে আপনি যে এন্ডপয়েন্টগুলো ব্যবহার করবেন:

• GET /markets — মার্কেট তালিকা এবং সিঙ্গেল-মার্কেট কুয়েরি
• GET /events — গ্রুপ করা ইভেন্ট (ইভেন্ট-লেভেল মেটাডেটার জন্য উপযোগী)

ডিজাইন করার সময় যে গুরুত্বপূর্ণ রেট লিমিটগুলো মনে রাখা দরকার:

• /markets: 10 সেকেন্ড প্রতি 300 রিকুয়েস্ট
• /markets + /events লিস্টিং মিলিয়ে: 10 সেকেন্ড প্রতি 900 রিকুয়েস্ট
• সামগ্রিক Gamma API: 10 সেকেন্ড প্রতি 4000 রিকুয়েস্ট

আপনার ক্লায়েন্ট যদি পোলিং করে বা বড় ডেটাসেট ব্যাকফিল করে, তাহলে রিকুয়েস্ট ব্যাচ ও স্ট্যাগার করুন এবং এই লিমিটগুলো মানুন।

2. মার্কেট ফেচ করা: মিনিমাল curl উদাহরণ

ডিফল্ট প্যারামিটার নিয়ে মার্কেট তালিকা করার একটি সর্বনিম্ন অনুরোধ:

curl "https://gamma-api.polymarket.com/markets"

পেজ সাইজ (limit) এবং অর্ডার কন্ট্রোল করতে:

curl "https://gamma-api.polymarket.com/markets?limit=100&order=volume24hr&ascending=false"

নোটসমূহ:

• limit এর সর্বোচ্চ মান 1000। ডিফল্ট 20।
• Gamma offset-ভিত্তিক পেজিনেশন প্রত্যাখ্যান করে (HTTP 422)। keyset পেজিনেশনের জন্য after_cursor ব্যবহার করুন।

3. কার্সার-ভিত্তিক পেজিনেশন (after_cursor)

লিস্টিং রেসপন্সে Gamma একটি next_cursor ফিরিয়ে দেয়। পরবর্তী পেজ ফেচ করতে সেই মানকে after_cursor হিসেবে পাঠান। নীচে TypeScript উদাহরণ দেয়া আছে।

TypeScript উদাহরণ (node-fetch বা নেটিভ fetch ব্যবহার করে):

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

type MarketsResponse = {
  markets: any[];
  next_cursor?: string | null;
};

async function fetchAllMarkets(limit = 200) {
  let cursor: string | undefined;
  const all: any[] = [];

  while (true) {
    const url = new URL('/markets', BASE);
    url.searchParams.set('limit', String(limit));
    if (cursor) url.searchParams.set('after_cursor', cursor);

    const res = await fetch(url.toString());
    if (!res.ok) throw new Error(`Gamma error ${res.status}`);

    const body: MarketsResponse = await res.json();
    all.push(...body.markets);

    if (!body.next_cursor) break;
    cursor = body.next_cursor;

    // small delay to avoid spike; tune for your rate budget
    await new Promise((r) => setTimeout(r, 100));
  }

  return all;
}

দেখানো সেরা অনুশীলনসমূহ:

• পেজ সাইজ এবং নেটওয়ার্ক ব্যবহার নিয়ন্ত্রণ করতে limit ব্যবহার করুন।
• next_cursor মানটি সম্মান করুন এবং এটি না থাকলে স্টপ করুন।
• রেট লিমিটের কাছাকাছি থাকলে ছোট ডিলে বা ব্যাকঅফ যোগ করুন।

4. ফিল্টার এবং জানা দরকারি কুয়েরি প্যারামিটার

Gamma অনেক কুয়েরি প্যারামিটার সমর্থন করে। টার্গেটেড রিড চাইলে এগুলো সবচেয়ে কাজে লাগে:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — সবগুলো অ্যারে হিসেবে পাঠানো যায়
• closed (বুলিয়ান), active, archived
• tag_id — ক্যাটাগরিভিত্তিক ফিল্টার
• order — কমা-সেপারেটেড ফিল্ড যেমন volume24hr, volume, liquidity, endDate
• ascending — বুলিয়ান (ডিফল্ট true)

উদাহরণ: একটি ট্যাগে সক্রিয় মার্কেটগুলো 24h ভলিউম অনুযায়ী অবতরণে (descending) আনার জন্য:

curl "https://gamma-api.polymarket.com/markets?active=true&tag_id=123&order=volume24hr&ascending=false&limit=100"

আপনি যদি নির্দিষ্ট মার্কেটগুলোই চান, তাহলে slug বা id-র অ্যারে পাঠান— এতে পোলোড কমে এবং লিস্ট স্ক্যান এড়ানো যায়।

5. ইভেন্টস এন্ডপয়েন্ট

/events এন্ডপয়েন্ট মার্কেটগুলোকে ইভেন্ট-লেভেল মেটাডেটার অধীনে গ্রুপ করে (যেমন: "2026 Presidential Election" একটি ইভেন্ট যার মধ্যে একাধিক মার্কেট কন্ডিশন রয়েছে)।

বেসিক কল:

curl "https://gamma-api.polymarket.com/events?limit=50"

Events ওগুলোর ক্ষেত্রেও after_cursor ব্যবহার করে পেজিনেশন এবং /markets-এর সাথে মিলিয়ে লিস্টিং লিমিট শেয়ার করে (combined listings এর জন্য 900 req / 10 s)।

6. প্র্যাক্টিক্যাল TypeScript উদাহরণ: condition_ids দিয়ে মার্কেট ফেচ করা

নিচের উদাহরণটি একটি condition ID তালিকার জন্য মার্কেটগুলো ফেচ করে, concurrency কন্ট্রোল এবং এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করে।

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

async function fetchMarketsByCondition(conditionIds: string[]) {
  const results: any[] = [];

  for (const id of conditionIds) {
    let cursor: string | undefined;
    let retries = 0;

    while (true) {
      const url = new URL('/markets', BASE);
      url.searchParams.set('limit', '200');
      url.searchParams.set('condition_ids', id);
      if (cursor) url.searchParams.set('after_cursor', cursor);

      const res = await fetch(url.toString());
      if (res.status === 429) {
        // respect rate limits with exponential backoff
        await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, retries)));
        retries = Math.min(retries + 1, 5);
        continue;
      }

      if (!res.ok) throw new Error(`Gamma ${res.status}`);

      const body = await res.json();
      results.push(...body.markets);

      if (!body.next_cursor) break;
      cursor = body.next_cursor;
    }
  }

  return results;
}

প্রোডাকশন ব্যবহারের নোট:

• conditionIds বড় হলে concurrency limiter (p-map, p-limit) ব্যবহার করুন।
• যদি API ETag/If-None-Match সমর্থন করে এবং আপনার ইউজ-কেসে উপযোগী হয়, অপরিবর্তিত রেজাল্ট কেশ করুন।
• আপনার রিকুয়েস্ট রেট ডকুমেন্টেড লিমিটের বিরুদ্ধে মনিটর করুন।

7. সাধারণ অসুবিধা এবং ট্রাবলশুটিং

• offset ব্যবহার করবেন না — Gamma offset প্যারামিটারে HTTP 422 রিটার্ন করে।
• কার্সার ছাড়া বিশাল পেজ রিকুয়েস্ট করলে রেট লিমিট ও মেমরি প্রেসার হতে পারে; ছোট লিমিট ও কার্সার ট্র্যাভার্সাল পছন্দ করুন।
• /markets + /events লিস্টিং মিলিয়ে লিমিট থাকার কারণে দুটো এন্ডপয়েন্টেই ভারী পোলিং করলে দ্রুত থ্রটল হতে পারেন।
• API next_cursor দেয় keyset পেজিনেশনের জন্য; এটাকে opaque হিসেবে বিবেচনা করে সামইকভাবে ফিরিয়ে দিন।

8. রিয়েল-টাইম ডাটার সাথে ইন্টিগ্রেশন

Gamma হল মেটাডাটা ও ঐতিহাসিক লিস্টিংয়ের REST সারফেস। রিয়েল-টাইম অর্ডার-বুক এবং টিক ইভেন্ট পেতে Market WebSocket ব্যবহার করুন:

wss://ws-subscriptions-clob.polymarket.com/ws/market

WebSocket এক সংযোগে সর্বোচ্চ 500 টি ইনস্ট্রুমেন্ট সাপোর্ট করে এবং price_change, best_bid_ask, last_trade_price, এবং tick_size_change ইভেন্ট এমিট করে।

ব্যাকফিলের জন্য REST রাখুন এবং লাইভ আপডেটের জন্য WebSocket ব্যবহার করুন।

9. এটির আপনার ট্রেডিং বা টুলিং-এ কী প্রভাব

যদি আপনি ট্রেডিং বট, ড্যাশবোর্ড, বা ডেটা পাইপলাইন বানাচ্ছেন, Gamma হল মার্কেট মেটাডাটা, ট্যাগ, এবং লিস্টিংয়ের জন্য canonical রিড সোর্স। কার্সার পেজিনেশন ব্যবহার করুন, কঠোরভাবে ফিল্টার করুন, এবং প্রাইস ও অর্ডার-বুক ডাটার জন্য Gamma রিডকে CLOB API বা Market WebSocket-এর সাথে পেয়ার করুন। থ্রটল এড়াতে ডকুমেন্টেড রেট লিমিট অনুযায়ী পোলিং ক্dেন্স নির্ধারণ করুন।

Gamma পাবলিক ডাটা-রিডের জন্য read-only; উপরোক্ত উদাহরণগুলোর জন্য কোনো API key প্রয়োজন নেই। অর্ডার প্লেসমেন্ট ও বুক অপারেশনের জন্য CLOB API ব্যবহার করুন:

https://clob.polymarket.com

যেটি ট্রেডিংয়ের জন্য API key + HMAC প্রয়োজন।

সমাপ্তি

এই Polymarket Gamma API টিউটোরিয়াল মার্কেট ও ইভেন্ট ফেচ করা, কার্সার পেজিনেশন হ্যান্ডেল করা, এবং সাধারণ পিটফল এড়ানোর ব্যবহারিক ধাপগুলোকে কভার করেছে। এগুলো নির্ভরযোগ্য বট ও অ্যানালিটিক্স তৈরি করার ভিত্তি হিসেবে ব্যবহার করুন—Gamma-র রেট লিমিট এবং পেজিনেশন মডেলকে সম্মান করে।

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

Gamma API থেকে পড়ার জন্য কি আমার API key লাগবে?

না। Gamma-র পাবলিক রিড এন্ডপয়েন্টগুলোর জন্য authentication দরকার নেই। বেস URL হল https://gamma-api.polymarket.com। কেবল ট্রেডিংয়ের জন্য CLOB এন্ডপয়েন্ট API key + HMAC চায়।

বড় মার্কেট তালিকাগুলো কিভাবে পেজ করব?

কার্সার-ভিত্তিক পেজিনেশন ব্যবহার করুন। প্রতিটি লিস্টিং next_cursor রিটার্ন করে; পরের পেজ ফেচ করতে সেই মানটি after_cursor হিসেবে পাঠান। Gamma offset-ভিত্তিক পেজিনেশন HTTP 422 দিয়ে প্রত্যাখ্যান করে।

বিবেচনা করার জন্য গুরুত্বপূর্ণ রেট লিমিটগুলো কী কী?

/markets-এ 10 সেকেন্ড প্রতি 300 রিকুয়েস্ট সীমা আছে। /markets + /events লিস্টিং কল মিলিয়ে 10 সেকেন্ডে 900 রিকুয়েস্ট লিমিট আছে। সামগ্রিক Gamma API লিমিট 10 সেকেন্ডে 4000 রিকুয়েস্ট। থ্রটল হওয়া এড়াতে রিকুয়েস্টগুলো স্ট্যাগার করুন এবং ব্যাকঅফ ইমপ্লিমেন্ট করুন।

রিয়েল-টাইম ডাটার জন্য আমি Gamma না Market WebSocket ব্যবহার করব?

মেটাডাটা, লিস্টিং, এবং ঐতিহাসিক রিডের জন্য Gamma ব্যবহার করুন। রিয়েল-টাইম অর্ডার-বুক ও টিক ইভেন্টের জন্য Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) ব্যবহার করুন; WebSocket এক সংযোগে সর্বোচ্চ 500 ইনস্ট্রুমেন্ট সাপোর্ট করে।

আমি কি ট্যাগ বা কন্ডিশন দিয়ে মার্কেট ফিল্টার করতে পারি?

হ্যাঁ। Gamma tag_id, condition_ids, clob_token_ids, slug এবং আরও কিছু ফিল্টার সমর্থন করে। নির্দিষ্ট ফিল্টার পাঠালে পোলোড কমে এবং রেট লিমিটের মধ্যে থাকা সহজ হয়।