Polymarket Bot Tutorial · Sura ya 8 kati ya 32

Polymarket CLOB API kwa bots: REST endpoints kwa order book snapshots, WebSocket subscriptions kwa real-time updates, kuparse bids/asks, kuhesabu mid-price na depth, code samples.

Na Harley Young, mwandishi mkuu wa Polymarkets.co.il. Marekebisho ya mwisho: Mei 2026.

Sura hii inafunika nini

CLOB API ni mahali orders zinasainiwa, kutumwa, kumatchwa, na mahali order book inaishi. Polymarket ina SDK generations mbili - v1 iliyodeprecated na v2 ya sasa. Sura hii inafunika v2 tu; v1 haipaswi kuonekana katika bot yoyote unayoship katika 2026. Tunapitia REST snapshot path, WebSocket update channel, parsing details zinazochanganya builders wapya, na reconnect logic bila ambayo long-running bot inadrift out of sync ndani ya masaa.

  • CLOB v1 vs v2 (tumia v2)
  • Order book REST snapshot
  • WebSocket subscriptions: market na user channels
  • Kuparse bids/asks/depth
  • Kuhesabu mid-price na best-bid/ask
  • Maker fees, taker fees, rebates
  • Code: connect WS na process price-change events
  • Reconnect na gap-handling

CLOB v1 vs v2 (tumia v2)

Polymarket inahifadhi SDK generations mbili. v1 (@polymarket/clob-client kwenye npm, py-clob-client <0.30) imedeprecated na inakosa order types kadhaa zilizoongezwa katika 2024. v2 (@polymarket/clob-client-v2 v1.0.6 katika Node, py-clob-client 0.34.6+ katika Python) ni standard ya sasa.

Tofauti tatu za concrete. v2 inasaidia negRisk flag kwa multi-outcome markets - inahitajika tangu NegRisk exchange ilipolaunch mwishoni mwa 2024. v2 inaship TypeScript types kwa WebSocket message shapes; v1 inarudisha any. v2 inashughulikia August 2025 Gnosis Safe signature flow natively; v1 inahitaji custom signing glue.

Sehemu iliyobaki ya sura hii imeandikwa ikidhania v2 kote. Ikiwa unaona v1 code katika tutorial ya zamani, treat kama broken hadi ithibitishwe vinginevyo - order placement dhidi ya NegRisk markets hasa silently itaroute kwa wrong exchange contract chini ya v1.

Order book REST snapshot

REST snapshot endpoint inarudisha full book kwa token moja kwa wakati.

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

Prices ni strings na decimal places 2-3; sizes ni strings zinazowakilisha share counts (sio dollars). Bids zimesortwa juu-hadi-chini, asks chini-hadi-juu. hash ni deduplication marker - repeated polls za unchanged book zinarudisha hash sawa na bot yako inaweza kuskip processing.

REST snapshot ni call sahihi kwa one-off lookups (price check kwenye entry decision). Kwa continuous monitoring, tumia WebSocket channel hapa chini.

WebSocket subscriptions: market na user channels

WebSocket channels mbili zinajali.

Market channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. Jisajili kwa moja au nyingi tokens; pokea order-book updates zinapotokea.

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

Messages zinafika kwenye kila change. Types zinajumuisha book (full snapshot), price_change (delta), tick_size_change (nadra), na last_trade_price (most recent fill).

User channel: wss://ws-subscriptions-clob.polymarket.com/ws/user. Iliyoauthenticate; pokea order events zako mwenyewe - fills, partial fills, cancellations.

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

User channel ni njia safi zaidi kudetect fill. Polling orders REST endpoint inagharimu zaidi na inaweza kukosa state changes kati ya polls; WebSocket inapush event wakati matcher inaikubali.

Kuparse bids/asks/depth

Order book ni list ya price levels na aggregated size. Parsing conventions mbili za kupata sawa.

Order direction: bids ni buy orders (mtu anataka KUNUNUA kwa price hii). Wakati bot YAKO inauza, unahit bid. Wakati bot yako inanunua, unalift ask. Polymarket UI inaonyesha direction sawa; baadhi ya exchanges nyingine zinainvert.

Sorting: bids zinafika zikiwa sorted descending (best bid kwanza). asks zinafika zikiwa sorted ascending (best ask kwanza). Best bid ni bids[0]; best ask ni asks[0]. Tahadhari: public WebSocket wakati mwingine inatuma partial book updates ambazo si pre-sorted - daima re-sort defensively baada ya merge yoyote.

