API CLOB پلی‌مارکت: دفتر سفارشات، قیمت و سفارش‌ها (V2، ۲۰۲۶)

API · مرجع

CLOB (دفتر سفارشات با محدودیت مرکزی) در clob.polymarket.com جایی است که سفارش‌ها قرار می‌گیرند و با هم مچ می‌شوند. شما بدون احراز هویت دفتر سفارشات، قیمت‌ها و اندازه تیک را می‌خوانید و با اعتبارنامه‌های API و امضا معامله می‌کنید (ثبت / لغو سفارش، خواندن موجودی). این مرجع CLOB V2 است — وثیقه pUSD است، کارمزدها روی زنجیره‌اند و سازندگان (maker) صفر می‌پردازند.

خواندن دفتر سفارشات (بدون احراز هویت)

from py_clob_client_v2 import ClobClient   # pip install py-clob-client-v2
client = ClobClient(host="https://clob.polymarket.com", chain_id=137)   # read-only: no key
book = client.get_order_book(token_id)
mid  = client.get_midpoint(token_id)
print(book.bids[0].price, book.asks[0].price, mid)

// polymarket_client_sdk_v2 (official, repo rs-clob-client-v2)
use polymarket_client_sdk_v2::clob::{Client, Config};
use polymarket_client_sdk_v2::clob::types::request::OrderBookSummaryRequest;
let client = Client::new("https://clob.polymarket.com", Config::default())?;
let book = client.order_book(&OrderBookSummaryRequest::builder().token_id(token_id).build()).await?;

curl -s "https://clob.polymarket.com/book?token_id=$TOKEN_ID"

نمونه پاسخ

{
  "market": "0x...",
  "bids": [ { "price": "0.62", "size": "1400" }, { "price": "0.61", "size": "900" } ],
  "asks": [ { "price": "0.64", "size": "1100" }, { "price": "0.65", "size": "2000" } ]
}

اندپوینت‌های خواندن

محدودیت‌ها بالا هستند: CLOB حدود ۹٬۰۰۰ درخواست / ۱۰ ثانیه، /book و /price ۱٬۵۰۰ / ۱۰ ثانیه، و درخواست‌های بیش از حد throttle می‌شوند نه رد. بیشتر درباره خطای 429.

ثبت و لغو یک سفارش (با احراز هویت)

یک فراخوانی سفارش شما را می‌سازد، امضا می‌کند (ساختار سفارش V2) و ثبت می‌کند. شما یک نوع سفارش انتخاب می‌کنید:

from py_clob_client_v2 import (ClobClient, OrderArgs, OrderType,
                               PartialCreateOrderOptions, Side, OrderPayload)

# authenticated client (creds from create_or_derive_api_key — see Authentication)
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PK, creds=creds)

resp = client.create_and_post_order(
    order_args=OrderArgs(token_id=token_id, price=0.62, side=Side.BUY, size=10),
    options=PartialCreateOrderOptions(tick_size="0.01", neg_risk=False),  # read both off the market
    order_type=OrderType.GTC,            # GTC, GTD, FOK or FAK
)
# resp -> {"success": true, "orderID": "0x...", "status": "live"}
client.cancel_order(OrderPayload(orderID=resp["orderID"]))   # cancel

کارمزدها: فقط گیرندگان می‌پردازند و نرخ منحنی دارد

سازندگان هرگز کارمزد نمی‌دهند. گیرندگان کارمزدی می‌پردازند که ثابت نیست - با میزان عدم قطعیت بازار مقیاس می‌شود و بر حسب دسته‌بندی فرق می‌کند. فرمول:

fee = shares × feeRate × p × (1 - p)      # p = share price, 0..1

جمله p·(1-p) یعنی کارمزد در ۵۰/۵۰ به اوج می‌رسد و به سمت لبه‌های ۱ سنت و ۹۹ سنت کوچک می‌شود - پس گرفتن یک نتیجه تقریباً قطعی ارزان است و یک شیر یا خط گران. نرخ کارمزد گیرنده به تفکیک دسته (feeRate):

نرخ زنده هر توکن را به جای هاردکد کردن با GET /fee-rate-bps?token_id= بخوانید؛ کارمزدها به ۵ رقم اعشار گرد می‌شوند (حداقل 0.00001 pUSD). صفر پرداختن سازندگان دلیل این است که بیشتر بات‌های بدون مزیت به جای گرفتن، قیمت اعلام (quote) می‌کنند.

بازارهای ریسک منفی (چندنتیجه‌ای)

