Polymarket Bot Tutorial · Kabanata 8 ng 32

Polymarket CLOB API para sa bots: REST endpoints para sa order book snapshots, WebSocket subscriptions para sa real-time updates, pag-parse ng bids/asks, pag-compute ng mid-price at depth, code samples.

Ni Harley Young, pangunahing manunulat sa Polymarkets.co.il. Huling rebyu: Mayo 2026.

Ano ang sinasaklaw ng kabanatang ito

Ang CLOB API ay kung saan na-sign, ipinadala, na-match ang orders, at kung saan nakatira ang order book. Ang Polymarket ay may dalawang SDK generations - ang deprecated v1 at ang kasalukuyang v2. Sinasaklaw lamang ng kabanata ito ang v2; ang v1 ay hindi dapat lumitaw sa anumang bot na ini-ship mo noong 2026. Naglalakad kami sa REST snapshot path, WebSocket update channel, parsing details na nagdadala ng problema sa bagong builders, at reconnect logic kung saan ang long-running bot ay nag-drift palabas ng sync sa loob ng mga oras.

Ito ay kabanata 8 ng aming 32-part series sa pagbuo ng Polymarket trading bot.

  • CLOB v1 vs v2 (gamitin ang v2)
  • Order book REST snapshot
  • WebSocket subscriptions: market at user channels
  • Pag-parse ng bids/asks/depth
  • Pag-compute ng mid-price at best-bid/ask
  • Maker fees, taker fees, rebates
  • Code: kumonekta sa WS at iproseso ang price-change events
  • Reconnect at gap-handling

CLOB v1 vs v2 (gamitin ang v2)

Nagpapanatili ang Polymarket ng dalawang SDK generations. Ang v1 (@polymarket/clob-client sa npm, py-clob-client <0.30) ay deprecated at nawawala ng ilang order types na idinagdag noong 2024. Ang v2 (@polymarket/clob-client-v2 v1.0.2 sa Node, py-clob-client 0.34.6+ sa Python) ay ang kasalukuyang standard.

Tatlong concrete na pagkakaiba. Ang v2 ay sumusuporta sa negRisk flag para sa multi-outcome markets - kinakailangan mula nang i-launch ang NegRisk exchange noong huling bahagi ng 2024. Ang v2 ay nag-ship ng TypeScript types para sa WebSocket message shapes; ang v1 ay nag-return ng any. Ang v2 ay humahawak ng Agosto 2025 Gnosis Safe signature flow natively; ang v1 ay nangangailangan ng custom signing glue.

Ang natitirang bahagi ng kabanatang ito ay nakasulat na nag-aassume ng v2 sa buong. Kung makakita ka ng v1 code sa mas matandang tutorial, treat ito bilang sira hanggang sa mapatunayan ang iba - ang order placement laban sa NegRisk markets lalo na ay tahimik na mag-route sa maling exchange contract sa ilalim ng v1.

Order book REST snapshot

Nag-return ang REST snapshot endpoint ng full book para sa isang token sa isang punto sa oras.

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

Response shape:

{
  "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"}, ...]
}

Ang prices ay strings na may 2-3 decimal places; ang sizes ay strings na nagrerepresenta ng share counts (hindi dollars). Ang bids ay sorted high-to-low, asks low-to-high. Ang hash ay deduplication marker - ang paulit-ulit na polls ng hindi nagbabagong book ay nag-return ng parehong hash at maaaring laktawan ng iyong bot ang processing.

Ang REST snapshot ay ang tamang call para sa one-off lookups (price check sa entry decision). Para sa continuous monitoring, gamitin ang WebSocket channel sa ibaba.

WebSocket subscriptions: market at user channels

Dalawang WebSocket channels ang mahalaga.

Market channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. Mag-subscribe sa isa o maraming tokens; tumanggap ng order-book updates habang nangyayari sila.

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

Ang messages ay dumarating sa bawat pagbabago. Ang mga types ay kasama ang book (full snapshot), price_change (delta), tick_size_change (bihira), at last_trade_price (pinakabagong fill).

