Polymarket API Guide for Trading Bots

The Polymarket API is the set of public HTTP and WebSocket interfaces bots use to discover markets, read books, authenticate a wallet, and place or cancel orders. For a trading bot, the core path is Gamma for market metadata, the CLOB for books and trading, and optional streams for live updates—not a single “bot endpoint.”

Trading collateral is pUSD (Polymarket USD), a USDC-backed ERC-20 on Polygon. Orders target outcome token IDs, and prices behave like implied probabilities once you understand how prediction markets work.

What is the Polymarket API?

It is not one REST host. Official surfaces split by job:

Public market discovery needs no credentials. Private trading needs wallet-backed CLOB auth.

Which Polymarket API endpoints does a trading bot need?

Most bots only need four jobs:

1. Discover — list or fetch events/markets from Gamma (/markets, /events, slug lookup).
2. Resolve instruments — read YES/NO token IDs, tick size, and whether the market accepts orders.
3. Trade — read /book (or batch books), then POST/DELETE orders on the CLOB.
4. Reconcile — poll Data API positions/trades, or subscribe to user WebSocket fills.

Start with official clients (@polymarket/client / Python polymarket secure clients, or CLOB v2 packages) unless you must sign raw HTTP yourself. Raw integrations must stay current with CLOB V2 order fields and exchange contracts.

How does Polymarket API authentication work?

CLOB auth has two layers:

1. L1 (wallet) — EIP-712 ClobAuth signature proves you control the Polygon address. Use it to create or derive API credentials (apiKey, secret, passphrase).
2. L2 (API key) — HMAC-SHA256 over timestamp + METHOD + path + body with the API secret. Private REST calls send POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, POLY_API_KEY, and POLY_PASSPHRASE.

Order placement also needs a wallet signature on the order itself. L2 authenticates the request; the signed order authorizes the trade.

Keep private keys and API secrets off laptops and chat logs. Rotate credentials if a process leaks env vars.

How do bots discover markets and token IDs?

Gamma is the catalog. A common loop:

1. Search or list open markets (closed=false).
2. Open the event/market you care about (by slug or id).
3. Read each outcome’s token ID — every price, book, and order uses that id.
4. Confirm market status, tick size, and minimum size before sending size.

An event contract is the tradable question; token IDs are the wire identifiers your bot passes to the CLOB. Never hardcode token IDs across redeploys without re-fetching metadata.

How do trading bots place and manage Polymarket orders?

Bots trade shares of an outcome at a price between 0 and 1 (subject to tick size), collateralized in pUSD.

Limit orders

• GTC — rests until fill or cancel.
• GTD — expires at a timestamp (docs add a one-minute safety buffer; very short expiries are rejected).

Market-style execution

• FAK (Fill and Kill) — take what liquidity allows, cancel the rest (common default).
• FOK (Fill or Kill) — fill entirely now or not at all.

After a match, settlement is asynchronous on-chain. Wait for fill settlement before trusting position size. Thin books punish naive marketable size—spreads, depth, and slippage matter as much as your signal.

Cancel paths (DELETE single/batch/market/all) and optional heartbeats matter for unattended bots: if your process dies without cancels, resting quotes can sit exposed.

How does the Polymarket WebSocket API fit a bot loop?

Use REST for setup and WebSockets for the hot path:

• Market channel — subscribe with assets_ids (token IDs) and type: "market" for book snapshots, price updates, trades, and lifecycle events.
• User channel — authenticated stream for your orders and trades so you are not polling every fill.

A practical architecture: Gamma + REST books for cold start → market WS for quotes → strategy decides → signed order over REST → user WS + Data API for reconciliation. Poll only when streams drop.

What rate limits and ops traps matter for Polymarket bots?

Cloudflare IP limits throttle rather than hard-fail when you burst. Examples from the docs:

• Gamma general: 4,000 / 10s (stricter on /markets and /events)
• CLOB general: 9,000 / 10s; /book 1,500 / 10s
• Trading POST /order: high burst caps, plus separate per-signer token-bucket limits

Ops checklist for bots:

• Cache Gamma metadata; do not scrape /markets every tick.
• Batch book reads when scanning many tokens.
• Back off on throttle; do not tight-loop cancels.
• Check geographic restrictions before live order paths.
• Prefer official SDKs after CLOB V2 (pUSD collateral, updated order struct, EIP-712 exchange domain "2").

If you only need mobile execution without running infra, a ready Telegram workflow on Sides.Trade covers browse, orders, and portfolio without hosting a CLOB client—custom API bots still win when you need proprietary signals or inventory logic.

How should you structure a minimal Polymarket trading bot?

1. Fund an account and confirm pUSD balance.
2. Create a secure client (or create/derive L2 credentials).
3. Resolve a market slug → outcome token ID.
4. Read the book; size with tick and min-size constraints.
5. Place a small FAK or limit order; wait for settlement.
6. Subscribe to market + user sockets before scaling size.
7. Add cancels-on-shutdown, idempotent client order ids, and position checks.

Ship that loop first. Strategy code is worthless if auth, token resolution, or cancel safety is wrong.