Polymarket Gamma API tutorial

Tutorial Polymarket Gamma API ini mengajar anda cara mengambil pasaran dan acara dari permukaan Gamma Polymarket, mengendalikan penomboran, dan menggunakan penapis biasa. Contoh menggunakan curl dan TypeScript supaya anda boleh menyepadukan bacaan ke dalam bot, papan pemuka, atau saluran analitik.

Perkara utama yang perlu diingati

• Gamma's base URL is https://gamma-api.polymarket.com and requires no auth for reads.
• Gunakan endpoint /markets dan /events dengan penomboran berasaskan kursor melalui after_cursor; jangan gunakan offset.
• Hormati had kadar: /markets mempunyai 300 req / 10 s; had gabungan /markets + /events untuk penyenaraian ialah 900 req / 10 s. Had keseluruhan API ialah 4000 req / 10 s.
• Tapiskan mengikut medan seperti condition_ids, clob_token_ids, slug, dan tag_id untuk mengurangkan muatan dan mengelakkan melepasi had.
• Gunakan saiz halaman kecil dan exponential backoff untuk klien produksi.

1. Gamma basics: endpoints and limits

URL asas bacaan Gamma ialah:

https://gamma-api.polymarket.com

Endpoint yang akan anda gunakan dalam tutorial ini:

• GET /markets — senarai pasaran dan pertanyaan satu-pasaran
• GET /events — acara berkumpulan (berguna untuk metadata peringkat acara)

Had kadar penting untuk direka bentuk di sekelilingnya:

• /markets: 300 requests per 10 seconds
• /markets + /events listing combined: 900 requests per 10 seconds
• Overall Gamma API: 4000 requests per 10 seconds

Jika klien anda akan membuat poll atau backfill dataset besar, kumpulkan dan jarakkan permintaan serta hormati had ini.

2. Fetching markets: minimal curl example

Permintaan minimum untuk menyenaraikan pasaran dengan parameter lalai:

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

Untuk mengawal saiz halaman (limit) dan penyusunan:

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

Nota:

• had maksimum limit ialah 1000. Lalai ialah 20.
• Gamma menolak penomboran berasaskan offset (HTTP 422). Gunakan after_cursor untuk penomboran keyset sebaliknya.

3. Cursor-based pagination (after_cursor)

Gamma memulangkan next_cursor dalam respons penyenaraian. Gunakan nilai itu dalam after_cursor untuk mengambil halaman seterusnya. Aliran contoh 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;
}

Amalan terbaik yang ditunjukkan:

• Gunakan limit untuk mengawal saiz halaman dan penggunaan rangkaian.
• Hormati next_cursor dan berhenti bila ia tiada.
• Tambah kelewatan kecil atau backoff apabila anda hampir kepada had kadar.

4. Filtering and query parameters worth knowing

Gamma menyokong banyak parameter pertanyaan. Paling berguna apabila anda mahukan bacaan yang disasarkan:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — semua dalam bentuk array
• closed (boolean), active, archived
• tag_id — tapis mengikut kategori
• order — medan berasingan dengan koma seperti volume24hr, volume, liquidity, endDate
• ascending — boolean (lalai true)

Contoh: ambil pasaran aktif dalam satu tag, tersusun mengikut volume 24h menurun:

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

Apabila anda hanya memerlukan pasaran tertentu, hantarkan array untuk slug atau id untuk mengurangkan muatan dan mengelakkan imbasan senarai.

5. Events endpoint

Endpoint /events mengumpulkan pasaran di bawah metadata peringkat acara (contoh: "2026 Presidential Election" sebagai acara yang mengandungi berbilang kondisi pasaran).

Panggilan asas:

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

Acara juga menggunakan after_cursor untuk penomboran dan berkongsi had penyenaraian gabungan dengan /markets (900 req / 10 s untuk penyenaraian gabungan).

6. Practical TypeScript example: fetch markets by condition_ids

Contoh ini mengambil pasaran untuk senarai ID condition, dengan kawalan kebolehkawalan selari 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;
}

Nota untuk penggunaan produksi:

• Gunakan pengehad kebolehkawalan selari (p-map, p-limit) jika conditionIds besar.
• Cache keputusan yang tidak berubah (ETag/If-None-Match) jika API menyokongnya untuk kes penggunaan anda.
• Pantau kadar permintaan anda berbanding had yang didokumenkan.

7. Common pitfalls and troubleshooting

• Jangan gunakan offset — Gamma memulangkan HTTP 422 untuk parameter offset.
• Meminta halaman besar tanpa kursor boleh melepasi had kadar dan memberi tekanan memori; pilih had yang lebih kecil dan lintas kursor.
• Had penyenaraian gabungan /markets + /events bermakna polling berat kedua-dua endpoint boleh mengehadkan anda dengan cepat.
• API memulangkan next_cursor untuk penomboran keyset; anggap ia sebagai opak dan hantarkan kembali tanpa mengubahnya.

8. Integrating with real-time data

Gamma ialah permukaan REST untuk metadata dan penyenaraian sejarah. Untuk buku pesanan masa nyata dan acara tick, gunakan Market WebSocket di wss://ws-subscriptions-clob.polymarket.com/ws/market. WebSocket menyokong sehingga 500 instrumen setiap sambungan dan mengeluarkan event price_change, best_bid_ask, last_trade_price, dan tick_size_change.

Simpan REST untuk backfill dan WebSocket untuk kemas kini langsung.

9. How this affects your trading or tooling

Jika anda membina bot dagangan, papan pemuka, atau saluran data, Gamma ialah sumber baca kanonik untuk metadata pasaran, tag, dan penyenaraian. Gunakan penomboran kursor, tapis secara agresif, dan padankan bacaan Gamma dengan CLOB API atau Market WebSocket untuk data harga dan buku pesanan. Rancang kekerapan poll anda mengikut had kadar yang didokumenkan untuk mengelakkan throttle.

Gamma ialah baca sahaja untuk data awam; tiada kunci API diperlukan untuk contoh di atas. Untuk penempatan pesanan dan operasi buku gunakan CLOB API di https://clob.polymarket.com, yang memerlukan API key + HMAC.

Closing

Tutorial Polymarket Gamma API ini merangkumi langkah praktikal untuk mengambil pasaran dan acara, mengendalikan penomboran kursor, dan mengelakkan perangkap biasa. Gunakan corak ini sebagai asas untuk bot dan analitik yang boleh dipercayai yang menghormati had kadar dan model penomboran Gamma.

Frequently asked questions

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

No. Gamma's public read endpoints do not require authentication. The base URL is https://gamma-api.polymarket.com. Only the CLOB endpoint requires API key + HMAC for trading.

How do I page through large market lists?

Use cursor-based pagination. Each listing returns next_cursor; pass that value as after_cursor to fetch the next page. Gamma rejects offset-based pagination with HTTP 422.

What are the important rate limits to consider?

/markets has a limit of 300 requests per 10 seconds. Combined /markets + /events listing calls count toward a 900 req / 10 s combined limit. The overall Gamma API limit is 4000 req / 10 s. Stagger requests and implement backoff to avoid throttling.

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

Use Gamma for metadata, listings, and historical reads. Use the Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) for real-time order-book and tick events; the WebSocket supports up to 500 instruments per connection.

Can I filter markets by tag or condition?

Yes. Gamma supports filters such as tag_id, condition_ids, clob_token_ids, slug, and others. Passing specific filters reduces payload and helps stay within rate limits.