Polymarket Gamma API ट्यूटोरियल

यह Polymarket Gamma API ट्यूटोरियल आपको दिखाता है कि Polymarket के Gamma surface से मार्केट्स और इवेंट्स कैसे प्राप्त करें, पेजिनेशन को कैसे संभालें, और सामान्य फ़िल्टर कैसे लागू करें। उदाहरण curl और TypeScript में हैं ताकि आप इन्हें बॉट्स, डैशबोर्ड या एनालिटिक्स पाइपलाइनों में इंटीग्रेट कर सकें।

मुख्य निष्कर्ष

• Gamma का बेस URL है https://gamma-api.polymarket.com और रीड्स के लिए ऑथ नहीं चाहिए।
• /markets और /events एंडपॉइंट्स का उपयोग करें और cursor-आधारित पेजिनेशन के लिए after_cursor का उपयोग करें; offset का उपयोग न करें।
• रेट सीमाओं का सम्मान करें: /markets के लिए 300 req / 10 s; combined /markets + /events listing limit 900 req / 10 s है। समग्र API लिमिट 4000 req / 10 s है।
• payload कम करने और लिमिट टकराने से बचने के लिए condition_ids, clob_token_ids, slug, और tag_id जैसे फ़ील्ड से फ़िल्टर करें।
• प्रोडक्शन क्लाइंट्स के लिए छोटे पेज साइज़ और एक्स्पोनेंशियल बैकऑफ़ का उपयोग करें।

1. Gamma मूल बातें: एंडपॉइंट्स और लिमिट

Gamma रीड बेस URL है:

https://gamma-api.polymarket.com

इस ट्यूटोरियल में जिन एंडपॉइंट्स का आप उपयोग करेंगे:

• GET /markets — मार्केट लिस्ट और सिंगल-मार्केट क्वेरीज़
• GET /events — ग्रुप्ड इवेंट्स (इवेंट-लेवल मेटाडेटा के लिए उपयोगी)

डिज़ाइन करते समय महत्वपूर्ण रेट लिमिट्स:

• /markets: 300 requests प्रति 10 सेकंड
• /markets + /events लिस्टिंग सम्मिलित: 900 requests प्रति 10 सेकंड
• समग्र Gamma API: 4000 requests प्रति 10 सेकंड

यदि आपका क्लाइंट बड़े डेटा सेट्स को पोल या बैकफिल करेगा, तो रिक्वेस्ट्स को बैच और स्टैगर करें और इन लिमिट्स का सम्मान करें।

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 या native 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 (boolean), active, archived
• tag_id — श्रेणी द्वारा फ़िल्टर करें
• order — comma-separated फ़ील्ड जैसे volume24hr, volume, liquidity, endDate
• ascending — boolean (डिफ़ॉल्ट true)

उदाहरण: किसी टैग के सक्रिय मार्केट्स को 24 घंटे के वॉल्यूम के आधार पर घटते क्रम में प्राप्त करें:

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

जब आपको केवल विशिष्ट मार्केट्स चाहिए, तो payload घटाने और लिस्ट स्कैन से बचने के लिए 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 IDs की सूची के लिए मार्केट्स लाता है, 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. सामान्य pitfalls और ट्रबलशूटिंग

• offset का उपयोग न करें — Gamma offset पैरामीटर के साथ HTTP 422 लौटाता है।
• बिना करसर के बहुत बड़े पेज मांगने से रेट लिमिट्स और मेमोरी प्रेशर हो सकता है; छोटे limits और करसर ट्रैवर्सल पसंद करें।
• सम्मिलित /markets + /events लिस्टिंग लिमिट का मतलब है कि दोनों एंडपॉइंट्स पर भारी पोलिंग आपको जल्दी से थ्रॉटल कर सकता है।
• API keyset पेजिनेशन के लिए next_cursor लौटाता है; इसे 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 मार्केट मेटाडेटा, टैग और लिस्टिंग के लिए कैनोनिकल रीड सोर्स है। करसर पेजिनेशन का उपयोग करें, agressively फ़िल्टर करें, और प्राइस तथा ऑर्डर-बुक डेटा के लिए Gamma रीड्स को CLOB API या Market WebSocket के साथ जोड़ें। थ्रॉटलिंग से बचने के लिए अपने पोलिंग कैडेंस की योजना दस्तावेज़ित रेट लिमिट्स के चारों ओर बनाएं।

Gamma सार्वजनिक डेटा के लिए रीड-ओनली है; ऊपर दिए उदाहरणों के लिए कोई API key आवश्यक नहीं है। ऑर्डर प्लेसमेंट और बुक ऑपरेशन्स के लिए CLOB API का उपयोग करें: https://clob.polymarket.com, जिसे API key + HMAC की आवश्यकता होती है।

समापन

इस Polymarket Gamma API ट्यूटोरियल ने मार्केट्स और इवेंट्स प्राप्त करने, करसर पेजिनेशन संभालने, और सामान्य pitfalls से बचने के व्यावहारिक चरणों को कवर किया। ये पैटर्न विश्वसनीय बॉट्स और एनालिटिक्स के लिए आधार के रूप में उपयोग करें जो Gamma की रेट लिमिट्स और पेजिनेशन मॉडल का सम्मान करते हैं।

अक्सर पूछे जाने वाले प्रश्न

क्या मुझे Gamma API से पढ़ने के लिए API key चाहिए?

नहीं। Gamma के सार्वजनिक रीड एंडपॉइंट्स के लिए ऑथ आवश्यक नहीं है। बेस URL है https://gamma-api.polymarket.com। केवल ट्रेडिंग के लिए CLOB एंडपॉइंट API key + HMAC मांगता है।

मैं बड़ी मार्केट सूची में कैसे पेज करूं?

करसर-आधारित पेजिनेशन का उपयोग करें। हर लिस्टिंग next_cursor लौटाती है; अगले पेज को प्राप्त करने के लिए उस मान को after_cursor के रूप में पास करें। Gamma offset-आधारित पेजिनेशन को HTTP 422 के साथ अस्वीकार कर देता है।

किस महत्वपूर्ण रेट लिमिट्स को ध्यान में रखना चाहिए?

/markets के लिए 300 requests प्रति 10 सेकंड की सीमा है। /markets + /events के सम्मिलित लिस्टिंग कॉल 900 req / 10 s सम्मिलित सीमा के तहत आते हैं। समग्र Gamma API लिमिट 4000 req / 10 s है। थ्रॉटलिंग से बचने के लिए रिक्वेस्ट्स stagger करें और बैकऑफ़ लागू करें।

रीयल-टाइम डेटा के लिए मुझे 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, और अन्य फ़िल्टर्स का समर्थन करता है। विशिष्ट फ़िल्टर्स पास करने से payload घटता है और आप रेट लिमिट्स में बने रहते हैं।