Polymarket Gamma API tutorial

Hướng dẫn Polymarket Gamma API này chỉ cho bạn cách lấy markets và events từ giao diện Gamma của Polymarket, xử lý phân trang và áp dụng các bộ lọc thường dùng. Các ví dụ dùng curl và TypeScript để bạn dễ tích hợp đọc dữ liệu vào bot, dashboard hoặc pipeline phân tích.

Các điểm chính

• Base URL của Gamma là https://gamma-api.polymarket.com và không yêu cầu xác thực cho các lệnh đọc.
• Dùng các endpoint /markets và /events với phân trang theo cursor bằng after_cursor; không dùng offset.
• Tôn trọng giới hạn tốc độ: /markets có 300 req / 10 s; giới hạn kết hợp /markets + /events là 900 req / 10 s. Tổng giới hạn API là 4000 req / 10 s.
• Lọc theo các trường như condition_ids, clob_token_ids, slug và tag_id để giảm payload và tránh chạm giới hạn.
• Dùng kích thước trang nhỏ và backoff mũ cho client production.

1. Gamma basics: endpoints and limits

Base URL đọc của Gamma là:

https://gamma-api.polymarket.com

Các endpoint bạn sẽ dùng trong hướng dẫn này:

• GET /markets — danh sách thị trường và truy vấn single-market
• GET /events — các sự kiện theo nhóm (hữu ích cho metadata ở cấp event)

Các giới hạn tốc độ quan trọng để thiết kế:

• /markets: 300 requests mỗi 10 giây
• /markets + /events listing kết hợp: 900 requests mỗi 10 giây
• Tổng Gamma API: 4000 requests mỗi 10 giây

Nếu client của bạn sẽ poll hoặc backfill dataset lớn, hãy gom lô và dàn trải các yêu cầu và tôn trọng những giới hạn này.

2. Fetching markets: minimal curl example

Một yêu cầu tối thiểu để liệt kê markets với tham số mặc định:

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

Để điều khiển kích thước trang (limit) và thứ tự:

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

Ghi chú:

• limit tối đa là 1000. Mặc định là 20.
• Gamma từ chối phân trang theo offset (HTTP 422). Thay vào đó hãy dùng after_cursor cho phân trang theo keyset.

3. Cursor-based pagination (after_cursor)

Gamma trả về một next_cursor trong phản hồi danh sách. Dùng giá trị đó trong after_cursor để lấy trang tiếp theo. Ví dụ TypeScript dưới đây mô tả luồng xử lý.

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

Các thực hành tốt được thể hiện:

• Dùng limit để kiểm soát kích thước trang và sử dụng mạng.
• Tôn trọng next_cursor và dừng khi nó vắng mặt.
• Thêm độ trễ nhỏ hoặc backoff khi bạn gần chạm giới hạn tốc độ.

4. Filtering and query parameters worth knowing

Gamma hỗ trợ nhiều tham số truy vấn. Hữu ích nhất khi bạn muốn đọc có mục tiêu:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — đều là mảng
• closed (boolean), active, archived
• tag_id — lọc theo danh mục
• order — các trường phân cách bởi dấu phẩy như volume24hr, volume, liquidity, endDate
• ascending — boolean (mặc định true)

Ví dụ: lấy các thị trường active trong một tag, sắp xếp theo volume 24h giảm dần:

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

Khi bạn chỉ cần các thị trường cụ thể, truyền mảng cho slug hoặc id để giảm payload và tránh quét danh sách lớn.

5. Events endpoint

Endpoint /events gom các markets vào metadata ở cấp event (ví dụ: "2026 Presidential Election" như một event chứa nhiều condition).

Gọi cơ bản:

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

Events cũng dùng after_cursor cho phân trang và chia sẻ giới hạn listing kết hợp với /markets (900 req / 10 s cho listing kết hợp).

6. Practical TypeScript example: fetch markets by condition_ids

