Polymarket API গাইড: CLOB, REST ও ট্রেডিং বট (2026)

অধ্যায় 27 এর 33

সংক্ষিপ্ত সংস্করণ

Polymarket তিনটি পাবলিক API উন্মুক্ত করে: CLOB (ট্রেডিং), Gamma (মার্কেট ডিসকভারি), এবং Data (অ্যানালিটিক্স)। অফিসিয়াল Python SDK হলো py-clob-client 0.34.6। অথেনটিকেশন ব্যবহার করে API key + ECDSA signature, যেখানে অর্ডারগুলো সাইন করা হয় একটি Polygon proxy wallet-এর মাধ্যমে EIP-712 দিয়ে। Rate limits আপনাকে প্রতি কী-এ আনুমানিক 60 orders/minute-এ সীমাবদ্ধ রাখে। নতুন ডেভেলপারদের জন্য সবচেয়ে বড় সমস্যা হলো Gamma এবং CLOB-এর মধ্যে condition_id → token_id ম্যাপিং সমস্যা - আগে এটা সমাধান করুন, তারপর বাকি সব সহজ হয়ে যাবে। আনুমানিক $40M/month লিকুইডিটি রিওয়ার্ড এবং বট-ক্যাপচারড স্প্রেড Polymarket-এ আয় করা হয়, প্রায় পুরোটা API ব্যবহারকারীদের মাধ্যমে।

তিনটি পৃথক সার্ভিস: ট্রেডিংয়ের জন্য CLOB (9,000/10s auth), ডিসকভারির জন্য Gamma (4,000/10s public), ঐতিহাসিক অ্যানালিটিক্সের জন্য Data (1,000/10s public)।

পর্ব ১: তিনটি API

Polymarket তিনটি পৃথক সার্ভিসের মধ্যে কাজগুলো পরিষ্কারভাবে ভাগ করে দেয়। প্রতিটি কাজের জন্য সঠিক API ব্যবহার করলে আপনার বট দ্রুত, সহজ, এবং রেট লিমিটের মধ্যে থাকে।

একটি সাধারণ বট লুপে Gamma ব্যবহার করা হয় মার্কেট খুঁজতে, CLOB ব্যবহার করা হয় অর্ডার বুক ফেচ করতে এবং ট্রেড দিতে, আর Data ব্যবহার করা হয় অফলাইনে স্ট্র্যাটেজির পারফরম্যান্স ব্যাক-টেস্ট করতে। Gamma-কে ভাবুন "catalog," CLOB-কে "exchange," আর Data-কে "warehouse."

L1 chainId 137 দিয়ে "ClobAuthDomain" EIP-712 struct সাইন করে credentials ডেরাইভ করে। L2 HMAC-SHA256 প্রতিটি পরবর্তী request-এ POLY_SIGNATURE headers দিয়ে সাইন করে।

পর্ব 2: প্রমাণীকরণ & প্রক্সি ওয়ালেট মডেল

Polymarket আপনার মূল ওয়ালেটের প্রাইভেট কী দিয়ে ট্রেডে সাইন করে না। বরং, এটি একটি Gnosis Safe-স্টাইলের প্রক্সি ওয়ালেট ব্যবহার করে: আপনার মূল ওয়ালেট একটি প্রক্সিকে অনুমোদন করে, আর সেই প্রক্সি Polygon-এ সব ট্রেড এক্সিকিউট করে। আপনার API বট সেই প্রক্সির সাথে যোগাযোগ করে।

আপনার যা লাগবে

• API key - Polymarket Settings → Developer-এ জেনারেট করুন
• Private key - আপনার ট্রেডিং ওয়ালেটের কী (আপনার মূল MetaMask seed phrase নয়)
• Funder address - আপনার প্রক্সি ওয়ালেটের ঠিকানা (Settings → Wallet-এ দেখানো)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, খুচরা ব্যবহারকারীদের জন্য স্ট্যান্ডার্ড)

