Tutorial Bot Polymarket · Bab 8 dari 32

Polymarket CLOB API untuk bot: REST endpoints untuk order book snapshots, WebSocket subscriptions untuk update real-time, parsing bids/asks, menghitung mid-price dan depth, contoh code.

Oleh Harley Young, penulis utama di Polymarkets.co.il. Terakhir diperiksa: Mei 2026.

Apa yang dibahas di bab ini

CLOB API adalah tempat order ditandatangani, dikirim, dicocokkan, dan tempat order book berada. Polymarket memiliki dua generasi SDK - v1 yang deprecated dan v2 yang saat ini dipakai. Bab ini hanya membahas v2; v1 tidak boleh muncul di bot apa pun yang Anda rilis pada 2026. Kami membahas jalur REST snapshot, channel update WebSocket, detail parsing yang sering menjebak builder baru, dan logika reconnect yang tanpanya bot yang berjalan lama akan keluar dari sync dalam hitungan jam.

  • CLOB v1 vs v2 (gunakan v2]
  • Order book REST snapshot
  • WebSocket subscriptions: channel market dan user
  • Parsing bids/asks/depth
  • Menghitung mid-price dan best-bid/ask
  • Maker fees, taker fees, rebates
  • Code: connect WS dan process price-change events
  • Reconnect dan gap-handling

CLOB v1 vs v2 (gunakan v2]

Polymarket mempertahankan dua generasi SDK. v1 (@polymarket/clob-client di npm, py-clob-client <0.30) sudah deprecated dan tidak memiliki beberapa order type yang ditambahkan pada 2024. v2 (@polymarket/clob-client-v2 v1.0.2 di Node, py-clob-client 0.34.6+ di Python) adalah standar saat ini.

Ada tiga perbedaan konkret. v2 mendukung flag negRisk untuk market multi-outcome - diperlukan sejak NegRisk exchange diluncurkan pada akhir 2024. v2 menyertakan TypeScript types untuk bentuk message WebSocket; v1 mengembalikan any. v2 menangani alur signature Gnosis Safe Agustus 2025 secara native; v1 memerlukan custom signing glue.

Sisa bab ini ditulis dengan asumsi v2 secara menyeluruh. Jika Anda melihat code v1 di tutorial lama, anggap itu rusak sampai terbukti sebaliknya - khususnya order placement ke market NegRisk akan diam-diam diarahkan ke contract exchange yang salah pada v1.

Order book REST snapshot

Endpoint REST snapshot mengembalikan full book untuk satu token pada satu titik waktu.

GET https://clob.polymarket.com/book?token_id=<ERC1155_TOKEN_ID>

Bentuk response:

{
  "market": "0x...",
  "asset_id": "5413...",
  "timestamp": "1715600000000",
  "hash": "0x...",
  "bids": [{"price":"0.45","size":"120"}, {"price":"0.44","size":"380"}, ...],
  "asks": [{"price":"0.47","size":"85"}, {"price":"0.48","size":"210"}, ...]
}

Harga adalah string dengan 2-3 angka desimal; size adalah string yang merepresentasikan jumlah share (bukan dolar). Bids diurutkan dari tinggi ke rendah, asks dari rendah ke tinggi. hash adalah penanda deduplikasi - polling berulang pada book yang tidak berubah akan mengembalikan hash yang sama dan bot Anda bisa melewati prosesnya.

REST snapshot adalah pilihan yang tepat untuk lookup sekali pakai (cek harga saat mengambil keputusan entry). Untuk monitoring kontinu, gunakan channel WebSocket di bawah.

WebSocket subscriptions: channel market dan user

Ada dua channel WebSocket yang penting.

Channel market: wss://ws-subscriptions-clob.polymarket.com/ws/market. Subscribe ke satu atau banyak token; terima update order book saat terjadi perubahan.

{"type":"Market","markets":["0xCondId1","0xCondId2"]}

Message masuk setiap ada perubahan. Tipe termasuk book (full snapshot), price_change (delta), tick_size_change (jarang), dan last_trade_price (fill terbaru).

