Polymarket CLOB Orderbook API: REST + WebSocket

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 کا حساب، code samples۔

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

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

CLOB API وہ جگہ ہے جہاں orders sign ہوتے ہیں، send ہوتے ہیں، match ہوتے ہیں، اور جہاں order book رہتا ہے۔ Polymarket کے دو 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)

Polymarket دو 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.6 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 کرتا ہے۔ Polymarket 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 ہے۔ Polymarket کی 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

اپنی زیادہ تر تاریخ میں Polymarket نے کوئی trading fee بالکل نہیں لی۔ یہ 2026 میں بدل گیا: fees سال کے آغاز میں 15 منٹ والی crypto markets پر متعارف ہوئیں، 30 مارچ 2026 کو Sports تک بڑھائی گئیں، اور تب سے زیادہ تر categories پر roll out ہو گئیں۔ کوئی بھی tutorial جو اب بھی کہے کہ Polymarket fee سے پاک ہے، پرانا ہے - اور جو کوئی high-frequency strategy میں اسے نظرانداز کرے گا، خاموشی سے کھا لیا جائے گا۔ 2026 کے وسط کے مطابق model اصل میں یوں کام کرتا ہے۔

پہلے ہر trade کے دو رخ۔ maker وہ ہے جو book میں ایک resting limit order رکھتا ہے جو وہیں انتظار کرتا ہے؛ taker وہ ہے جو ایسا order بھیجتا ہے جو موجودہ liquidity کے خلاف فوراً execute ہو جاتا ہے۔ makers اب بھی صفر fee دیتے ہیں اور اوپر سے ایک rebate بھی پاتے ہیں؛ fee صرف takers دیتے ہیں۔

taker fee کوئی fixed percentage نہیں ہے۔ یہ ایک curve کی پیروی کرتی ہے جو order کے size اور price دونوں پر منحصر ہے:

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

جزو price × (1 - price) price 0.50 (ایک حقیقی "سکّہ اچھالنے" والی market) پر maximum ہوتا ہے اور 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 0.50 price پر کسی crypto market کے 100 shares لیتا ہے۔ 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 پر اس سے زیادہ assume کریں۔ NegRisk markets (multi-outcome exchange) وہی fee model استعمال کرتی ہیں مگر ایک الگ contract پر settle ہوتی ہیں، اس لیے ان کے rewards الگ accrue ہوتے ہیں۔ Chapter 19 liquidity-rewards farming کو cover کرتا ہے، جہاں 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 تک 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 کرتے ہیں؛ Polymarket کبھی کبھی 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 سمجھیں۔

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