Polymarket Gamma API 教程

本教程演示如何从 Polymarket 的 Gamma 面获取 markets 和 events、处理分页，并应用常见过滤器。示例使用 curl 和 TypeScript，便于将读取集成到机器人、仪表盘或分析管道中。

要点

Gamma 的基础 URL 是 https://gamma-api.polymarket.com，读取不需要认证。
使用 /markets 和 /events 端点，通过 after_cursor 进行基于 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. 获取 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 pagination）。

3. 基于 cursor 的分页（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）

示例：按 24 小时成交量降序获取某标签下的活跃市场：

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

当你只需要特定市场时，传入 slug 或 id 的数组以减少载荷并避免全表扫描。

5. Events 端点

/ events 端点会将市场按事件级元数据分组（例如：将多个市场条件包含在“2026 Presidential Election”事件下）。

基本调用：

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。
请求巨大页面而不使用 cursor 可能会触发速率限制并造成内存压力；优先使用较小的 limit 并遍历 cursor。
/markets + /events 的合并列表限制意味着对两个端点的重度轮询会很快让你被限流。
API 返回的 next_cursor 用于键集分页；将其视为不透明值并原样传回。

8. 与实时数据集成

Gamma 是用于元数据和历史列表的 REST 面。要获取实时订单簿和 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 用于回填，将 WebSocket 用于实时更新。

9. 这如何影响你的交易或工具链

如果你在构建交易机器人、仪表盘或数据管道，Gamma 是市场元数据、标签和列表的权威读取来源。使用 cursor 分页、积极过滤，并将 Gamma 读取与 CLOB API 或 Market WebSocket 配合使用以获取价格与订单簿数据。根据文档中的速率限制规划轮询频率以避免被限流。

Gamma 对公共数据只读；上述示例不需要 API key。若要下单与进行订单簿操作，请使用需要 API key + HMAC 的 CLOB API，地址为 https://clob.polymarket.com。

结语

本 Polymarket Gamma API 教程覆盖了获取 markets 与 events、处理 cursor 分页以及避免常见陷阱的实用步骤。将这些模式作为可靠机器人与分析工具的基础，并确保遵守 Gamma 的速率限制与分页模型。

常见问题

我需要 API key 才能读取 Gamma API 吗？

不需要。Gamma 的公共只读端点不需要认证。基础 URL 是 https://gamma-api.polymarket.com。只有用于交易的 CLOB 端点需要 API key + HMAC。

如何遍历大型 market 列表？

使用基于 cursor 的分页。每个列表都会返回 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）用于实时订单簿和 tick 事件；WebSocket 每个连接支持最多 500 个 instrument。

我可以按标签或 condition 过滤 markets 吗？

可以。Gamma 支持诸如 tag_id、condition_ids、clob_token_ids、slug 等过滤器。传入特定过滤器可减少载荷并有助于保持在速率限制内。

仅供教育用途。非金融、法律或税务建议。Polymarket在你的司法管辖区可能不可用。