Polymarket API rate limits — Gamma, Data & CLOB

Had kadar API Polymarket adalah throttle yang perlu anda reka bentuk di sekelilingnya apabila membina bot, papan pemuka, atau analitik. Panduan ini menyenaraikan had yang didokumentasikan untuk setiap permukaan awam (Gamma, Data, CLOB, dan Market WebSocket), menerangkan kekangan penting Gamma /markets (termasuk peraturan 300 req / 10 s untuk /markets dan pagination berasaskan cursor), dan memberi strategi konkrit—pembungkusan (batching), caching, pagination cursor, exponential backoff—untuk memastikan klien anda boleh dipercayai di bawah beban.

Perkara penting

• Endpoint /markets Gamma: 300 permintaan setiap 10 saat; gunakan parameter limit dan after_cursor untuk pagination (jangan gunakan offset).
• Had penyenaraian gabungan: panggilan penyenaraian /markets + /events berkongsi had 900 req / 10 s; keseluruhan Gamma: 4000 req / 10 s.
• Gunakan API CLOB dan Data untuk bacaan terspesialisasi; CLOB memerlukan API key + HMAC untuk panggilan dagangan, bacaan adalah awam.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) menyediakan data masa nyata; utamakan WS untuk kemas kini buku langsung berbanding polling.
• Corak mitigasi: request coalescing, caching TTL, exponential backoff dengan jitter, penjadualan yang sedar kadar, dan pengambilan sensitif pagination.

Mengapa had kadar penting

Had kadar melindungi infrastruktur bersama Polymarket dan menghalang klien bising daripada merendahkan pengalaman pengguna lain. Untuk pembangun yang membina bot arbitrage atau sistem analitik, terkena had menyebabkan permintaan ditolak serta-merta dan boleh merosakkan aliran yang sensitif kepada masa. Merancang corak permintaan dari awal mengurangkan kejutan dan menjadikan sistem lebih tahan.

Had kadar dan endpoint Polymarket yang didokumentasikan

Gamma (metadata pasaran utama)

• Base URL: https://gamma-api.polymarket.com
• Had penting:
  • /markets: maks 300 permintaan setiap 10 saat. Gunakan parameter limit (maks 1000) dan pagination berasaskan cursor melalui after_cursor. API menolak offset dengan HTTP 422.
  • Had penyenaraian gabungan /markets + /events: 900 permintaan setiap 10 saat.
  • Permukaan Gamma keseluruhan: 4000 permintaan setiap 10 saat.

Nota praktikal:

• Sentiasa utamakan after_cursor yang dikembalikan oleh panggilan sebelumnya; jangan cuba meniru keyset menggunakan offset.
• Laraskan limit untuk mengurangkan pusingan panggilan. Jika anda perlukan senarai pasaran penuh, limit=1000 mengurangkan bilangan panggilan.

Data (positions, trades, holders)

• Base URL: https://data-api.polymarket.com
• Auth: Tiada untuk bacaan awam.
• Dokumen ringkas permukaan ini tetapi tidak menyenaraikan nombor kadar per-endpoint untuk Data. Anggap Data sebagai awam, tetapi laksanakan kawalan klien sisi yang sama konservatif seperti Gamma (batching, caching, backoff).

CLOB (order book dan dagangan)

• Base URL: https://clob.polymarket.com
• Bacaan adalah awam. Dagangan memerlukan API key + HMAC.
• Permukaan CLOB mendedahkan order book, midpoint, sejarah harga, dan penempatan/pembatalan pesanan. Dokumen tidak menerbitkan nombor kadar per-endpoint yang jelas untuk bacaan CLOB; anggap laluan dagangan sensitif kadar dan gunakan CLOB WebSocket atau Market WS untuk data buku langsung bila boleh.