رویدادهای چندکاندیدایی («چه کسی در انتخابات برنده می‌شود؟») بازارهای neg-risk هستند: نتیجه‌هایشان به هم پیوسته‌اند، پس یک سهم No در یک نتیجه به یک سهم Yes در هر نتیجه دیگر تبدیل می‌شود از طریق Neg Risk Adapter - از نظر سرمایه کارآمد اما مکانیک متفاوتی دارد. این‌ها روی قراردادهای متفاوتی از بازارهای دودویی اجرا می‌شوند، پس باید در گزینه‌های سفارش neg_risk=True پاس بدهید (پرچم negRisk بازار را از Gamma بخوانید). اگر آن را جا بیندازید سفارش در برابر Exchange اشتباه امضا و رد می‌شود.

توکن‌های شرطی: split، merge، redeem (فراتر از دفتر)

زیر هر بازار چارچوب توکن شرطی (CTF) قرار دارد. توکن‌های نتیجه توکن‌های ERC-1155 هستند و هر جفت Yes/No دقیقاً با ۱٫۰۰ دلار pUSD قفل‌شده در قرارداد CTF پشتیبانی می‌شود. این سه ابزار پایه را به شما می‌دهد که دفتر سفارشات به تنهایی ندارد:

split و merge پایه آربیتراژ CTF هستند: اگر Yes + No زیر ۱٫۰۰ دلار روی دفتر معامله شوند، هر دو را بخر و با merge به ۱٫۰۰ دلار برگردان؛ اگر بالای ۱٫۰۰ دلار معامله شوند، با split یک دلار را به یک جفت تازه تبدیل کن و هر دو را بفروش. بازخرید (redemption) پس از آن‌که اوراکل نتیجه را روی زنجیره ثبت کرد از طریق قرارداد ConditionalTokens تسویه می‌شود - یک موقعیت وقتی قابل مطالبه است redeemable: true را روی Data API نشان می‌دهد. شناسه‌های موقعیت از مسیر getConditionId → getCollectionId → getPositionId به دست می‌آیند.

پیشرفته: RFQ و بازارهای combo (برای سازندگان جدی)

فراتر از دفتر سفارشات، پلی‌مارکت یک سیستم درخواست قیمت (RFQ) اجرا می‌کند که به‌ویژه برای بازارهای combo به کار می‌رود - بازارهای موجود که در موقعیت‌های ترکیبی چندبخشی بسته‌بندی شده‌اند. جریان سه فاز دارد: یک گیرنده یک قیمت درخواست می‌کند، سازندگان با قیمت‌ها رقابت می‌کنند و سازنده انتخاب‌شده پیش از اجرا یک نگاه آخر برای تأیید یا رد می‌گیرد.

• کشف combo‌ها: GET /v1/rfq/combo-markets (عمومی؛ limit ۱-۱۰۰، cursor، exclude). هر combo دو شناسه موقعیت را نمایان می‌کند (Yes = اندیس ۰، No = اندیس ۱).
• اعلام قیمت به‌عنوان سازنده: POST combos-rfq-api.polymarket.com/v1/maker/quotes (احراز هویت L2). خودتان quote_id را تولید می‌کنید و rfq_id، maker_address، signature_type، یک سفارش امضاشده Exchange و price_e6 / size_e6 را به‌صورت رشته‌های ممیز ثابت شش‌رقمی می‌فرستید (قرارداد *_e6 از افت دقت اعداد اعشاری جلوگیری می‌کند).
• نگاه آخر: در حالی که RFQ در وضعیت AWAITING_MAKER_CONFIRMATION است، با CONFIRM، DECLINE پاسخ بده یا بگذار TIMED_OUT شود.

ماشین حالت RFQ: CREATED → COLLECTING_QUOTES → AWAITING_REQUESTER_ACCEPTANCE → AWAITING_MAKER_CONFIRMATION → EXECUTING → FILLED (وگرنه FAILED / EXPIRED / CANCELED / REJECTED). برای وضعیت زنده به دروازه WebSocket مربوط به RFQ متصل شوید. این حوزه تخصصی است - بیشتر بات‌ها فقط به دفتر CLOB بالا نیاز دارند - اما این‌گونه است که نقدینگی چندبخشی و combo قیمت‌گذاری می‌شود.

بررسی موجودی و allowance

client.get_balance_allowance(...)   # collateral (pUSD) and conditional-token allowances

اگر این allowance صفر نشان داد، پیش از سفارش‌دادن pUSD/CTF را به قراردادهای exchange V2 تأیید (approve) کنید.

بعدی: احراز هویت و کیف‌پول‌ها · WebSocket: استریم دفتر · رفع یک خطای CLOB.