Magic-link অ্যাকাউন্টের জন্য Signature type 1 (POLY_PROXY), browser-wallet proxy-এর জন্য type 2 (GNOSIS_SAFE), direct key-এর জন্য type 0 (EOA)। type 1 এবং 2-এর জন্য Funder প্রয়োজন।

অংশ 3: py-clob-client ইনস্টল করা

অফিশিয়াল Python SDK-ই শূন্য থেকে প্রথম অর্ডার পর্যন্ত পৌঁছানোর সবচেয়ে দ্রুত উপায়। আমরা 0.34.6 ভার্সনটি ব্যবহার করব, যা এপ্রিল 2026 পর্যন্ত সর্বশেষ।

# প্রথমে একটি virtual environment তৈরি করুন
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# SDK ইনস্টল করুন
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

বেসিক ক্লায়েন্ট কনফিগারেশন

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# একবারের জন্য: API credentials derive করে cache করুন
client.set_api_creds(client.create_or_derive_api_creds())

create_or_derive_api_creds() কলটি আপনার private key দিয়ে একটি message sign করে এবং সেটি API key, secret, এবং passphrase-এর সঙ্গে exchange করে। প্রথম run-এর পর এগুলো আপনার .env-এ cache করে রাখুন, যাতে প্রতিবার startup-এ derive endpoint-এ hit করতে না হয়।

Gamma /markets outcomePrices, clobTokenIds, volume24hr, tags ফেরত দেয়। default bot scanner query হিসেবে tag_slug + order=volume24hr ব্যবহার করুন।

পার্ট 4: Gamma-এর মাধ্যমে মার্কেট আবিষ্কার

ট্রেড করতে পারার আগে, আপনাকে ট্রেড করার মতো মার্কেট খুঁজে নিতে হবে। Gamma এমন JSON ফেরত দেয় যাতে Polymarket UI-তে দেখানো সবকিছু থাকে: প্রশ্ন, আউটকাম, দাম, 24h ভলিউম, মেয়াদ শেষ হওয়া, ট্যাগ এবং ছবি।

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

সহায়ক Gamma query parameters

Gamma conditionId প্রকাশ করে (প্রতি মার্কেটে একটি); CLOB token_id-তে ট্রেড করে (প্রতি আউটকামে একটি)। clobTokenIds হলো JSON-এনকোড করা string array, যা outcomes-এর সঙ্গে index-matched।

পর্ব ৫: condition_id → token_id ম্যাপিং

Polymarket বট ডেভেলপমেন্টে এটি #১ বড় সমস্যা। Gamma একটি condition_id ফেরত দেয় (প্রতি মার্কেটে একটী)। CLOB ট্রেডে ব্যবহৃত হয় token_id (প্রতি outcome-এ একটী)। আপনার সবসময়ই দুটোই দরকার।

# প্রতিটি Gamma market object-এ 'clobTokenIds' থাকে - এটি একটি JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # প্রথম outcome
no_token = token_ids[1] # দ্বিতীয় outcome

# বিকল্প: condition_id ব্যবহার করে সরাসরি CLOB-কে জিজ্ঞাসা করুন
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Outcome ordering gotcha

Gamma-এর outcomes array এবং clobTokenIds array-এর index একে অন্যের সঙ্গে মিলে যায়। সবসময় index 0 কে "Yes" ধরে না নিয়ে outcome label পড়ুন। multi-outcome market-এ (NegRisk, Oscars, নির্বাচন), index 0 হতে পারে "Kamala Harris" বা "Taylor Swift" - order নির্ধারিত, কিন্তু market-specific।

Book bids descending এবং asks ascending হিসেবে ফেরত আসে। market-like FAK পাঠানোর আগে যেকোনো target notional-এর fill price অনুমান করতে level গুলো ধরে এগোন।

অংশ ৬: অর্ডার বুক পড়া

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

