Polymarket Bot Tutorial · Chapter 8 of 32

Bots के लिए Polymarket CLOB API: order book snapshots के लिए REST endpoints, real-time updates के लिए WebSocket subscriptions, bids/asks parsing, mid-price और depth की computation, code samples.

Harley Young द्वारा, Polymarkets.co.il में मुख्य लेखिका। अंतिम समीक्षा: मई 2026।

इस chapter में क्या कवर किया गया है

CLOB API वह जगह है जहाँ orders sign होते हैं, भेजे जाते हैं, match होते हैं, और जहाँ order book रहता है। Polymarket की दो SDK generations हैं - deprecated v1 और current v2। यह chapter केवल v2 को कवर करता है; 2026 में आप जो भी bot ship करें उसमें v1 नहीं होना चाहिए। हम REST snapshot path, WebSocket update channel, parsing details जो नए builders को फँसा देते हैं, और reconnect logic को कवर करते हैं - जिसके बिना एक long-running bot कुछ घंटों में sync से बाहर हो जाता है।

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

CLOB v1 vs v2 (use v2)

Polymarket दो SDK generations maintain करता है। v1 (@polymarket/clob-client on npm, py-clob-client <0.30) deprecated है और 2024 में जोड़े गए कई order types missing हैं। v2 (@polymarket/clob-client-v2 Node में v1.0.6, Python में py-clob-client 0.34.6+) current standard है।

तीन concrete differences। v2 multi-outcome markets के लिए negRisk flag support करता है - NegRisk exchange के late 2024 में launch होने के बाद से यह required है। v2 WebSocket message shapes के लिए TypeScript types ship करता है; v1 any return करता है। v2 अगस्त 2025 के Gnosis Safe signature flow को natively handle करता है; v1 को custom signing glue की ज़रूरत होती है।

इस chapter का बाकी हिस्सा पूरे time v2 मानकर लिखा गया है। अगर आपको किसी पुराने tutorial में v1 code दिखे, तो जब तक साबित न हो कि वह सही है, उसे broken मानें - खासकर NegRisk markets के against order placement v1 में silently wrong exchange contract पर route हो सकता है।

Order book REST snapshot

REST snapshot endpoint किसी एक token के लिए एक point in time पर पूरा book return करता है।

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 strings के रूप में 2-3 decimal places के साथ होते हैं; sizes strings होते हैं जो share counts represent करते हैं (dollars नहीं)। Bids high-to-low sorted होते हैं, asks low-to-high। hash एक deduplication marker है - unchanged book के repeated polls same hash return करते हैं और आपका bot processing skip कर सकता है।

REST snapshot one-off lookups के लिए सही choice है (entry decision पर price check)। Continuous monitoring के लिए नीचे दिया गया WebSocket channel use करें।

WebSocket subscriptions: market and user channels

दो WebSocket channels महत्वपूर्ण हैं।

Market channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. एक या कई tokens subscribe करें; जैसे ही updates आते हैं, order-book updates receive करें।

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

Messages हर change पर आते हैं। Types में book (full snapshot), price_change (delta), tick_size_change (rare), और last_trade_price (most recent fill) शामिल हैं।

User channel: wss://ws-subscriptions-clob.polymarket.com/ws/user. Authenticated; अपने order events receive करें - fills, partial fills, cancellations।

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

Fill detect करने का सबसे साफ़ तरीका user channel है। Orders REST endpoint poll करना ज़्यादा costly है और polls के बीच state changes miss कर सकता है; WebSocket event उसी moment push करता है जब matcher उसे acknowledge करता है।

Parsing bids/asks/depth

Order book aggregated size के साथ price levels की list होता है। सही करने के लिए दो parsing conventions हैं।

Order direction: bids buy orders होते हैं (कोई इस price पर BUY करना चाहता है)। जब आपका bot SELL करता है, तो आप bid hit करते हैं। जब आपका bot BUY करता है, तो आप ask lift करते हैं। Polymarket UI वही direction दिखाता है; कुछ दूसरे exchanges इसे उल्टा करते हैं।

Sorting: bids descending order में आते हैं (best bid first)। asks ascending order में आते हैं (best ask first)। Best bid bids[0] है; best ask asks[0] है। ध्यान रहे: public WebSocket कभी-कभी partial book updates भेजता है जो पहले से pre-sorted नहीं होते - किसी भी merge के बाद हमेशा defensively re-sort करें।

किसी level पर depth का मतलब transactable dollar value है: price * size. Top-5-level depth एक common liquidity metric है: sum(b.price * b.size for b in bids[:5]). अगर top-5 depth $100 से कम है, तो book illiquid है और ज़्यादातर strategy assumptions टूट जाती हैं।