Depth kwenye level ni dollar value inayoweza kufanyiwa transact: price * size. Top-5-level depth ni liquidity metric ya kawaida: sum(b.price * b.size for b in bids[:5]). Ikiwa top-5 depth iko chini ya $100, book ni illiquid na strategy assumptions nyingi zinavunjika.

Kuhesabu mid-price na best-bid/ask

Derived price points tatu bot yako inahitaji.

  • Best bid / best ask: bids[0].price na asks[0].price. Prices unazoweza kweli kutrade, share moja.
  • Mid-price: (best_bid + best_ask) / 2. Mathematical center ya spread. Inafaa kwa valuation; hutradei kamwe kwenye mid.
  • VWAP price kwa size N: tembea book hadi cumulative size ifikie N, rudisha size-weighted average price. Actual cost ya KUNUNUA N shares sasa hivi, ikihesabu sweep kwenda deeper levels.

Edge case: empty bid au ask side (hakuna anayeuza, au hakuna anayenunua) inamaanisha book ni one-sided. Katika market structure ya Polymarket hii inatokea kwa resolved au near-resolved markets ambapo side moja iko 0.999 na hakuna anayetoa liquidity kwa loser side. Treat best-bid = 0 au best-ask = 1 kama "usitradeji" signals.

Maker fees, taker fees, rebates

Kwa sehemu kubwa ya historia yake, Polymarket haikutoza fee yoyote ya trading. Hili lilibadilika mwaka 2026: fees zilianzishwa mwanzoni mwa mwaka kwenye crypto markets za dakika 15, zikapanuliwa hadi Sports tarehe 30 Machi 2026, na tangu wakati huo zikaenezwa kwenye categories nyingi. Tutorial yoyote inayodai bado kwamba Polymarket haina fee imepitwa na wakati - na yeyote anayepuuza hili katika strategy ya frequency kubwa atalwa kimyakimya. Hivi ndivyo model inavyofanya kazi kweli, kufikia katikati ya 2026.

Kwanza pande mbili za kila trade. maker ni yule anayeweka limit order inayopumzika katika book na kungoja pale; taker ni yule anayetuma order inayoexecute mara moja dhidi ya liquidity iliyopo. makers bado wanalipa fee sifuri na zaidi ya hapo wanapata rebate; ni takers tu wanaolipa fee.

taker fee si asilimia thabiti. Inafuata curve inayotegemea ukubwa wa order na bei pia:

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

Kipengele price × (1 - price) kiko juu zaidi kwa bei ya 0.50 (market halisi ya "kurusha sarafu") na hupungua kuelekea 0 au 1. Kwa maneno mengine, kwenye markets zisizo na uhakika zaidi unalipa fee kubwa zaidi, na kwenye zile zilizokaribia kuamuliwa karibu hakuna. feeRate imewekwa per category:

  • Crypto: feeRate 0.07 (kubwa zaidi, peak halisi karibu 1.8%), maker rebate 20%.
  • Sports: feeRate 0.03 (peak karibu 0.75%), maker rebate 25%.
  • Finance, Politics, Tech, Mentions: feeRate 0.04, maker rebate 25%.
  • Economics, Culture, Weather, jumla: feeRate 0.05, maker rebate 25%.
  • Geopolitics na matukio makubwa ya dunia: 0, bado bila fee.

Mfano wa hesabu. Tuseme bot yako inachukua shares 100 za crypto market kwa bei ya 0.50. fee ni 100 × 0.07 × 0.50 × (1 - 0.50) = 100 × 0.07 × 0.25 = $1.75. Ukichukua shares 100 zilezile kwa 0.90, fee inashuka hadi 100 × 0.07 × 0.90 × 0.10 = $0.63, kwa sababu bei iko mbali na katikati isiyo na uhakika. Kwa bot, somo liko wazi: kuchukua liquidity kwenye crypto na sports markets zinazobadilikabadilika na karibu sawa kunagharimu fee kubwa zaidi - kwa hiyo hapo ndipo inafaa zaidi kuquote kama maker na kuchukua rebate badala ya kulipa fee.

