پولی مارکیٹ CLOB Orderbook API: REST + WebSocket

پولی مارکیٹ بوٹ ٹیوٹوریل · 32 میں سے باب 8

Bots کے لیے پولی مارکیٹ CLOB API: order book snapshots کے لیے REST endpoints، real-time updates کے لیے WebSocket subscriptions، bids/asks parsing، mid-price اور depth کا حساب، code samples۔

تحریر: ہارلی ینگ، Polymarkets.co.il کی مرکزی مصنفہ۔ آخری جائزہ: مئی 2026۔

یہ chapter کیا cover کرتا ہے

CLOB API وہ جگہ ہے جہاں orders sign ہوتے ہیں، send ہوتے ہیں، match ہوتے ہیں، اور جہاں order book رہتا ہے۔ پولی مارکیٹ کے دو SDK generations ہیں - deprecated v1 اور current v2۔ یہ chapter صرف v2 cover کرتا ہے؛ 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]

پولی مارکیٹ دو SDK generations maintain کرتا ہے۔ v1 (@polymarket/clob-client on npm, py-clob-client <0.30) deprecated ہے اور 2024 میں add ہونے والی کئی order types missing ہیں۔ v2 (@polymarket/clob-client-v2 v1.0.2 in Node, py-clob-client 0.34.6+ in Python) current standard ہے۔

تین concrete differences۔ v2 multi-outcome markets کے لیے negRisk flag support کرتا ہے - جو late 2024 میں NegRisk exchange launch ہونے کے بعد ضروری ہے۔ v2 WebSocket message shapes کے لیے TypeScript types ship کرتا ہے؛ v1 any return کرتا ہے۔ v2 August 2025 کے Gnosis Safe signature flow کو native طور پر handle کرتا ہے؛ v1 کو custom signing glue چاہیے۔

اس chapter کا باقی حصہ ہر جگہ v2 فرض کر کے لکھا گیا ہے۔ اگر آپ کو کسی older tutorial میں v1 code نظر آئے، تو اسے تب تک broken سمجھیں جب تک اس کے درست ہونے کا ثبوت نہ مل جائے - خاص طور پر NegRisk markets کے خلاف order placement v1 میں silently غلط exchange contract پر route ہو سکتی ہے۔

Order book REST snapshot

REST snapshot endpoint ایک وقت میں single token کے لیے full 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 ایک-off lookups کے لیے درست انتخاب ہے (entry decision پر price check)۔ Continuous monitoring کے لیے نیچے والا WebSocket channel استعمال کریں۔

WebSocket subscriptions: market and user channels

دو WebSocket channels اہم ہیں۔

Market channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. ایک یا کئی tokens subscribe کریں؛ 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 کرنا زیادہ cost کرتا ہے اور polls کے درمیان state changes miss ہو سکتی ہیں؛ WebSocket matcher کے acknowledge کرتے ہی event push کر دیتا ہے۔

Parsing bids/asks/depth

Order book price levels کی ایک list ہے جس میں aggregated size ہوتی ہے۔ دو parsing conventions درست کرنا ضروری ہے۔

Order direction: bids buy orders ہیں (کوئی اس price پر BUY کرنا چاہتا ہے)۔ جب آپ کا bot sell کرتا ہے، وہ bid hit کرتا ہے۔ جب آپ کا bot buy کرتا ہے، وہ ask lift کرتا ہے۔ پولی مارکیٹ UI یہی direction دکھاتا ہے؛ بعض دوسری exchanges الٹا کرتی ہیں۔

Sorting: bids descending order میں آتی ہیں (best bid پہلے)۔ asks ascending order میں آتی ہیں (best ask پہلے)۔ Best bid bids[0] ہے؛ best ask asks[0] ہے۔ احتیاط: public WebSocket کبھی کبھی partial book updates بھیجتا ہے جو پہلے سے sorted نہیں ہوتیں - کسی بھی merge کے بعد ہمیشہ defensively re-sort کریں۔

Kisi level پر depth وہ dollar value ہے جو transact ہو سکتی ہے: 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 BUY کرنے کی actual cost، deeper levels میں sweep کو حساب میں لاتے ہوئے۔

Edge case: bid یا ask side کا empty ہونا (کوئی selling نہیں کر رہا، یا کوئی buying نہیں کر رہا) اس بات کی علامت ہے کہ book one-sided ہے۔ پولی مارکیٹ کی market structure میں یہ resolved یا near-resolved markets میں ہوتا ہے جہاں ایک side 0.999 پر ہوتی ہے اور کوئی loser side پر liquidity offer نہیں کرتا۔ best-bid = 0 یا best-ask = 1 کو "do not trade" signals سمجھیں۔

Maker fees, taker fees, rebates

پولی مارکیٹ maker-taker fee model چلاتا ہے۔ مئی 2026 کے مطابق numbers:

• Taker fee: 0 (zero) - وہ orders جو existing book liquidity lift کرتی ہیں کوئی fee pay نہیں کرتیں۔ نوٹ کریں کہ proxy operations پر gas / network costs apply ہوتے ہیں۔
• Maker rebate: small positive، programmatic، eligible reward-program markets میں ہر filled rested order پر paid out ہوتی ہے۔ ہر market میں rewards نہیں ہوتیں۔
• NegRisk markets: fee structure وہی ہے لیکن separate exchange contract پر؛ rewards الگ accrue ہوتی ہیں۔

Zero taker fee پولی مارکیٹ کو traditional CFD venues سے meaningful طور پر مختلف بناتی ہے - trading "cost" کا بڑا حصہ bid-ask spread خود ہے، نہ کہ کوئی explicit fee۔ اگر کوئی strategy ہر trade پر spread cross کرتی ہے، تو spread tax اصل cost ہے؛ typical books پر round-trip کے لیے 1-3 cents assume کریں، اور illiquid books پر اس سے زیادہ۔

Maker rebates صرف تب chase کرنے کے قابل ہوتی ہیں جب liquidity-rewards-eligible markets strategy ideas کے ساتھ align کریں۔ Chapter 19 liquidity-rewards farming کو ایک dedicated approach کے طور پر cover کرتا ہے۔

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 تک comfortably 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 کرتے ہیں؛ پولی مارکیٹ کبھی کبھی deploy کرتا ہے۔ اس کے لیے plan کریں۔

Reconnect strategy: close یا error پر min(2^attempt, 30) seconds jitter کے ساتھ 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 معنی خیز طور پر move ہوا ہے ان کی state re-check کی ضرورت ہے، exits fire کرنے کی ضرورت ہو سکتی ہے، alarms stale ہو سکتی ہیں۔ "میں نے 30 seconds book updates miss کر دیں" والا case long-running bots کا silent killer ہے - وہ stale state پر چلتے رہتے ہیں اور ایسے prices پر orders place کرتے ہیں جو اب موجود ہی نہیں ہوتے۔

Defensive pattern: WebSocket state سے قطع نظر ہر منٹ میں ہر subscribed book snapshot کریں، اور WS کو snapshot poll کے اوپر fast-path optimization سمجھیں۔

اکثر پوچھے جانے والے سوالات