Ví dụ này lấy markets theo một danh sách condition IDs, với điều khiển concurrency và backoff mũ.

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

Ghi chú cho môi trường production:

• Dùng một giới hạn concurrency (p-map, p-limit) nếu conditionIds lớn.
• Cache kết quả không đổi (ETag/If-None-Match) nếu API hỗ trợ và phù hợp với trường hợp sử dụng.
• Giám sát tốc độ yêu cầu so với các giới hạn đã ghi để tránh bị throttle.

7. Common pitfalls and troubleshooting

• Không dùng offset — Gamma trả về HTTP 422 cho các tham số offset.
• Yêu cầu các trang lớn mà không dùng cursor có thể chạm giới hạn tốc độ và gây áp lực bộ nhớ; ưu tiên limit nhỏ và duyệt cursor.
• Giới hạn kết hợp /markets + /events có nghĩa là poll nhiều hai endpoint này cùng lúc có thể bị throttle nhanh.
• API trả về next_cursor cho phân trang theo keyset; coi nó là một giá trị opaque và truyền lại nguyên vẹn.

8. Integrating with real-time data

Gamma là bề mặt REST cho metadata và danh sách lịch sử. Để lấy dữ liệu order-book và sự kiện tick thời gian thực, dùng Market WebSocket tại wss://ws-subscriptions-clob.polymarket.com/ws/market. WebSocket hỗ trợ tối đa 500 instruments mỗi kết nối và phát các sự kiện price_change, best_bid_ask, last_trade_price, và tick_size_change.

Giữ REST cho backfill và WebSocket cho cập nhật live.

9. How this affects your trading or tooling

Nếu bạn xây bot giao dịch, dashboard hoặc pipeline dữ liệu, Gamma là nguồn đọc chuẩn cho metadata thị trường, tag và listing. Dùng phân trang theo cursor, lọc mạnh, và ghép các lần đọc từ Gamma với CLOB API hoặc Market WebSocket để lấy dữ liệu giá và order-book. Lên kế hoạch tần suất polling theo các giới hạn đã ghi để tránh bị throttle.

Gamma chỉ đọc công cộng; không cần API key cho các ví dụ ở trên. Để đặt lệnh và thao tác trên book, dùng CLOB API tại https://clob.polymarket.com, endpoint đó yêu cầu API key + HMAC.

Closing

Hướng dẫn Polymarket Gamma API này đã trình bày các bước thực tế để lấy markets và events, xử lý phân trang theo cursor và tránh các lỗi thường gặp. Dùng các mẫu này làm cơ sở cho bot và công cụ phân tích đáng tin cậy, tôn trọng giới hạn tốc độ và mô hình phân trang của Gamma.

Frequently asked questions

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

Không. Các endpoint đọc công khai của Gamma không yêu cầu xác thực. Base URL là https://gamma-api.polymarket.com. Chỉ CLOB endpoint yêu cầu API key + HMAC để giao dịch.

How do I page through large market lists?

Dùng phân trang theo cursor. Mỗi listing trả về next_cursor; truyền giá trị đó như after_cursor để lấy trang tiếp theo. Gamma từ chối phân trang theo offset với HTTP 422.

What are the important rate limits to consider?

/markets có giới hạn 300 requests mỗi 10 giây. Các cuộc gọi listing kết hợp /markets + /events tính vào giới hạn 900 req / 10 s. Tổng Gamma API là 4000 req / 10 s. Dàn trải yêu cầu và triển khai backoff để tránh bị throttle.

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

Dùng Gamma cho metadata, listing và truy vấn lịch sử. Dùng Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) cho order-book thời gian thực và các sự kiện tick; WebSocket hỗ trợ tối đa 500 instruments mỗi kết nối.

Can I filter markets by tag or condition?

Có. Gamma hỗ trợ bộ lọc như tag_id, condition_ids, clob_token_ids, slug và các trường khác. Truyền các bộ lọc cụ thể sẽ giảm payload và giúp bạn duy trì trong giới hạn tốc độ.