Zaidi ya fee ya wazi, kila unapocross bid-ask spread unailipa spread hiyo. spread ni pengo kati ya bei bora ya kununua na bei bora ya kuuza, na kwa strategy inayoingia na kutoka kama taker pengo hilo ni cost halisi juu ya fee. Assume cents 1-3 round-trip kwa typical books, zaidi kwa illiquid. NegRisk markets (multi-outcome exchange) zinatumia model sawa ya fee lakini zinasettle kwenye contract tofauti, kwa hiyo rewards zao zinaaccrue tofauti. Sura ya 19 inafunika liquidity-rewards farming, ambapo kuchukua maker rebates ndiyo strategy yenyewe, si tu side-effect.

Code: connect WS na process price-change events

Minimal Node example: connect, subscribe, log kila price-change event kwa token moja.

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));

Jisajili hadi tokens ~30 kwa WebSocket connection comfortably. Zaidi ya hapo, gawanya katika connections nyingi - server mara kwa mara inadrop large subscriptions sakafuni bila erroring, ambayo inazalisha silent stale book reads.

Reconnect na gap-handling

Long-running WebSocket connection itadrop. Cloudflare inacycle connections kila masaa machache; networks zinablink; Polymarket wakati mwingine inadeploy. Panga kwa hilo.

Reconnect strategy: kwenye close au error, subiri min(2^attempt, 30) sekunde na jitter, kisha re-subscribe. Reset attempt counter kwenye first successful message baada ya reconnect.

Gap handling inajali zaidi kuliko reconnect speed. Wakati WebSocket ilikuwa disconnected, book ilihama. Kwenye kila reconnect, re-fetch REST snapshot ya kila subscribed token na reconcile: open positions yoyote ambazo book yake imehama meaningfully zinahitaji state re-check, exits zinaweza kuhitaji kufire, alarms zinaweza kuwa stale. "Nilikosa sekunde 30 za book updates" case ni silent killer ya long-running bots - wanaendelea kufanya kazi kwenye stale state na kuweka orders kwa prices ambazo hazipo tena.

Defensive pattern: snapshot kila subscribed book mara moja kwa dakika bila kujali WebSocket state, na treat WS kama fast-path optimization juu ya snapshot poll.

Maswali yanayoulizwa mara kwa mara

Ni nini Polymarket CLOB API endpoint?
Base CLOB endpoint ni https://clob.polymarket.com (REST) na wss://ws-subscriptions-clob.polymarket.com/ws/market (WebSocket). Hizi ni V2 endpoints zinazotumiwa na @polymarket/clob-client-v2 na py-clob-client.
Je, ninahitaji API key kusoma order book?
Hapana. Order book reads (snapshots na WebSocket subscriptions) ni public na hazihitaji authentication. Unahitaji API key tu kwa kuweka/kucancel orders na kusoma account-specific data (positions, fills).
Ni haraka gani CLOB WebSocket inapush price updates?
Haraka kama orders zinamatch. Active markets zinaona updates kila milliseconds chache mia; thin markets zinaupdate tu kwenye actual orders. Depth changes na trade events zote zinapita kupitia WS channel sawa - parse event type ku-handle kila moja kwa usahihi.
Je, ninawezaje kuhesabu mid-price ya Polymarket order book?
mid = (best_bid + best_ask) / 2 ikiwa zote zipo; vinginevyo tumia last_trade_price kama fallback. Kuwa makini na thin books ambapo best_bid iko mbali sana chini ya best_ask - mid inaweza kuwa meaningless. Daima pia fikiri spread kabla ya kutreat mid kama fair price.
Ni nini maker fee kwenye Polymarket katika 2026?
makers wanalipa 0% na wanapata rebate (20% kwenye crypto, 25% kwenye categories nyingine nyingi). Ni takers tu wanaolipa fee, nayo si thabiti: inafuata fee = shares × feeRate × price × (1 - price), kwa hiyo iko juu zaidi kwenye markets za "kurusha sarafu" karibu na 0.50 na hupungua kuelekea pembeni. feeRates per category zinatoka 0.03 (Sports, peak halisi karibu 0.75%) hadi 0.07 (Crypto, peak halisi karibu 1.8%), huku Geopolitics ikiwa bado bila fee. Asymmetry hii ya maker-taker ndiyo sababu active bots karibu daima zinaquote na limit orders zinazopumzika badala ya kucross spread na market orders.
Je, ninawezaje kushughulikia WebSocket disconnects?
Reconnect na exponential backoff (1s, 2s, 4s, max 30s), re-subscribe kwa markets sawa, na re-fetch REST snapshot kujaza gap yoyote. Usitrust stale order book - ikiwa umekuwa disconnected kwa zaidi ya sekunde 5, omba fresh snapshot kabla ya kuweka orders.