Computing mid-price and best-bid/ask

तीन derived price points जिनकी आपके bot को ज़रूरत होती है।

  • Best bid / best ask: bids[0].price और asks[0].price. वे prices जिन पर आप सचमुच trade कर सकते हैं, एक share के लिए।
  • Mid-price: (best_bid + best_ask) / 2. spread का mathematical center। valuation के लिए उपयोगी; आप mid पर trade नहीं करते।
  • VWAP price for size N: book को तब तक walk करें जब तक cumulative size N तक न पहुँच जाए, फिर size-weighted average price return करें। अभी N shares खरीदने की actual cost, deeper levels में sweep को account करते हुए।

Edge case: bid या ask side का खाली होना (कोई बेच नहीं रहा, या कोई खरीद नहीं रहा) मतलब book one-sided है। Polymarket की market structure में यह resolved या near-resolved markets में होता है जहाँ एक side 0.999 पर होती है और loser side पर कोई liquidity offer नहीं करता। best-bid = 0 या best-ask = 1 को "do not trade" signals की तरह treat करें।

Maker fees, taker fees, rebates

अपने ज़्यादातर इतिहास में Polymarket ने कोई trading fee ली ही नहीं। यह 2026 में बदला: fees साल की शुरुआत में 15-मिनट वाले crypto markets पर शुरू हुईं, 30 मार्च 2026 को Sports तक बढ़ाई गईं, और तब से ज़्यादातर categories पर लागू हो गईं। कोई भी tutorial जो अब भी कहता है कि Polymarket fee-मुक्त है, पुराना है - और जो कोई high-frequency strategy में इसे नज़रअंदाज़ करेगा, चुपचाप खा लिया जाएगा। 2026 के मध्य तक model असल में ऐसे काम करता है।

पहले हर trade के दो पक्ष। maker वह है जो book में एक प्रतीक्षारत limit order रखता है जो वहीं इंतज़ार करता है; taker वह है जो ऐसा order भेजता है जो मौजूद liquidity के विरुद्ध तुरंत execute हो जाता है। makers अब भी शून्य fee देते हैं और ऊपर से एक rebate भी पाते हैं; fee सिर्फ़ takers देते हैं।

taker fee कोई स्थिर प्रतिशत नहीं है। यह एक वक्र का अनुसरण करती है जो order के आकार और price दोनों पर निर्भर करता है:

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

पद price × (1 - price) price 0.50 (एक सच्चा "सिक्का उछाल" market) पर अधिकतम होता है और 0 या 1 की ओर सिकुड़ता है। दूसरे शब्दों में, सबसे अनिश्चित markets में आप सबसे ऊँची fee देते हैं और लगभग तय हो चुके markets में लगभग कुछ नहीं। feeRate हर category के लिए तय है:

  • Crypto: feeRate 0.07 (सबसे ऊँची, effective peak लगभग 1.8%), maker rebate 20%।
  • Sports: feeRate 0.03 (peak लगभग 0.75%), maker rebate 25%।
  • Finance, Politics, Tech, Mentions: feeRate 0.04, maker rebate 25%।
  • Economics, Culture, Weather, सामान्य: feeRate 0.05, maker rebate 25%।
  • Geopolitics और बड़ी वैश्विक घटनाएँ: 0, अब भी fee-मुक्त।

एक हिसाब का उदाहरण। मान लें आपका bot किसी crypto market के 100 shares 0.50 price पर लेता है। fee होगी 100 × 0.07 × 0.50 × (1 - 0.50) = 100 × 0.07 × 0.25 = $1.75। अगर आप वही 100 shares 0.90 पर लें तो fee घटकर 100 × 0.07 × 0.90 × 0.10 = $0.63 रह जाती है, क्योंकि price अनिश्चित मध्य से दूर है। bot के लिए सबक़ साफ़ है: अस्थिर और लगभग संतुलित crypto और sports markets में liquidity लेना सबसे ज़्यादा fee लेता है - इसलिए ठीक वहीं सबसे फ़ायदेमंद है कि maker के रूप में quote करें और fee देने के बजाय rebate समेटें।

explicit fee के अलावा, हर बार जब आप bid-ask spread cross करते हैं तो वह spread भी देते हैं। spread सबसे अच्छे buy price और सबसे अच्छे sell price के बीच का अंतर है, और taker के रूप में अंदर-बाहर होने वाली strategy के लिए वह अंतर fee के ऊपर एक असली cost है। typical books पर round-trip 1-3 cents और illiquid पर इससे ज़्यादा मानें। NegRisk markets (multi-outcome exchange) वही fee model इस्तेमाल करती हैं पर एक अलग contract पर settle होती हैं, इसलिए उनके rewards अलग से accrue होते हैं। Chapter 19 liquidity-rewards farming को कवर करता है, जहाँ maker rebates समेटना ख़ुद strategy है, महज़ कोई side-effect नहीं।

