Polymarket CLOB API: Building Your First Order Bot

Polymarket runs a Central Limit Order Book (CLOB) on Polygon, and it exposes a clean API surface that lets bots post limit orders, stream real-time quotes, and manage positions programmatically. If you have experience with traditional exchange APIs but haven't touched a prediction-market CLOB yet, the concepts translate well — the wrinkle is that every order requires an on-chain EIP-712 signature and the settlement asset is USDC.e rather than a perpetual margin token. Here is a practical map of what you need to know before writing your first polymarket api bot.

REST Endpoints You Will Actually Use

The CLOB host is https://clob.polymarket.com. Authentication is header-based: you derive an API key from your wallet using the /auth/derive-api-key endpoint, then pass POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, and POLY_NONCE on every private call. The most important REST routes are:

• GET /markets — paginated list of active markets with condition_id, tokens (YES/NO token addresses), and active / closed flags.
• GET /book?token_id=<id> — current order book snapshot: sorted bids and asks arrays, each entry carrying price and size.
• POST /order — submit a signed limit or market order.
• GET /orders — your open resting orders.
• DELETE /orders/<id> — cancel a single order.
• GET /trades — your fill history, including partial fills.

Order structs must be serialized following the CTFExchange contract's EIP-712 domain, then signed with eth_signTypedData_v4. The Polymarket Python client (py-clob-client) handles this for you, but reading the signing logic yourself is worth an hour of your time — it is the one place where bugs silently produce rejected transactions rather than helpful error messages.

WebSocket Streams for Low-Latency Quoting

REST polling is fine for a slow signal bot, but if you want to post tight spreads you need the WebSocket feed at wss://ws-subscriptions-clob.polymarket.com/ws/. Two channels matter most:

market channel — pushes incremental order book diffs keyed by token_id. You maintain a local order book, apply each delta, and derive mid-price and spread on every update. Latency to the feed typically sits under 50 ms from a US-east server.

user channel — pushes your own order acknowledgements and fills in real time. Wire this up before you open any positions; polling GET /trades to detect fills is a race condition that will hurt your inventory accounting.

A robust bot keeps both channels open with a reconnect loop that detects stale heartbeats. The feed does not guarantee message ordering across tokens in the same subscription, so tag each diff with the server timestamp and sort before applying.

Order Signing and the On-Chain Layer

Each POST /order payload contains a data object with the signed order and a type field (FOK, GTC, or GTD). The exchange contract validates the signature on-chain via Polygon, so the RPC you connect to for nonce management matters. Use a private or load-balanced RPC endpoint rather than the public one; dropped nonces cause silent order rejections that are expensive to debug under live conditions.

For high-frequency quoting, batch your cancel-and-replace cycles using DELETE /orders (bulk cancel) followed immediately by a POST /order. The round-trip from API call to on-chain confirmation on Polygon L2 is typically 1–3 seconds — fast enough for markets with 30-second resolution windows, but you need explicit timing guards for markets approaching settlement.

Risk Controls Before You Go Live

No bot should touch real capital without these layers in place:

• Kill-switch: a file-flag or environment variable that halts order submission instantly. Wire it into your main loop's first conditional on every iteration.
• Inventory skew limits: track your YES and NO token exposure per market. Bias your quotes toward the side that flattens inventory once you breach a threshold — this is the same skew logic used in our polymarket arb bot work.
• Position size caps: maximum USDC at risk per market and in aggregate.
• Market resolution guard: pull GET /markets on startup and filter out any market whose end_date_iso is within your minimum buffer (e.g. 1 hour). Resolution mechanics freeze order books and can leave resting orders stranded.
• Simulation mode: shadow-post orders with a dry-run flag that calls GET /book instead of POST /order and logs the theoretical fill. Run in simulation for at least one full session before going live.

These aren't optional extras — they are the difference between a systematic edge and an expensive lesson. Our trading-bot services always ship with a standardized risk layer before any live deployment.

Putting It Together: Bot Architecture

A minimal viable Polymarket CLOB bot has four threads (or async tasks):

1. Market data — subscribe to the WebSocket market channel, maintain order book, publish best-bid/ask to an in-process queue.
2. Signal — consume best-bid/ask, run your pricing model (fair-value estimate, spread target, inventory skew adjustment), emit target quotes.
3. Execution — diff current resting orders against target quotes, generate cancel and new-order instructions, sign and submit via REST.
4. Risk monitor — read fills from the user WebSocket channel, update position tracker, enforce kill-switch and inventory limits.

Keep the risk monitor on a separate thread with the highest scheduling priority. If the execution thread hangs on an HTTP timeout, the risk monitor should still be capable of cancelling all open orders independently.

When you're ready to move from a single-market proof of concept to a multi-market strategy, latency across markets becomes the binding constraint. The same design patterns that underpin cross-venue work — shared order book state, unified risk accounting, and deterministic cancel logic — apply here too. You can see how we approach multi-venue complexity in our cross-venue arbitrage case study.

---

If you want to go from this map to a production-grade bot without burning weeks on API quirks and signing bugs, start a project with us. TierZero builds and deploys custom CLOB bots for Polymarket and other venues — from initial spec to live trading.