Channel user: wss://ws-subscriptions-clob.polymarket.com/ws/user. Terautentikasi; menerima event order Anda sendiri - fill, partial fill, cancellation.

{"type":"User","auth":{"apiKey":"...","secret":"...","passphrase":"..."}}

Channel user adalah cara paling bersih untuk mendeteksi fill. Polling endpoint REST orders lebih mahal dan bisa melewatkan perubahan state di antara polling; WebSocket mendorong event tepat saat matcher mengakuinya.

Parsing bids/asks/depth

Order book adalah daftar price level dengan size yang diagregasi. Ada dua konvensi parsing yang harus benar.

Arah order: bids adalah buy orders (seseorang ingin BUY pada harga ini). Saat bot ANDA menjual, Anda memukul bid. Saat bot Anda membeli, Anda mengangkat ask. UI Polymarket menampilkan arah yang sama; beberapa exchange lain membaliknya.

Sorting: bids datang terurut menurun (best bid dulu). asks datang terurut menaik (best ask dulu). Best bid adalah bids[0]; best ask adalah asks[0]. Hati-hati: public WebSocket kadang mengirim partial book update yang belum tersortir - selalu re-sort secara defensif setelah merge apa pun.

Depth pada satu level adalah nilai dolar yang bisa ditransaksikan: price * size. Depth top-5 level adalah metrik likuiditas yang umum: sum(b.price * b.size for b in bids[:5]). Jika depth top-5 di bawah $100, book tersebut tidak likuid dan sebagian besar asumsi strategi akan gagal.

Menghitung mid-price dan best-bid/ask

Ada tiga price point turunan yang dibutuhkan bot Anda.

  • Best bid / best ask: bids[0].price dan asks[0].price. Harga yang benar-benar bisa Anda trade, satu share.
  • Mid-price: (best_bid + best_ask) / 2. Titik tengah matematis dari spread. Berguna untuk valuasi; Anda tidak pernah trade di mid.
  • VWAP price untuk size N: telusuri book sampai cumulative size mencapai N, lalu kembalikan size-weighted average price. Biaya aktual untuk BUY N share sekarang, dengan memperhitungkan sweep ke level yang lebih dalam.

Kasus edge: sisi bid atau ask yang kosong (tidak ada yang menjual, atau tidak ada yang membeli) berarti book one-sided. Dalam struktur market Polymarket, ini terjadi pada market yang sudah resolved atau hampir resolved ketika satu sisi berada di 0.999 dan tidak ada yang menawarkan likuiditas di sisi yang kalah. Perlakukan best-bid = 0 atau best-ask = 1 sebagai sinyal "jangan trade".

Maker fees, taker fees, rebates

Polymarket menjalankan model fee maker-taker. Angka per Mei 2026:

  • Taker fee: 0 (nol) - order yang mengangkat existing book liquidity tidak membayar fee. Perhatikan bahwa gas / biaya network tetap berlaku untuk operasi proxy.
  • Maker rebate: kecil dan positif, programmatic, dibayarkan per rested order yang ter-fill pada market reward-program yang memenuhi syarat. Tidak semua market memiliki reward.
  • NegRisk markets: struktur fee yang sama tetapi pada contract exchange terpisah; rewards terakumulasi secara terpisah.

Taker fee nol membuat Polymarket berbeda secara signifikan dari venue CFD tradisional - sebagian besar "biaya" trading adalah spread bid-ask itu sendiri, bukan fee eksplisit. Untuk strategi yang menyeberangi spread pada setiap trade, spread tax adalah biaya nyata; asumsikan 1-3 sen round-trip pada book biasa, lebih besar pada yang tidak likuid.

Maker rebate hanya layak dikejar ketika market yang eligible untuk liquidity rewards selaras dengan ide strategi. Bab 19 membahas liquidity-rewards farming sebagai pendekatan khusus.

Code: connect WS dan process price-change events

Contoh Node minimal: connect, subscribe, log setiap event price-change untuk satu token.

