Polymarket Gamma API 教學

本教學示範如何從 Polymarket 的 Gamma surface 擷取 markets 與 events、處理分頁，並套用常見篩選。範例使用 curl 與 TypeScript，方便將讀取整合到機器人、儀表板或分析管線中。

重點摘要

• Gamma 的 base URL 為 https://gamma-api.polymarket.com，讀取不需要驗證。
• 使用 /markets 與 /events 端點，採用 after_cursor 的 cursor-based 分頁；不要使用 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 的讀取 base URL：

https://gamma-api.polymarket.com

本教學會用到的端點：

• GET /markets — 列表與單一 market 查詢
• GET /events — 群組化的 events（適用於事件層級的 metadata）

設計時要注意的重要速率限制：

• /markets：每 10 秒 300 次請求
• /markets + /events 列表合併：每 10 秒 900 次請求
• 整體 Gamma API：每 10 秒 4000 次請求

如果你的用戶端會輪詢或回補大量資料，請批次並錯開請求以遵守這些限制。

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 會拒絕基於 offset 的分頁（HTTP 422）。請改用 after_cursor 做 keyset 分頁。

3. 游標分頁（after_cursor）

列表回應會包含 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（boolean）、active、archived
• tag_id — 依分類篩選
• order — 以逗號分隔的欄位，例如 volume24hr、volume、liquidity、endDate
• ascending — boolean（預設為 true）

範例：抓取某分類下的活躍 markets，依 24 小時成交量降冪排序：

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

當你只需要特定 markets 時，傳入 slug 或 id 的陣列可減少回傳量並避免全表掃描。

5. Events 端點

/events 端點會將 markets 群組在事件層級的 metadata 底下（例如：事件 "2026 Presidential Election" 可能包含多個 market condition）。

基本呼叫：

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

Events 同樣使用 after_cursor 分頁，且與 /markets 共享合併列舉限制（/markets + /events 列表合併為每 10 秒 900 次請求）。

6. 實務 TypeScript 範例：依 condition_ids 擷取 markets

此範例示範如何為一組 condition ID 擷取 markets，並加入併發控制與指數退避。

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 很多，使用併發限制器（如 p-map、p-limit）。
• 若 API 支援，可以快取未變更的結果（ETag / If-None-Match）。
• 監控你的請求速率，確保不超出文件化的限制。

7. 常見陷阱與除錯

• 不要使用 offset — Gamma 對 offset 參數回傳 HTTP 422。
• 一次請求過大的頁面若不搭配游標，可能遭遇速率限制或記憶體壓力；優先使用較小的 limit 並遍歷游標。
• /markets + /events 的合併列表限制代表同時重度輪詢兩個端點會很快被節流。
• API 回傳的 next_cursor 為不透明值；請原樣傳回並視為不解析的 token。

8. 與即時資料整合

Gamma 是 metadata 與歷史列表的 REST surface。若需要即時的 order-book 與 tick 事件，請使用 Market WebSocket：wss://ws-subscriptions-clob.polymarket.com/ws/market。該 WebSocket 每條連線支援最多 500 個 instrument，並會發出 price_change、best_bid_ask、last_trade_price 與 tick_size_change 事件。

將 REST 用於回補（backfills），WebSocket 用於即時更新。

9. 這如何影響你的交易或工具開發

若你在建構交易機器人、儀表板或資料管線，Gamma 是 market metadata、tags 與 listings 的權威讀取來源。請使用游標分頁、積極篩選，並將 Gamma 的讀取與 CLOB API 或 Market WebSocket 配合，取得價格與 order-book 資料。依據文件化的速率限制規劃你的輪詢頻率以避免被節流。

Gamma 對公開資料為唯讀；上述範例不需 API key。若要下單與操作 order-book，請使用需 API key + HMAC 的 CLOB API：https://clob.polymarket.com。

結語

本 Polymarket Gamma API 教學涵蓋了擷取 markets 與 events、處理游標分頁與避免常見陷阱的實務步驟。以這些模式為基礎，建立可靠的機器人與分析系統，同時尊重 Gamma 的速率限制與分頁模型。

常見問題

我需要 API key 才能讀取 Gamma API 嗎？

不需要。Gamma 的公開讀取端點不需要驗證。base URL 為 https://gamma-api.polymarket.com。只有下單相關的 CLOB 端點需要 API key + HMAC。

我該如何分頁大量的 market 列表？

使用 cursor-based 分頁。每次列舉都會回傳 next_cursor，將該值作為 after_cursor 傳回以取得下一頁。Gamma 會對 offset-based 分頁回傳 HTTP 422。

需要注意的重要速率限制有哪些？

/markets 的限制為每 10 秒 300 次請求。/markets + /events 的合併列舉限制為每 10 秒 900 次請求。整體 Gamma API 的限制為每 10 秒 4000 次請求。請錯開請求並實作退避以避免被節流。

我該使用 Gamma 還是 Market WebSocket 取得即時資料？

Gamma 適合 metadata、列表與歷史讀取。即時的 order-book 與 tick 事件請使用 Market WebSocket（wss://ws-subscriptions-clob.polymarket.com/ws/market）；該 WebSocket 每條連線支援最多 500 個 instrument。

我可以依 tag 或 condition 篩選 markets 嗎？

可以。Gamma 支援像 tag_id、condition_ids、clob_token_ids、slug 等篩選。傳入具體篩選可減少回傳量並有助於維持在速率限制內。