অর্ডার বুকগুলো সাজানো অ্যারে হিসেবে ফেরত আসে (bids অবরোহী, asks আরোহী)। প্রতিটি স্তরে price এবং size থাকে। বড় অর্ডারের জন্য স্লিপেজ অনুমান করতে, বুক বরাবর এগিয়ে যান এবং আপনার লক্ষ্যমাত্রা সাইজ পূরণ না হওয়া পর্যন্ত notional জমা করুন।

GTC বুকের ওপর থাকে, GTD timestamp-এ স্বয়ংক্রিয়ভাবে বাতিল হয়, FOK-তে পুরো সাইজ ফিল না হলে বাতিল হয়, FAK যতটা সম্ভব লিমিটে নেয় এবং বাকি অংশ বাতিল করে।

পর্ব 7: অর্ডার প্লেস করা

লিমিট অর্ডার (GTC - ডিফল্ট)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # শেয়ার, ডলার নয়। 0.45 ডলারে 100 শেয়ার = সর্বোচ্চ 45 ডলার খরচ।
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

create_order কলটি আপনার প্রাইভেট কী দিয়ে একটি EIP-712 স্ট্রাকচার্ড মেসেজ সাইন করে। post_order সেটি CLOB-এ সাবমিট করে। আপনি কখনও র- প্রাইভেট কী নেটওয়ার্কের মাধ্যমে পাঠান না - শুধু সাইন করা অর্ডার পাঠান।

অর্ডারের ধরন

ক্যানসেল করা

# Single order
client.cancel(order_id="0xabc...")

# নির্দিষ্ট একটি মার্কেটে সব অর্ডার ক্যানসেল করুন
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: সবকিছু ক্যানসেল করুন
client.cancel_all()

অংশ 8: WebSocket স্ট্রিমিং

প্রতি সেকেন্ডে Gamma পোল করা অপচয়, আর এতে দ্রুতই আপনি rate limit-এ পৌঁছে যাবেন। WebSocket feed সাব-সেকেন্ড লেটেন্সিতে রিয়েল-টাইম অর্ডার বুক (order book) এবং ট্রেড আপডেট স্ট্রিম করে।

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

দুটি feed আছে: /market feedটি (পাবলিক order book + trades) এবং /user feedটি (আপনার নিজের order এবং fill ইভেন্ট, authenticated)। Production bot-গুলো সাধারণত দুটিতেই connect করে, disconnect হলে স্বয়ংক্রিয়ভাবে reconnect করে, এবং বর্তমান book state-এর source of truth হিসেবে WebSocket-কে ধরে।

পর্ব 9: রেট লিমিট ও ব্যাকঅফ

আপনি যখন একটি HTTP 429-এ পৌঁছান, সার্ভার একটি Retry-After header ফেরত দেয়। জিটারসহ exponential backoff বাস্তবায়ন করুন:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Part 10: একটি রেফারেন্স বট আর্কিটেকচার

প্রতি শক্তিশালী Polymarket বটের একই ছয়টি কম্পোনেন্ট থাকে। প্রতিটিকে আলাদা মডিউল হিসেবে তৈরি করুন; সেগুলোকে ঢিলেঢালা ভাবে যুক্ত রাখুন।

Part 11: সাধারণ ব্যর্থতার ধরন

• Stale WebSocket data - প্রতিটি asset-এর শেষ message-এর সময় ট্র্যাক করুন; active market-এ যদি 30s-এর বেশি কোনো update না আসে, তাহলে REST refresh বাধ্যতামূলক করুন।
• Nonce collisions - py-clob-client আপনার জন্য order nonce সামলায়, কিন্তু আপনি যদি নিজে signer বানান, তাহলে প্রতিটি order-এ nonce বাড়ান।
• Insufficient balance - place করার আগে সবসময় USDC balance পরীক্ষা করুন; book-এ আপনার order দেখালেও matching সেটি reject করবে।
• Market paused or resolving - trading-এর আগে market.active && !market.closed পরীক্ষা করুন। রেজল্যুশন (resolution)-এর আশেপাশে Gamma update, CLOB-এর তুলনায় কয়েক সেকেন্ড পিছিয়ে থাকে।
• NegRisk adapter mismatch - multi-outcome market আলাদা NegRisk adapter-এর মাধ্যমে route হয়। SDK এটি সামলায়, কিন্তু আপনার order সঠিক venue-তে গেছে কি না নিশ্চিত করুন।