import WebSocket from "ws";
const ws = new WebSocket("wss://ws-subscriptions-clob.polymarket.com/ws/market");
ws.on("open", () => {
  ws.send(JSON.stringify({ type: "Market", markets: ["<CONDITION_ID>"] }));
});
ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.event_type === "price_change") {
    console.log("price_change", msg.asset_id, msg.changes);
  } else if (msg.event_type === "book") {
    console.log("book snapshot", msg.bids?.[0], msg.asks?.[0]);
  }
});
ws.on("close", () => console.log("closed"));
ws.on("error", (e) => console.error("err", e.message));

Subscribe hingga sekitar 30 token per koneksi WebSocket masih nyaman. Di atas itu, bagi ke beberapa koneksi - server kadang menjatuhkan subscription besar tanpa error, yang menghasilkan stale book reads secara diam-diam.

Reconnect dan gap-handling

Koneksi WebSocket yang berjalan lama akan terputus. Cloudflare me-recycle koneksi setiap beberapa jam; network berkedip; Polymarket kadang melakukan deploy. Rencanakan untuk itu.

Strategi reconnect: saat close atau error, tunggu min(2^attempt, 30) detik dengan jitter, lalu subscribe ulang. Reset counter attempt pada message pertama yang berhasil setelah reconnect.

Gap-handling lebih penting daripada kecepatan reconnect. Selama WebSocket terputus, book bergerak. Pada setiap reconnect, ambil ulang REST snapshot dari setiap token yang disubscribe dan lakukan reconciliation: posisi terbuka apa pun yang book-nya bergerak signifikan perlu pengecekan state ulang, exit mungkin perlu dieksekusi, alarm bisa jadi sudah stale. Kasus "saya melewatkan 30 detik update book" adalah pembunuh diam-diam bot jangka panjang - mereka terus berjalan dengan state yang stale dan memasang order pada harga yang sudah tidak ada lagi.

Pola defensif: snapshot setiap book yang disubscribe sekali per menit terlepas dari state WebSocket, dan perlakukan WS sebagai optimisasi fast-path di atas polling snapshot.

Pertanyaan yang sering diajukan

Apa endpoint Polymarket CLOB API?
Base CLOB endpoint adalah https://clob.polymarket.com (REST) dan wss://ws-subscriptions-clob.polymarket.com/ws/market (WebSocket). Ini adalah endpoint V2 yang digunakan oleh @polymarket/clob-client-v2 dan py-clob-client.
Apakah saya perlu API key untuk membaca order book?
Tidak. Pembacaan order book (snapshot dan WebSocket subscriptions) bersifat public dan tidak memerlukan autentikasi. Anda hanya memerlukan API key untuk memasang/membatalkan order dan membaca data spesifik akun (positions, fills).
Seberapa cepat CLOB WebSocket mengirim update harga?
Sesuai kecepatan order match. Market aktif melihat update setiap beberapa ratus milidetik; market tipis hanya update saat ada order aktual. Baik perubahan depth maupun trade event mengalir melalui channel WS yang sama - parse event type untuk menangani masing-masing dengan benar.
Bagaimana cara menghitung mid-price dari order book Polymarket?
mid = (best_bid + best_ask) / 2 jika keduanya ada; jika tidak, gunakan last_trade_price sebagai fallback. Hati-hati dengan book tipis di mana best_bid jauh di bawah best_ask - mid bisa jadi tidak bermakna. Selalu pertimbangkan spread sebelum memperlakukan mid sebagai harga wajar.
Berapa maker fee di Polymarket pada 2026?
0% untuk sebagian besar kategori. Maker memperoleh rebate setara 20-25% dari taker fees. Taker fees bervariasi حسب kategori: 0,75% sports, 1,00% politics, 1,25% economics, 1,80% crypto. Asimetri rebate-vs-fee inilah sebabnya bot aktif hampir selalu meng-quote dengan limit orders daripada market orders.
Bagaimana cara menangani WebSocket disconnect?
Reconnect dengan exponential backoff (1s, 2s, 4s, maksimum 30s), subscribe ulang ke market yang sama, dan ambil ulang REST snapshot untuk mengisi gap. Jangan pernah mempercayai order book yang stale - jika Anda terputus lebih dari 5 detik, minta snapshot baru sebelum memasang order.