Polymarket Bot Tutorial · 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.6 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

Sepanjang sebagian besar sejarahnya, Polymarket sama sekali tidak memungut fee trading. Itu berubah pada 2026: fee diperkenalkan di awal tahun pada market crypto 15 menit, diperluas ke Sports pada 30 Maret 2026, dan sejak itu digulirkan ke sebagian besar kategori. Tutorial mana pun yang masih mengklaim Polymarket bebas fee sudah usang - dan siapa pun yang melewatkannya dalam strategi frekuensi tinggi akan dimakan diam-diam. Beginilah model itu benar-benar bekerja, per pertengahan 2026.

Pertama, dua sisi setiap trade. Maker adalah pihak yang menaruh limit order yang beristirahat di book dan menunggu di sana; taker adalah pihak yang mengirim order yang langsung dieksekusi terhadap likuiditas yang sudah ada. Maker tetap membayar nol fee dan justru menerima rebate; hanya taker yang membayar fee.

Taker fee bukan persentase tetap. Ia mengikuti kurva yang bergantung pada ukuran order maupun harga:

fee = shares × feeRate × price × (1 - price)

Suku price × (1 - price) maksimum pada harga 0,50 (market lempar-koin sejati) dan menyusut menuju 0 atau 1. Dengan kata lain, di market paling tidak pasti Anda membayar fee tertinggi, dan di market yang nyaris ditentukan hampir tidak ada. feeRate ditetapkan per kategori:

  • Crypto: feeRate 0,07 (tertinggi, puncak efektif sekitar 1,8%), maker rebate 20%.
  • Sports: feeRate 0,03 (puncak sekitar 0,75%), maker rebate 25%.
  • Finance, Politics, Tech, Mentions: feeRate 0,04, maker rebate 25%.
  • Economics, Culture, Weather, umum: feeRate 0,05, maker rebate 25%.
  • Geopolitics dan peristiwa dunia besar: 0, masih bebas fee.

Contoh perhitungan. Misalkan bot Anda mengambil 100 shares dari market crypto pada harga 0,50. Fee-nya adalah 100 × 0,07 × 0,50 × (1 - 0,50) = 100 × 0,07 × 0,25 = $1,75. Jika Anda mengambil 100 shares yang sama pada 0,90, fee turun menjadi 100 × 0,07 × 0,90 × 0,10 = $0,63, karena harga jauh dari tengah yang tidak pasti. Bagi bot, pelajarannya jelas: mengambil likuiditas di market crypto dan sports yang volatil dan nyaris seimbang menelan fee paling besar - jadi justru di situlah paling menguntungkan untuk meng-quote sebagai maker dan mengantongi rebate alih-alih membayar fee.

Selain fee eksplisit, setiap kali Anda menyeberangi spread bid-ask, Anda membayarnya. Spread adalah selisih antara harga beli terbaik dan harga jual terbaik, dan bagi strategi yang masuk dan keluar sebagai taker, selisih itu adalah biaya nyata di atas fee. Asumsikan 1-3 sen round-trip pada book biasa, lebih besar pada yang tidak likuid. Market NegRisk (multi-outcome exchange) memakai model fee yang sama tetapi settle pada contract terpisah, sehingga rewards-nya terakumulasi terpisah. Bab 19 membahas liquidity-rewards farming, di mana mengantongi maker rebate adalah strateginya sendiri, bukan sekadar efek samping.

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?
Maker membayar 0% dan menerima rebate (20% di crypto, 25% di sebagian besar kategori lain). Hanya taker yang membayar fee, dan fee itu tidak tetap: ia mengikuti fee = shares × feeRate × price × (1 - price), sehingga memuncak di market lempar-koin sekitar 0,50 dan menyusut menuju ujung. feeRate per kategori berkisar dari 0,03 (Sports, sekitar 0,75% puncak efektif) hingga 0,07 (Crypto, sekitar 1,8% puncak efektif), dengan Geopolitics yang masih bebas fee. Asimetri maker-taker inilah sebabnya bot aktif hampir selalu meng-quote dengan limit order yang beristirahat alih-alih menyeberangi spread dengan market order.
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.