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.

  • 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.6 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

Sa halos buong kasaysayan nito, walang sinisingil ang Polymarket na anumang trading fee. Nagbago ito noong 2026: ipinakilala ang fees sa simula ng taon sa 15-minutong crypto markets, pinalawak sa Sports noong Marso 30, 2026, at mula noon ay inilabas sa karamihan ng categories. Anumang tutorial na nagsasabi pa ring fee-free ang Polymarket ay luma na - at ang sinumang makaligtaan ito sa isang high-frequency strategy ay tahimik na uubusin. Ganito talaga gumagana ang model, sa kalagitnaan ng 2026.

Una, ang dalawang panig ng bawat trade. Ang maker ay ang naglalagay ng nakapahingang limit order sa book na naghihintay doon; ang taker ay ang nagpapadala ng order na agad na-execute laban sa umiiral na liquidity. Patuloy na nagbabayad ang makers ng zero fee at bukod pa rito ay tumatanggap ng rebate; ang takers lang ang nagbabayad ng fee.

Ang taker fee ay hindi pirmihang porsiyento. Sinusunod nito ang isang curve na nakadepende sa laki ng order at sa presyo:

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

Ang terminong price × (1 - price) ay pinakamataas sa presyong 0.50 (isang tunay na "coin-flip" market) at lumiliit papunta sa 0 o 1. Sa madaling salita, sa pinaka-hindi tiyak na markets ay pinakamataas ang fee na binabayaran mo, at sa halos napagdesisyunan na ay halos wala. Ang feeRate ay itinakda kada category:

  • Crypto: feeRate 0.07 (pinakamataas, effective peak na mga 1.8%), maker rebate 20%.
  • Sports: feeRate 0.03 (peak na mga 0.75%), maker rebate 25%.
  • Finance, Politics, Tech, Mentions: feeRate 0.04, maker rebate 25%.
  • Economics, Culture, Weather, pangkalahatan: feeRate 0.05, maker rebate 25%.
  • Geopolitics at malalaking pandaigdigang pangyayari: 0, fee-free pa rin.

Isang halimbawa ng pagkalkula. Sabihin nating kukuha ang bot mo ng 100 shares ng isang crypto market sa presyong 0.50. Ang fee ay 100 × 0.07 × 0.50 × (1 - 0.50) = 100 × 0.07 × 0.25 = $1.75. Kung kukunin mo ang parehong 100 shares sa 0.90, bababa ang fee sa 100 × 0.07 × 0.90 × 0.10 = $0.63, dahil malayo ang presyo sa hindi tiyak na gitna. Para sa bot, malinaw ang aral: ang pagkuha ng liquidity sa pabagu-bago at halos balanseng crypto at sports markets ang pinakamahal sa fee - kaya doon mismo pinakasulit na mag-quote bilang maker at kunin ang rebate sa halip na magbayad ng fee.

Bukod sa explicit fee, sa bawat pagtawid mo sa bid-ask spread ay binabayaran mo ang spread na iyon. Ang spread ay ang puwang sa pagitan ng pinakamagandang presyo ng bilihin at pinakamagandang presyo ng benta, at para sa strategy na pumapasok at lumalabas bilang taker, ang puwang na iyon ay tunay na gastos bukod sa fee. Mag-assume ng 1-3 cents round-trip sa typical books, mas higit pa sa illiquid. Ang NegRisk markets (ang multi-outcome exchange) ay gumagamit ng parehong fee model pero nag-se-settle sa hiwalay na contract, kaya hiwalay na nag-a-accrue ang rewards nila. Sinasaklaw ng kabanata 19 ang liquidity-rewards farming, kung saan ang pagkuha ng maker rebates mismo ang strategy, hindi lang basta side-effect.

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?
Ang makers ay nagbabayad ng 0% at tumatanggap ng rebate (20% sa crypto, 25% sa karamihan ng ibang categories). Ang takers lang ang nagbabayad ng fee, at hindi ito pirmihan: sinusunod nito ang fee = shares × feeRate × price × (1 - price), kaya pinakamataas sa "coin-flip" markets malapit sa 0.50 at lumiliit papunta sa mga gilid. Ang feeRates kada category ay mula 0.03 (Sports, effective peak na mga 0.75%) hanggang 0.07 (Crypto, effective peak na mga 1.8%), habang fee-free pa rin ang Geopolitics. Ang maker-taker asymmetry na ito ang dahilan kung bakit ang aktibong bots ay halos palaging nag-quote gamit ang nakapahingang limit orders sa halip na tumawid sa spread gamit ang 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.