API · Reference
The CLOB (Central Limit Order Book) at clob.polymarket.com is where orders
rest and match. You read the book, prices and tick size with no auth, and trade
(place / cancel orders, read your balance) with API credentials and signing.
This is the CLOB V2 reference — collateral is pUSD, fees are on-chain, and
makers pay zero.
Read the order book (no auth)
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"Sample response
{
"market": "0x...",
"bids": [ { "price": "0.62", "size": "1400" }, { "price": "0.61", "size": "900" } ],
"asks": [ { "price": "0.64", "size": "1100" }, { "price": "0.65", "size": "2000" } ]
}Read endpoints
| Endpoint | Returns |
|---|---|
GET /book?token_id= | Full order book (bids / asks). |
GET /price?token_id=&side= | Best bid or ask. |
GET /midpoint?token_id= | Mid = (best bid + best ask) / 2. |
GET /spread?token_id= | Best ask − best bid. |
GET /tick-size?token_id= | Minimum price increment (round your price to it). |
Limits are high: CLOB ~9,000 requests / 10s, /book and /price 1,500 / 10s,
and over-limit requests are throttled, not rejected. More on 429s.
Place & cancel an order (auth)
One call builds, signs (the V2 order struct) and posts your order. You choose an order type:
| Type | Behaviour |
|---|---|
GTC | Good-Till-Cancelled — rests on the book until filled or cancelled. |
GTD | Good-Till-Date — rests until an expiry timestamp. |
FOK | Fill-Or-Kill — fill the whole order immediately or cancel it. |
FAK | Fill-And-Kill — fill what it can immediately, cancel the rest. |
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"),
order_type=OrderType.GTC, # GTC, GTD or FOK
)
client.cancel_order(OrderPayload(orderID=resp["orderID"])) # cancelnonce,
feeRateBps, taker and expiration and added timestamp,
metadata and builder; the Exchange EIP-712 domain version is "2".
Fees are collected on-chain at match — makers pay 0, only takers pay.
Before trading you must approve pUSD + conditional tokens to the three V2 contracts
(see the allowance fix).Check balance & allowance
client.get_balance_allowance(...) # collateral (pUSD) and conditional-token allowancesIf this shows zero allowance, approve pUSD/CTF to the V2 exchange contracts before ordering.
outcomes array (Gamma returns it, and
clobTokenIds, as JSON-encoded strings you must decode) and map by name.Next: Authentication & wallets · WebSocket: stream the book · Fix a CLOB error.
