Polymarket Gamma API チュートリアル
Polymarket の Gamma サーフェスから市場とイベントを取得するためのコードレベルの手順。ページネーション、フィルタリング、開発者向けのベストプラクティスを含みます。
Polymarket Gamma API チュートリアル
この Polymarket Gamma API チュートリアルでは、Polymarket の Gamma サーフェスから市場とイベントを取得する方法、ページネーションの処理、一般的なフィルタの適用方法を説明します。例は curl と TypeScript を使っており、ボット、ダッシュボード、分析パイプラインに読み取りを組み込めるようになっています。
主なポイント
- Gamma のベース URL は https://gamma-api.polymarket.com で、読み取りには認証を必要としません。
- /markets と /events エンドポイントを after_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. 市場取得: 最小限の 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）。代わりに after_cursor を使うキーセットページネーションを使ってください。
3. カーソルベースのページネーション (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 (boolean), active, archived
- tag_id — カテゴリでフィルタ
- order — volume24hr, volume, liquidity, endDate のようなカンマ区切りフィールド
- ascending — boolean（デフォルト true）
例: タグ内のアクティブ市場を 24 時間ボリューム降順で取得する:
特定の市場だけが必要な場合は、slug や id の配列を渡してペイロードを減らし、リスト走査を避けてください。
5. Events エンドポイント
/events エンドポイントは市場をイベント単位のメタデータの下にグループ化して返します（例: 複数の市場条件を含む "2026 Presidential Election" のようなイベント）。
基本的な呼び出し:
curl "https://gamma-api.polymarket.com/events?limit=50"
Events も after_cursor を使ったページネーションを持ち、/markets と共有するリスト呼び出しの合計制限 (combined listing limit) に含まれます（/markets + /events の合計で 10 秒あたり 900 req）。
6. 実践的な TypeScript 例: condition_ids で市場を取得する
この例は、複数の condition ID に対して市場を取得し、同時実行制御と指数バックオフを入れたものです。
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) を使う。
- 可能なら ETag / If-None-Match で未変更結果をキャッシュする（API がサポートする場合）。
- ドキュメント化された制限に対してリクエストレートを監視する。
7. よくある落とし穴とトラブルシューティング
- offset を使わないでください — Gamma は offset パラメータに対して HTTP 422 を返します。
- カーソルを使わずに巨大なページを要求すると、レート制限やメモリ圧迫に遭遇します。小さい limit とカーソル走査を優先してください。
- /markets と /events の合計リスト制限により、両方を激しくポーリングするとすぐにスロットリングされる可能性があります。
- API はキーセットページネーションのために next_cursor を返します。next_cursor は不透明な文字列として扱い、そのまま渡してください。
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 は市場メタデータ、タグ、一覧の正準的な読み取りソースです。カーソルページネーションを使い、積極的にフィルタし、Gamma の読み取りを CLOB API や Market WebSocket の価格・オーダーブックデータと組み合わせてください。ドキュメント化されたレート制限に沿ってポーリング頻度を計画し、スロットリングを避けてください。
Gamma は公開データの読み取り専用です; 上記の例は認証不要です。注文配置やブック操作には API key + HMAC が必要な CLOB API (https://clob.polymarket.com) を使ってください。
締め
この Polymarket Gamma API チュートリアルでは、市場とイベントの取得、カーソルページネーションの処理、一般的な落とし穴の回避について実践的に解説しました。これらのパターンを基礎にして、Gamma のレート制限とページネーションモデルを尊重する信頼できるボットや分析基盤を構築してください。
よくある質問
Gamma API を読むのに API キーは必要ですか？
いいえ。Gamma の公開読み取りエンドポイントは認証を必要としません。ベース URL は https://gamma-api.polymarket.com です。注文配置には API key + HMAC が必要な CLOB エンドポイントだけが該当します。
大きな市場リストをページングするにはどうすれば良いですか？
カーソルベースのページネーションを使ってください。各一覧は 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) を使ってください。WebSocket は接続あたり最大 500 銘柄をサポートします。
タグや condition で市場をフィルタできますか？
はい。Gamma は tag_id、condition_ids、clob_token_ids、slug などのフィルタをサポートします。特定のフィルタを渡すとペイロードが減り、レート制限内に収めやすくなります。
関連ガイド
教育目的の情報のみ。金融・法務・税務の助言ではありません。Polymarket はお住まいの地域で利用できない場合があります。