Part 12: API-এর মাধ্যমে Liquidity পুরস্কার (rewards)

Polymarket সাধারণ liquidity rewards-এ মাসে ~$5M এবং sports-specific rewards-এ মাসে $5M+ চালায় (দেখুন Liquidity Rewards)। এর বিশাল অংশই API-চালিত market মেকার (maker)-দের কাছে যায়, যারা হাজার হাজার market জুড়ে tight দুই-দিকের quote বজায় রাখতে পারে।

reward formula midpoint-এর কাছাকাছি order, size, এবং time-on-book-কে পুরস্কৃত করে। একটি ন্যূনতম market-making loop:

1. target market-এর অর্ডার বুক (order book) পড়ুন
2. একটি fair midpoint হিসাব করুন (যেমন, প্রতিটি পাশে top 3 level-এর VWAP)
3. mid − spread_target/2-এ একটি bid এবং mid + spread_target/2-এ একটি ask দিন
4. প্রতিটি WebSocket update-এ, আপনার quote target থেকে এক tick-এর বেশি সরে গেলে repricing করুন
5. book পাতলা হয়ে গেলে বা news প্রকাশ পেলে cancel করে বেরিয়ে যান

Part 13: Production-এ যাওয়া

• Hosting: ইউরোপ বা US-East-এ $6/month VPS (Hetzner, DigitalOcean) বেশিরভাগ bot-এর জন্য যথেষ্ট। sub-10ms latency দরকার হলে Polygon RPC-এর সাথে co-locate করুন।
• RPC: নির্ভরযোগ্য Polygon RPC-এর জন্য Alchemy, Infura, বা QuickNode ব্যবহার করুন। প্রতি মিনিটে শত শত order না দেওয়া পর্যন্ত free tier যথেষ্ট।
• Monitoring: metrics-এর জন্য Prometheus + Grafana; alert-এর জন্য একটি Telegram bot। আপনি যে প্রতিটি order ID পাঠান এবং যে প্রতিটি fill পান, সব log করুন।
• Backups: প্রতি মিনিটে state সংরক্ষণ করুন। VPS মাঝপথে die করলে, আপনি কয়েক সেকেন্ডে resume করতে চাইবেন, হাতে reconcile করতে নয়।
• Tax: আপনার logger-ই আপনার audit trail - দেখুন Tax Guide।

Part 14 - Polymarket API-এর জন্য যাচাইকৃত Pro Tips

Situation → Action Cheat Sheet

এর পরে কী?

• টুলস & রিসোর্স - API-এর পরিপূরক তৃতীয়-পক্ষের ড্যাশবোর্ড, অ্যানালিটিক্স, এবং ডেটা ফিড
• অ্যাডভান্সড স্ট্র্যাটেজিস - বটের জন্য উপযোগী বহু-লেগ আরবিট্রাজ এবং অপশন-সদৃশ গঠন
• লিকুইডিটি রিওয়ার্ডস - মার্কেট-মেকিং রিবেট উপার্জনের সুনির্দিষ্ট সূত্র
• অর্ডার বুক গাইড - এর বিরুদ্ধে কোড লেখা শুরু করার আগে বইটি পড়ার আরও গভীর অন্তর্দৃষ্টি
• গ্লসারি - এই গাইডের প্রতিটি টার্মের সহজ-ভাষার সংজ্ঞা