🔌 Technical
Polymarket API Guide: How the CLOB Works and How to Use It
The Polymarket CLOB API is what makes automated trading possible on Polymarket. This guide explains the architecture, authentication, core endpoints, and real Python examples — everything you need to start building (or understand what's happening under the hood when PolyBot trades for you).
📌 Note
PolyBot handles all of this automatically. You do not need to understand the API to use PolyBot — just paste your API key into the Setup Wizard. This guide is for developers who want to understand the mechanics or build their own integrations.
What Is the Polymarket CLOB API?
Polymarket runs a Central Limit Order Book (CLOB) — the same order-book structure used by professional exchanges like Binance and Coinbase. Unlike AMMs (automated market makers), the CLOB matches buy and sell orders by price priority, giving traders precise entry and exit control.
The CLOB API is a REST API hosted by Polymarket that allows programs to:
- Read live market data (prices, order book depth, trade history)
- Place and cancel limit orders
- Query account balances and open positions
- Stream real-time updates via WebSocket
REST API vs WebSocket
The API has two modes:
- REST API: Request/response. Used for placing orders, reading account state, and fetching market data snapshots. Base URL:
https://clob.polymarket.com - WebSocket: Streaming. Used for real-time price feeds and order book updates. Reduces polling latency significantly for high-frequency strategies.
Authentication — L1 vs L2
The Polymarket API uses two levels of authentication:
- L1 (Wallet-level): Signs requests with your wallet's ECDSA private key using the EIP-712 standard. Required for any order placement, cancellation, or account access.
- L2 (API Key-level): A derived API key created from your wallet. Used for most authenticated requests after the initial L1 setup. This is what you enter into PolyBot's Setup Wizard.
Getting your API key (L2 setup)
To generate an L2 API key from your wallet:
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds
# Connect with your wallet private key (L1)
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137, # Polygon mainnet
key="YOUR_PRIVATE_KEY"
)
# Create L2 API credentials
creds = client.create_or_derive_api_creds()
print(f"API Key: {creds.api_key}")
print(f"Secret: {creds.api_secret}")
print(f"Pass: {creds.api_passphrase}")
⚠️ Security: Never commit your private key to version control. Store it in an environment variable or secrets manager. PolyBot stores it in an encrypted local config file, never transmitting it externally.
Core REST Endpoints
Public endpoints (no auth required)
GET
/markets
— List all active markets
GET
/book?token_id={tokenId}
— Full order book for a market token
GET
/price?token_id={tokenId}&side=BUY&size=10
— Best executable price for a given size
GET
/trades?market={conditionId}
— Recent trade history for a market
Authenticated endpoints (L2 required)
POST
/order
— Place a new limit or market order
DELETE
/order/{orderId}
— Cancel a specific open order
DELETE
/orders
— Cancel all open orders (market or global)
GET
/data/balance-allowance
— Query USDC balance and allowance
GET
/orders?market={conditionId}
— List your open orders
Reading Market Data
Fetching active markets
# Get all active markets
markets = client.get_markets()
for market in markets.data:
print(f"Market: {market['question']}")
print(f" YES token: {market['tokens'][0]['token_id']}")
print(f" NO token: {market['tokens'][1]['token_id']}")
Getting order book state
# Fetch full order book for a YES token
token_id = "71321045679252212594626385532706912750332728571942532289631379312455583992563"
book = client.get_order_book(token_id)
print(f"Best ask: {book.asks[0].price} (size: {book.asks[0].size})")
print(f"Best bid: {book.bids[0].price} (size: {book.bids[0].size})")
print(f"Spread: {float(book.asks[0].price) - float(book.bids[0].price):.4f}")
Placing Orders
Limit orders vs market orders
Polymarket supports:
- GTC (Good Till Cancelled): Order stays open until filled or manually cancelled. Best for passive entry at a specific price.
- GTD (Good Till Date): Order expires at a specific timestamp. Useful for time-sensitive strategies.
- FOK (Fill Or Kill): Executes immediately at full size or cancels. Equivalent to a market order.
from py_clob_client.clob_types import OrderArgs, OrderType
# Place a GTC limit buy order at 0.65 for 10 USDC of YES shares
order_args = OrderArgs(
price=0.65, # Price per share (0–1)
size=10, # USDC amount
side="BUY",
token_id=token_id,
)
signed_order = client.create_order(order_args)
resp = client.post_order(signed_order, OrderType.GTC)
print(f"Order ID: {resp['orderID']}")
WebSocket Price Feeds
For real-time updates, connect to the Polymarket WebSocket endpoint to receive live price ticks and order book changes without polling:
import websockets, asyncio, json
async def stream_prices(token_id):
uri = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
async with websockets.connect(uri) as ws:
# Subscribe to price feed
await ws.send(json.dumps({
"type": "subscribe",
"channel": "market",
"assets_ids": [token_id]
}))
async for msg in ws:
data = json.loads(msg)
print(f"Price update: {data}")
asyncio.run(stream_prices(token_id))
Rate Limits and Best Practices
- REST rate limit: ~10 requests/second per IP. Use WebSocket for real-time data to avoid hitting this limit.
- Order rate limit: Burst of ~20 orders/second. PolyBot's internal queue prevents exceeding this.
- Always cancel on shutdown: Implement a cleanup handler that cancels all open orders when your bot stops — otherwise orders may fill at unintended prices.
- Handle partial fills: Your fill tracking logic must account for orders that fill partially across multiple trades.
- Use GTC, not FOK, for passive strategies: Market orders (FOK) cross the spread, which costs you more per trade than passive limit orders.
Skip the API complexity
PolyBot handles authentication, order management, rate limits, and error recovery automatically. Paste your API key into the Setup Wizard and you're live in minutes.
Frequently Asked Questions
Yes. The Polymarket CLOB REST API and WebSocket feeds are free to access. You only pay trading fees within the Polymarket protocol itself (typically 2% of winnings).
No KYC is required to use the Polymarket API or trade on the platform (outside of US-restricted users). You authenticate using your wallet private key, not an identity verification process.
Polymarket provides an official Python client library (py-clob-client). The underlying REST API can be called from any language (JavaScript, Go, Rust), but Python has the most complete official support.
L1 authentication uses your wallet private key to sign API requests with ECDSA (EIP-712). It is required to generate L2 API credentials, which you then use for all standard authenticated requests.