User channel: wss://ws-subscriptions-clob.polymarket.com/ws/user. Authenticated; tumanggap ng sariling order events - fills, partial fills, cancellations.

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

Ang user channel ay ang pinakamalinis na paraan para i-detect ang fill. Ang polling ng orders REST endpoint ay gumagastos nang higit pa at maaaring missing state changes sa pagitan ng polls; ang WebSocket ay nag-push ng event sa sandaling kinikilala ito ng matcher.

Pag-parse ng bids/asks/depth

Ang order book ay listahan ng price levels na may aggregated size. Dalawang parsing conventions ang dapat itama.

Order direction: ang bids ay buy orders (may gustong BUMILI sa price na ito). Kapag IBINEBENTA ng iyong bot, tinatamaan mo ang bid. Kapag bumibili ang iyong bot, ina-lift mo ang ask. Pinapakita ng Polymarket UI ang parehong direction; ang ilang ibang exchanges ay nag-invert.

Sorting: ang bids ay dumarating na sorted descending (best bid muna). Ang asks ay dumarating na sorted ascending (best ask muna). Ang best bid ay bids[0]; ang best ask ay asks[0]. Mag-ingat: ang public WebSocket ay paminsan-minsan ay nagpapadala ng partial book updates na hindi pre-sorted - palaging mag-re-sort nang defensive pagkatapos ng anumang merge.

Ang depth sa isang level ay ang transactable dollar value: price * size. Ang top-5-level depth ay karaniwang liquidity metric: sum(b.price * b.size for b in bids[:5]). Kung ang top-5 depth ay nasa ibaba ng $100, ang book ay illiquid at karamihan ng strategy assumptions ay nasisira.

Pag-compute ng mid-price at best-bid/ask

Tatlong derived price points ang kailangan ng iyong bot.

  • Best bid / best ask: bids[0].price at asks[0].price. Ang mga prices na maaaring talagang i-trade, isang share.
  • Mid-price: (best_bid + best_ask) / 2. Ang mathematical center ng spread. Kapaki-pakinabang para sa valuation; hindi ka kailanman nag-trade sa mid.
  • VWAP price para sa size N: maglakad sa book hanggang ang cumulative size ay umabot sa N, ibalik ang size-weighted average price. Ang aktwal na cost para BUMILI ng N shares ngayon, na isinasaalang-alang ang sweep sa mas malalalim na levels.

Edge case: ang empty bid o ask side (walang nagbebenta, o walang bumibili) ay nangangahulugan ang book ay one-sided. Sa market structure ng Polymarket nangyayari ito sa resolved o near-resolved markets kung saan ang isang side ay nasa 0.999 at walang nag-aalok ng liquidity sa loser side. Treat ang best-bid = 0 o best-ask = 1 bilang "huwag mag-trade" signals.

Maker fees, taker fees, rebates

Nag-run ang Polymarket ng maker-taker fee model. Numbers noong Mayo 2026:

  • Taker fee: 0 (zero) - ang mga orders na nag-lift ng existing book liquidity ay hindi nagbabayad ng fee. Tandaan na ang gas / network costs ay nalalapat para sa proxy operations.
  • Maker rebate: maliit na positive, programmatic, binayaran kada filled rested order sa eligible reward-program markets. Hindi lahat ng markets ay may rewards.
  • NegRisk markets: parehong fee structure pero sa hiwalay na exchange contract; ang rewards ay nag-accrue nang hiwalay.

Ang zero taker fee ay nagpapakaiba ng Polymarket nang meaningful mula sa traditional CFD venues - karamihan ng trading "cost" ay ang bid-ask spread mismo, hindi ang explicit fee. Para sa strategy na nag-crossing sa spread sa bawat trade, ang spread tax ang real cost; mag-assume ng 1-3 cents round-trip sa typical books, mas higit pa sa illiquid.

Ang maker rebates ay sulit lang habulin kapag ang liquidity-rewards-eligible markets ay tumutugma sa strategy ideas. Sinasaklaw ng kabanata 19 ang liquidity-rewards farming bilang dedicated approach.

Code: kumonekta sa WS at iproseso ang price-change events

