CLOB Architecture and Order Flow

Polymarket is a Central Limit Order Book — not an AMM. That one fact shapes every integration decision downstream. Throughout this track, examples use the Agent Framework — the running reference implementation of a Polymarket trading bot built across these lessons.

Where the Book Lives

The orderbook itself is off-chain. Bids and asks are held in Polymarket's backend database, sorted by price, matched by a centralized engine. This is why orderbook depth queries go through a REST API (/book?token_id=...) and not through an RPC call to Polygon. Only the settlement of matched orders happens on-chain: the ERC-1155 (a multi-token standard used here for conditional tokens representing outcome shares) transfers and the USDC.e collateral movements.

That off-chain structure gives Polymarket the speed advantage of a traditional exchange: sub-second order placement, deep price levels, standard limit-order mechanics. It also means your bot needs to speak HTTP to the Polymarket CLOB API — not just Web3.

The Four Endpoints That Matter

1. /markets — Lists all active markets with their condition IDs and token IDs.
2. /book?token_id=... — Returns the live orderbook for a specific outcome token. Bids and asks, sorted.
3. /balance-allowance?asset=...&wallet=... — Returns what Polymarket believes your wallet has available. Use this instead of direct Web3 balance calls during pre-trade checks. (An allowance is the ERC-20 spending permission you grant the exchange contract with an approve() transaction — without it, your balance is visible but unspendable. The "Dual-Approval Wall" lesson later in this track covers it in depth.)
4. /orders — POST to place an order (signed EIP-712 payload — the typed structured-data signing standard that produces verifiable off-chain signatures), GET to inspect existing orders.

A Polymarket bot that understands these four endpoints can do 90% of what it needs to do. The remaining 10% — position resolution, PnL queries, historical fills — lives at other endpoints but is not on the critical path for trade execution.

Two Levels of Authentication

Before any of the authenticated endpoints work, the CLOB requires a two-level auth handshake — and the distinction trips up nearly every first integration:

• L1 — your private key. It does two jobs: signing each EIP-712 order payload, and a one-time derivation of API credentials. You call the create-or-derive API key endpoint with an EIP-712 signature, and the CLOB returns an API key, secret, and passphrase tied to your wallet.
• L2 — your API credentials. Every authenticated REST call after that — placing orders, canceling, reading your open orders and balances — must carry HMAC-signed headers built from those credentials: the API key, a timestamp, and an HMAC signature over the request.

In other words: the EIP-712 signature on the order proves the order came from your wallet; the L2 HMAC headers on the request prove the API call came from you. Client libraries like py-clob-client handle both layers once configured (client.create_or_derive_api_creds() then client.set_api_creds(...)), but if you speak raw HTTP, you implement both yourself. A bot with a perfect order signature and no L2 headers never gets past the front door.

Inline Diagram — Order Flow

Why Thin Books Matter

Political markets on Polymarket are typically thin. A top-of-book size of 100 shares is normal. A taker order of $50 can walk two or three price levels before it fills, costing 2-4 cents of slippage — which is meaningful when most contracts trade between $0.30 and $0.70.

The implication for bot logic:

• Check depth before placing taker orders. Query /book and compute the walked-price at your intended size.
• Set a max slippage tolerance. If the walked price exceeds threshold, place a maker order instead and accept possible non-fill.
• Size orders to the book. Do not blindly send $500 at a market showing $80 at top-of-book.

The Rule

Understand the CLOB before integrating. The four endpoints are your API surface. The off-chain matching engine is your speed layer. Polygon is your settlement layer. Thin books are your execution constraint. Every Polymarket bot decision flows from these four facts.