Polymarket Gamma API tutorial

คู่มือนี้สอนวิธีดึง markets และ events จาก surface ของ Polymarket ที่เรียกว่า Gamma จัดการ pagination และใช้ตัวกรองที่พบบ่อย ตัวอย่างใช้ curl และ TypeScript เพื่อให้คุณสามารถผนวกการอ่านข้อมูลเข้ากับบอท แดชบอร์ด หรือ pipeline วิเคราะห์ได้

ข้อสรุปสำคัญ

• ค่า base URL ของ Gamma คือ https://gamma-api.polymarket.com และการอ่านข้อมูลสาธารณะไม่ต้องใช้การยืนยันตัวตน
• ใช้ endpoints /markets และ /events พร้อม pagination แบบ cursor โดยใช้ after_cursor; อย่าใช้ offset
• เคารพ rate limits: /markets มี 300 req / 10 s; รวม /markets + /events สำหรับการดึงรายการคือ 900 req / 10 s; ขีดจำกัดรวมของ API คือ 4000 req / 10 s
• กรองด้วยฟิลด์อย่าง condition_ids, clob_token_ids, slug และ tag_id เพื่อลดปริมาณข้อมูลและหลีกเลี่ยงการชนขีดจำกัด
• ใช้ขนาดหน้าเล็กและ exponential backoff สำหรับไคลเอนต์ production

1. Gamma พื้นฐาน: endpoints และข้อจำกัด

ค่า base URL สำหรับการอ่านของ Gamma คือ:

https://gamma-api.polymarket.com

Endpoints ที่คุณจะใช้ในคู่มือนี้:

• GET /markets — รายการตลาดและการค้นหาตลาดเดี่ยว
• GET /events — กลุ่ม events (มีประโยชน์สำหรับ metadata ระดับ event)

ข้อจำกัดของอัตราที่สำคัญสำหรับการออกแบบ:

• /markets: 300 requests ต่อ 10 วินาที
• /markets + /events สำหรับการดึงรายการรวม: 900 requests ต่อ 10 วินาที
• Gamma API รวมทั้งหมด: 4000 requests ต่อ 10 วินาที

ถ้าไคลเอนต์ของคุณจะ poll หรือ backfill ชุดข้อมูลขนาดใหญ่ ให้ทำการแบตช์และกระจายคำขอเพื่อตามข้อจำกัดเหล่านี้

2. การดึง markets: ตัวอย่าง curl ขั้นพื้นฐาน

คำขอขั้นต่ำเพื่อเรียกรายการ markets ด้วยพารามิเตอร์เริ่มต้น:

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 ปฏิเสธการทำ pagination แบบ offset (HTTP 422) ให้ใช้ after_cursor สำหรับ keyset pagination แทน

3. Pagination แบบ cursor (after_cursor)

Gamma จะส่ง next_cursor ในการตอบกลับแบบรายการ ใช้ค่านั้นใน after_cursor เพื่อดึงหน้าถัดไป ตัวอย่าง flow ใน TypeScript ดังต่อไปนี้

TypeScript example (node-fetch or 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 และหยุดเมื่อไม่มีค่า
• เพิ่มดีเลย์เล็กน้อยหรือ backoff เมื่อใกล้ถึงขีดจำกัด

4. การกรองและพารามิเตอร์ที่ควรรู้

Gamma รองรับพารามิเตอร์การค้นหาหลายชนิด ส่วนใหญ่มีประโยชน์เมื่อคุณต้องการการอ่านที่เจาะจง:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — ทุกตัวเป็นอาเรย์
• closed (boolean), active, archived
• tag_id — กรองตามหมวดหมู่
• order — ฟิลด์คั่นด้วย comma เช่น volume24hr, volume, liquidity, endDate
• ascending — boolean (ค่าเริ่มต้น true)

ตัวอย่าง: ดึง markets ที่ active ใน tag หนึ่ง เรียงตาม volume 24 ชั่วโมงจากมากไปน้อย:

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

เมื่อคุณต้องการเฉพาะตลาดบางรายการ ให้ส่งอาเรย์สำหรับ slug หรือ id เพื่อลด payload และหลีกเลี่ยงการสแกนรายการทั้งหมด

5. Events endpoint

Endpoint /events จะรวม markets ภายใต้ metadata ระดับ event (ตัวอย่าง: "2026 Presidential Election" เป็น event ที่มีหลาย condition)

คำขอพื้นฐาน:

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

Events ก็ใช้ after_cursor สำหรับ pagination และแชร์ขีดจำกัดการดึงรายการรวมกับ /markets (900 req / 10 s สำหรับการดึงรายการรวม)

6. ตัวอย่าง TypeScript เชิงปฏิบัติ: ดึง markets ตาม condition_ids

ตัวอย่างนี้ดึง markets สำหรับรายการ condition IDs พร้อมการควบคุม concurrency และ exponential backoff

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;
}