Minimal Node example: kumonekta, mag-subscribe, mag-log ng bawat price-change event para sa isang 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));

Mag-subscribe ng hanggang ~30 tokens per WebSocket connection nang komportable. Sa kabila niyan, hatiin sa maraming connections - paminsan-minsan ay nagpapakawala ng malaking subscriptions ang server nang walang error, na gumagawa ng silent stale book reads.

Reconnect at gap-handling

Ang long-running WebSocket connection ay mag-drop. Ang Cloudflare ay nag-cycle ng connections kada ilang oras; ang networks ay kumikislap; paminsan-minsan ay nag-deploy ang Polymarket. Plano para diyan.

Reconnect strategy: sa close o error, maghintay ng min(2^attempt, 30) segundo na may jitter, pagkatapos ay mag-re-subscribe. I-reset ang attempt counter sa unang successful message pagkatapos ng reconnect.

Ang gap handling ay mas mahalaga kaysa sa reconnect speed. Habang naka-disconnect ang WebSocket, gumalaw ang book. Sa bawat reconnect, mag-re-fetch ng REST snapshot ng bawat subscribed token at i-reconcile: ang anumang open positions na ang book ay gumalaw nang meaningful ay nangangailangan ng state re-check, ang exits ay maaaring kailanganing mag-fire, ang alarms ay maaaring stale. Ang "nakalimutan ko ang 30 segundo ng book updates" case ay ang silent killer ng long-running bots - patuloy silang nag-run sa stale state at naglalagay ng orders sa prices na wala na.

Defensive pattern: mag-snapshot ng bawat subscribed book minsan sa isang minuto anuman ang WebSocket state, at treat ang WS bilang fast-path optimization sa ibabaw ng snapshot poll.

Mga madalas na tanong

Ano ang Polymarket CLOB API endpoint?
Ang base CLOB endpoint ay https://clob.polymarket.com (REST) at wss://ws-subscriptions-clob.polymarket.com/ws/market (WebSocket). Ito ang V2 endpoints na ginagamit ng @polymarket/clob-client-v2 at py-clob-client.
Kailangan ko ba ng API key para basahin ang order book?
Hindi. Ang order book reads (snapshots at WebSocket subscriptions) ay public at hindi nangangailangan ng authentication. Kailangan mo lang ng API key para sa paglalagay/pagkansela ng orders at pagbabasa ng account-specific data (positions, fills).
Gaano kabilis nag-push ang CLOB WebSocket ng price updates?
Kasing-bilis ng pag-match ng orders. Ang aktibong markets ay nakakakita ng updates kada ilang daang milliseconds; ang manipis na markets ay nag-uupdate lamang sa aktwal na orders. Ang parehong depth changes at trade events ay dumadaan sa parehong WS channel - i-parse ang event type para hawakan ang bawat isa nang wasto.
Paano ko mag-compute ng mid-price ng Polymarket order book?
mid = (best_bid + best_ask) / 2 kung pareho ay umiiral; kung hindi, gamitin ang last_trade_price bilang fallback. Mag-ingat sa manipis na books kung saan ang best_bid ay malayo sa ibaba ng best_ask - ang mid ay maaaring walang kahulugan. Palaging isaalang-alang din ang spread bago i-treat ang mid bilang fair price.
Ano ang maker fee sa Polymarket noong 2026?
0% sa karamihan ng categories. Ang makers ay kumikita ng rebates na katumbas ng 20-25% ng taker fees. Ang taker fees ay nag-iiba ayon sa category: 0.75% sports, 1.00% politics, 1.25% economics, 1.80% crypto. Ang rebate-vs-fee asymmetry ay kung bakit ang aktibong bots ay halos palaging nag-quote gamit ang limit orders sa halip na market orders.
Paano ko hawakan ang WebSocket disconnects?
Mag-reconnect na may exponential backoff (1s, 2s, 4s, max 30s), mag-re-subscribe sa parehong markets, at mag-re-fetch ng REST snapshot para punan ang anumang gap. Huwag kailanman magtiwala sa stale order book - kung naka-disconnect ka nang higit sa 5 segundo, humingi ng fresh snapshot bago maglagay ng orders.