Code: connect WS and process price-change events

Minimal Node example: connect करें, subscribe करें, एक token के लिए हर price-change event log करें।

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

एक WebSocket connection पर लगभग 30 tokens तक subscribe करना आराम से संभव है। इससे आगे जाएँ तो multiple connections में split करें - server कभी-कभी बड़ी subscriptions को बिना error दिए drop कर देता है, जिससे silent stale book reads होते हैं।

Reconnect and gap-handling

Long-running WebSocket connection drop होगा। Cloudflare कुछ घंटों में connections cycle करता है; networks blink करते हैं; Polymarket कभी-कभी deploy करता है। इसके लिए plan करें।

Reconnect strategy: close या error पर jitter के साथ min(2^attempt, 30) seconds wait करें, फिर re-subscribe करें। Reconnect के बाद पहला successful message आते ही attempt counter reset कर दें।

Gap handling, reconnect speed से ज़्यादा महत्वपूर्ण है। जब WebSocket disconnected था, book move हो चुका था। हर reconnect पर, अपने हर subscribed token का REST snapshot दोबारा fetch करें और reconcile करें: जिन open positions का book meaningful रूप से बदल चुका है, उनकी state re-check की ज़रूरत होती है, exits fire करने पड़ सकते हैं, alarms stale हो सकते हैं। "मैंने 30 seconds के book updates miss कर दिए" वाला case लंबे समय तक चलने वाले bots का silent killer है - वे stale state पर चलते रहते हैं और ऐसे prices पर orders place करते हैं जो अब मौजूद ही नहीं हैं।

Defensive pattern: WebSocket state से independent होकर हर minute हर subscribed book का snapshot लें, और WS को snapshot poll के ऊपर fast-path optimization की तरह treat करें।

अक्सर पूछे जाने वाले प्रश्न

Polymarket CLOB API endpoint क्या है?
Base CLOB endpoint https://clob.polymarket.com (REST) और wss://ws-subscriptions-clob.polymarket.com/ws/market (WebSocket) है। ये V2 endpoints हैं जिनका उपयोग @polymarket/clob-client-v2 और py-clob-client करते हैं।
Order book पढ़ने के लिए क्या मुझे API key चाहिए?
नहीं। Order book reads (snapshots और WebSocket subscriptions) public हैं और authentication की ज़रूरत नहीं होती। API key केवल orders place/cancel करने और account-specific data (positions, fills) पढ़ने के लिए चाहिए।
CLOB WebSocket price updates कितनी तेज़ी से push करता है?
जितनी तेज़ी से orders match होते हैं। Active markets में updates हर कुछ सौ milliseconds में आते हैं; thin markets केवल actual orders पर update होते हैं। Depth changes और trade events दोनों same WS channel से flow होते हैं - हर event type को सही तरह handle करने के लिए उसे parse करें।
Polymarket order book का mid-price कैसे compute करूँ?
mid = (best_bid + best_ask) / 2 अगर दोनों मौजूद हों; वरना fallback के रूप में last_trade_price का use करें। Thin books में सावधान रहें जहाँ best_bid, best_ask से बहुत नीचे हो - mid meaningless हो सकता है। Mid को fair price मानने से पहले हमेशा spread भी consider करें।
2026 में Polymarket पर maker fee क्या है?
makers 0% देते हैं और एक rebate पाते हैं (crypto पर 20%, ज़्यादातर अन्य categories पर 25%)। fee सिर्फ़ takers देते हैं, और यह स्थिर नहीं: यह fee = shares × feeRate × price × (1 - price) का अनुसरण करती है, इसलिए 0.50 के पास "सिक्का उछाल" markets में चरम पर होती है और किनारों की ओर सिकुड़ती है। category के हिसाब से feeRates 0.03 (Sports, effective peak लगभग 0.75%) से 0.07 (Crypto, effective peak लगभग 1.8%) तक जाती हैं, जबकि Geopolitics अब भी fee-मुक्त है। यही maker-taker asymmetry वजह है कि active bots लगभग हमेशा market orders से spread cross करने के बजाय प्रतीक्षारत limit orders के साथ quote करते हैं।
WebSocket disconnects को कैसे handle करूँ?
Exponential backoff (1s, 2s, 4s, max 30s) के साथ reconnect करें, same markets पर re-subscribe करें, और gap भरने के लिए REST snapshot दोबारा fetch करें। कभी भी stale order book पर भरोसा न करें - अगर आप 5 seconds से ज़्यादा disconnected रहे हैं, तो orders place करने से पहले fresh snapshot मांगें।