Polymarket Gamma API tutorial

Tutorial Polymarket Gamma API ini menjelaskan cara mengambil markets dan events dari surface Gamma Polymarket, menangani pagination, dan menerapkan filter umum. Contoh menggunakan curl dan TypeScript sehingga Anda bisa mengintegrasikan pembacaan ke dalam bot, dasbor, atau pipeline analitik.

Ringkasan utama

• Base URL Gamma adalah https://gamma-api.polymarket.com dan tidak memerlukan autentikasi untuk operasi baca.
• Gunakan endpoint /markets dan /events dengan pagination berbasis cursor melalui after_cursor; jangan gunakan offset.
• Hormati rate limit: /markets 300 req / 10 s; gabungan /markets + /events listing limit 900 req / 10 s. Batas keseluruhan API adalah 4000 req / 10 s.
• Filter berdasarkan field seperti condition_ids, clob_token_ids, slug, dan tag_id untuk mengurangi payload dan menghindari mencapai limit.
• Gunakan ukuran halaman kecil dan exponential backoff untuk klien produksi.

1. Gamma basics: endpoints and limits

Base URL read Gamma adalah:

https://gamma-api.polymarket.com

Endpoint yang akan Anda gunakan dalam tutorial ini:

• GET /markets — daftar pasar dan kueri single-market
• GET /events — grup event (berguna untuk metadata tingkat event)

Rate limit penting yang harus dirancang:

• /markets: 300 request per 10 detik
• /markets + /events listing gabungan: 900 request per 10 detik
• Keseluruhan Gamma API: 4000 request per 10 detik

Jika klien Anda akan melakukan polling atau backfill dataset besar, batch dan stagger permintaan serta hormati limit ini.

2. Fetching markets: minimal curl example

Contoh permintaan minimal untuk daftar markets dengan parameter default:

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

Untuk mengontrol ukuran halaman (limit) dan pengurutan:

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

Catatan:

• limit maksimal adalah 1000. Default 20.
• Gamma menolak pagination berbasis offset (HTTP 422). Gunakan after_cursor untuk keyset pagination.

3. Cursor-based pagination (after_cursor)

Gamma mengembalikan next_cursor dalam respons listing. Gunakan nilai itu di after_cursor untuk mengambil halaman berikutnya. Contoh alur dalam TypeScript berikut.

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

Praktik terbaik yang ditunjukkan:

• Gunakan limit untuk mengontrol ukuran halaman dan penggunaan jaringan.
• Hormati next_cursor dan berhenti saat tidak ada.
• Tambahkan jeda kecil atau backoff saat mendekati batas rate.

4. Filtering and query parameters worth knowing

Gamma mendukung banyak query parameter. Paling berguna saat Anda ingin pembacaan yang tertarget:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — semuanya berupa array
• closed (boolean), active, archived
• tag_id — filter berdasarkan kategori
• order — field yang dipisah koma seperti volume24hr, volume, liquidity, endDate
• ascending — boolean (default true)

Contoh: ambil markets aktif dalam sebuah tag, diurutkan berdasarkan volume 24 jam secara menurun:

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

Jika Anda hanya butuh pasar tertentu, kirimkan array slug atau id untuk mengurangi payload dan menghindari pemindaian daftar.

5. Events endpoint

Endpoint /events mengelompokkan markets di bawah metadata tingkat event (mis. "2026 Presidential Election" sebagai event yang berisi beberapa kondisi pasar).

Panggilan dasar:

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

Events juga menggunakan after_cursor untuk pagination dan berbagi batas listing gabungan dengan /markets (900 req / 10 s untuk listing gabungan).

6. Practical TypeScript example: fetch markets by condition_ids

Contoh ini mengambil markets untuk daftar condition ID, dengan kontrol konkruensi dan 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;
}

Catatan penggunaan produksi:

• Gunakan pembatas konkruensi (p-map, p-limit) jika conditionIds besar.
• Cache hasil yang tidak berubah (ETag/If-None-Match) jika API mendukungnya dan sesuai kasus penggunaan Anda.
• Pantau laju permintaan terhadap batas yang didokumentasikan.

7. Common pitfalls and troubleshooting

• Jangan gunakan offset — Gamma mengembalikan HTTP 422 untuk parameter offset.
• Meminta halaman besar tanpa cursor dapat memicu rate limit dan tekanan memori; lebih baik gunakan limit kecil dan traversal cursor.
• Batas gabungan /markets + /events berarti polling berat pada kedua endpoint dapat dengan cepat membuat Anda dit-throttle.
• API mengembalikan next_cursor untuk keyset pagination; perlakukan sebagai opaque dan kirim kembali secara verbatim.

8. Integrating with real-time data

Gamma adalah surface REST untuk metadata dan listing historis. Untuk order-book real-time dan event tick, gunakan Market WebSocket di wss://ws-subscriptions-clob.polymarket.com/ws/market. WebSocket mendukung hingga 500 instrument per koneksi dan mengeluarkan event price_change, best_bid_ask, last_trade_price, dan tick_size_change.

Simpan REST untuk backfill dan WebSocket untuk pembaruan langsung.

9. How this affects your trading or tooling

Jika Anda membangun bot trading, dasbor, atau pipeline data, Gamma adalah sumber baca kanonis untuk metadata pasar, tag, dan listing. Gunakan cursor pagination, filter agresif, dan padukan pembacaan Gamma dengan CLOB API atau Market WebSocket untuk data harga dan order-book. Rencanakan cadence polling sesuai rate limit yang didokumentasikan untuk menghindari throttling.

Gamma hanya untuk baca data publik; tidak diperlukan API key untuk contoh di atas. Untuk penempatan order dan operasi buku gunakan CLOB API di https://clob.polymarket.com, yang memerlukan API key + HMAC.

Closing

Tutorial Polymarket Gamma API ini membahas langkah praktis untuk mengambil markets dan events, menangani cursor pagination, dan menghindari jebakan umum. Gunakan pola ini sebagai dasar untuk bot dan analitik yang andal yang menghormati rate limit dan model pagination Gamma.

Frequently asked questions

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

Tidak. Endpoint baca publik Gamma tidak memerlukan autentikasi. Base URL adalah https://gamma-api.polymarket.com. Hanya endpoint CLOB yang memerlukan API key + HMAC untuk trading.

How do I page through large market lists?

Gunakan pagination berbasis cursor. Setiap listing mengembalikan next_cursor; kirim nilai itu sebagai after_cursor untuk mengambil halaman berikutnya. Gamma menolak pagination berbasis offset dengan HTTP 422.

What are the important rate limits to consider?

/markets memiliki batas 300 request per 10 detik. Panggilan listing gabungan /markets + /events dihitung terhadap batas gabungan 900 req / 10 s. Batas keseluruhan Gamma API adalah 4000 req / 10 s. Susun permintaan dan terapkan backoff untuk menghindari throttling.

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

Gunakan Gamma untuk metadata, listing, dan bacaan historis. Gunakan Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) untuk order-book real-time dan event tick; WebSocket mendukung hingga 500 instrument per koneksi.

Can I filter markets by tag or condition?

Ya. Gamma mendukung filter seperti tag_id, condition_ids, clob_token_ids, slug, dan lainnya. Mengirim filter spesifik mengurangi payload dan membantu tetap dalam batas rate.