หมายเหตุสำหรับการใช้งาน production:

• ใช้ concurrency limiter (เช่น p-map, p-limit) ถ้า conditionIds มีจำนวนมาก
• แคชผลลัพธ์ที่ไม่เปลี่ยนแปลง (ETag/If-None-Match) หาก API รองรับสำหรับกรณีใช้งานของคุณ
• ตรวจสอบอัตราการร้องขอเทียบกับข้อจำกัดที่ระบุไว้

7. ข้อผิดพลาดที่พบบ่อยและการแก้ปัญหา

• อย่าใช้ offset — Gamma จะตอบด้วย HTTP 422 สำหรับพารามิเตอร์ offset
• การร้องขอหน้าขนาดใหญ่โดยไม่มี cursor อาจชนขีดจำกัดและกดดันหน่วยความจำ; ควรใช้ limit เล็กและเดินหน้าโดย cursor
• ขีดจำกัดรวม /markets + /events หมายความว่าการ poll หนักทั้งสอง endpoint อาจทำให้ถูก throttle ได้เร็ว
• API จะคืน next_cursor สำหรับ keyset pagination; ถือมันเป็นค่า opaque และส่งกลับตามตัวอักษร

8. การผนวกกับข้อมูลเรียลไทม์

Gamma คือ surface แบบ REST สำหรับ metadata และรายการในอดีต สำหรับ order-book และ tick events แบบเรียลไทม์ ให้ใช้ Market WebSocket ที่ wss://ws-subscriptions-clob.polymarket.com/ws/market. WebSocket รองรับสูงสุด 500 instruments ต่อการเชื่อมต่อ และส่งเหตุการณ์ price_change, best_bid_ask, last_trade_price, และ tick_size_change

เก็บ REST สำหรับการ backfill และใช้ WebSocket สำหรับอัพเดตสด

9. สิ่งนี้มีผลต่อการเทรดหรือเครื่องมือของคุณอย่างไร

ถ้าคุณกำลังสร้างบอทเทรด แดชบอร์ด หรือ pipeline ข้อมูล Gamma เป็นแหล่งอ่านหลักสำหรับ metadata ตลาด แท็ก และรายการ ใช้ cursor pagination กรองอย่างเข้มและจับคู่อ่านจาก Gamma กับ CLOB API หรือ Market WebSocket สำหรับข้อมูลราคาและ order-book วางแผนความถี่การ poll รอบข้อจำกัดที่ระบุไว้เพื่อหลีกเลี่ยงการถูก throttle

Gamma เป็นการอ่านข้อมูลสาธารณะ; ไม่ต้องใช้ API key สำหรับตัวอย่างข้างต้น สำหรับการวางคำสั่งและการดำเนินการบนหนังสือคำสั่ง ให้ใช้ CLOB API ที่ https://clob.polymarket.com ซึ่งต้องใช้ API key + HMAC

Closing

คู่มือนี้ครอบคลุมขั้นตอนปฏิบัติในการดึง markets และ events การจัดการ cursor pagination และการหลีกเลี่ยงข้อผิดพลาดทั่วไป ใช้แพตเทิร์นเหล่านี้เป็นพื้นฐานสำหรับบอทและระบบวิเคราะห์ที่เชื่อถือได้ซึ่งเคารพข้อจำกัดของ Gamma และรูปแบบ pagination

Frequently asked questions

Do I need an API key to read from the Gamma API?

No. Gamma's public read endpoints do not require authentication. The base URL is https://gamma-api.polymarket.com. Only the CLOB endpoint requires API key + HMAC for trading.

How do I page through large market lists?

Use cursor-based pagination. Each listing returns next_cursor; pass that value as after_cursor to fetch the next page. Gamma rejects offset-based pagination with HTTP 422.

What are the important rate limits to consider?

/markets has a limit of 300 requests per 10 seconds. Combined /markets + /events listing calls count toward a 900 req / 10 s combined limit. The overall Gamma API limit is 4000 req / 10 s. Stagger requests and implement backoff to avoid throttling.

Should I use Gamma or the Market WebSocket for real-time data?

Use Gamma for metadata, listings, and historical reads. Use the Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) for real-time order-book and tick events; the WebSocket supports up to 500 instruments per connection.

Can I filter markets by tag or condition?

Yes. Gamma supports filters such as tag_id, condition_ids, clob_token_ids, slug, and others. Passing specific filters reduces payload and helps stay within rate limits.