Market WebSocket (kemas kini pasaran masa nyata)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Tiada pengesahan diperlukan untuk data pasaran.
• Feed: real-time book, price_change, best_bid_ask (dayakan dengan custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING heartbeat setiap 10 saat. Maks 500 instrumen setiap sambungan.

Perincian Gamma /markets yang mesti anda patuhi

• Pagination: hanya after_cursor. API mengembalikan next_cursor — hantarkan semula tanpa ubah pada panggilan seterusnya.
• limit lalai ialah 20, maks 1000. Gunakan limit yang lebih besar untuk sync pukal.
• Parameter penapis yang diterima termasuk array untuk slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address dan lain-lain seperti closed, active, archived, tag_id.
• Pengurutan: order menerima senarai medan berkoma (contoh volume24hr,liquidity) dan ascending adalah boolean dengan lalai true.

Isyarat ralat biasa dan bagaimana bertindak

• HTTP 429 (rate limited): hentikan polling segera, back off, dan cuba semula dengan exponential backoff dan jitter.
• HTTP 422 semasa menggunakan offset: beralih kepada pagination after_cursor.
• Respons separa atau halaman kosong: hormati cursor; semak penapis anda. Jika anda percaya anda telah mencapai kuota sisi pelayan, kurangkan concurrency permintaan klien.

Corak reka bentuk untuk mengelak throttles

1. Cache dengan agresif

• Cache senarai pasaran dan metadata untuk TTL pendek (30s–2m) bergantung pada penggunaan. Senarai pasaran dan acara jarang berubah setiap saat.
• Cache mengikut kunci pertanyaan (penapis + order). Nyahsah cache hanya apabila anda menerima acara perubahan (contohnya, daripada WebSocket) atau selepas tamat TTL.

2. Batch dan tingkatkan limit

• Untuk full-sync, gunakan limit=1000 untuk mengurangkan pusingan terhadap /markets.
• Tarik halaman lebar semasa tingkap luar puncak dan gunakan kemas kini inkremental daripada WebSocket.

3. Gunakan WebSocket untuk data masa nyata

• Untuk kemas kini buku pesanan atau pergerakan harga langsung, langgan Market WS daripada melakukan polling Gamma atau bacaan CLOB. WS menyokong sehingga 500 instrumen setiap sambungan; bahagikan pelanggan jika anda memerlukan >500.

4. Penjadualan yang sedar kadar dan backoff

• Laksanakan limiter klien sisi seperti leaky-bucket atau token-bucket yang sepadan dengan puncak yang didokumentasikan (contohnya, 300/10s untuk /markets).
• Apabila anda menerima 429, gunakan exponential backoff dengan jitter dan secara progresif tingkatkan jangka masa percubaan semula.

5. Gabungkan permintaan serentak yang serupa

• Jika berbilang bahagian aplikasi anda meminta pertanyaan /markets yang sama serentak, gabungkan mereka kepada satu permintaan sedang berjalan dan edarkan respons kepada peminta lain.

6. Penyegerakan berasaskan cursor terlebih dahulu

• Sentiasa ikut pagination berasaskan cursor. Untuk sync langsung, minta halaman pertama kemudian langgan delta jika disokong. Jangan cuba fetch cursor secara serampangan serentak yang boleh melebihi had per-endpoint Gamma.

Strategi fetch contoh

• Tugas pengindeksan pukal (bukan masa nyata): fetch /markets?limit=1000 kemudian ikut next_cursor sehingga habis. Tidur sebentar antara halaman, dan hormati had endpoint 300/10s.
• UI hampir-masa-nyata: fetch set asas sekali (cache 30s), kemudian buka WebSocket untuk delta dan kemas kini best_bid_ask.
• Mikro-klien watchlist: bahagikan watchlist merentasi berbilang sambungan WS jika >500 instrumen.

Panduan operasi untuk bot dan klien berkeluaran tinggi

• Gunakan CLOB WebSocket atau bacaan CLOB untuk data peringkat buku dan Gamma untuk metadata yang berubah lebih perlahan.
• Simpan kelayakan dagangan (CLOB API key + HMAC) dengan selamat; endpoint dagangan memerlukan pengesahan.
• Pantau kadar 429 anda dan metrik latensi per-instrumen per-endpoint. Jika anda kerap menghampiri had yang didokumentasikan, minta akses atau hubungi saluran rasmi Polymarket (Builder Program adalah laluan untuk integrasi volum lebih tinggi dan atribusi).

Bagaimana ini mempengaruhi pembangunan dan penyebaran anda

Jika anda membina bot dagangan atau perkhidmatan analitik, rancang aliran data berlapis: fetch pukal awal dari Gamma dengan limit besar, diikuti langganan WebSocket untuk kemas kini langsung, dan set kecil polling berkala Gamma (dicache) untuk mana-mana metadata yang tidak ada dalam feed WS. Laksanakan limitasi sisi klien, coalescing, dan pagination-aware untuk mengelakkan terkena had /markets 300 req / 10 s yang didokumentasikan serta had penyenaraian gabungan dan keseluruhan Gamma.

Ringkasan penutup

Had kadar API Polymarket jelas untuk permukaan penyenaraian Gamma dan Market WS menawarkan alternatif skala untuk feed langsung. Reka bentuk sekitar pagination berasaskan cursor (after_cursor), gunakan limit secara strategik, dan utamakan WebSockets untuk data kekerapan tinggi. Mengikuti corak ini akan mengurangkan throttling dan menjadikan integrasi anda lebih boleh dipercayai.

Soalan Lazim

Apakah had /markets pada Gamma?

Endpoint /markets Gamma dihadkan kepada 300 permintaan setiap 10 saat. Gunakan limit (maks 1000) dan pagination berasaskan cursor melalui after_cursor. Jangan gunakan offset—API menolaknya dengan HTTP 422.

Adakah terdapat had gabungan untuk endpoint Gamma?

Ya. Panggilan penyenaraian kepada /markets dan /events berkongsi cap gabungan 900 permintaan setiap 10 saat. Tambahan pula, permukaan Gamma keseluruhan dihadkan kepada 4000 permintaan setiap 10 saat.

Patutkah saya poll Gamma atau gunakan WebSocket untuk kemas kini langsung?

Utamakan Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) untuk kemas kini buku dan harga langsung—ia lebih cekap dan mengelakkan polling berulang. Gunakan Gamma untuk metadata yang berubah lebih perlahan dan sync pukal awal.

Apa yang klien saya patut lakukan pada respons HTTP 429?

Anggap 429 sebagai isyarat untuk hentikan polling agresif. Laksanakan exponential backoff dengan jitter, kurangkan concurrency, dan gabungkan permintaan yang serupa. Jejak 429 untuk laraskan rate limiter anda secara dinamik.

Adakah API CLOB memerlukan pengesahan?

Bacaan CLOB adalah awam. Operasi dagangan pada CLOB memerlukan API key ditambah pengesahan HMAC. Hormati had dagangan dan utamakan feed WS untuk kemas kini buku.