The Polymarket API: A Practical Guide for Bot Builders

The API surfaces at a glance

Polymarket's developer platform grew organically, so the first thing that confuses new builders is that there isn't one API — there are several, each with a different job:

In 2026 Polymarket has kept expanding the platform — there are now also a Relayer API (transaction submission), a Bridge API (cross-chain deposits), a Combos/RFQ API (multi-leg positions via request-for-quote), and a Perps API for perpetual futures. Most trading bots never touch these; the four surfaces in the table cover the standard read–signal–execute loop. Always confirm details against the official documentation, which Polymarket has been actively consolidating.

Quickstart: fetch active markets

The Gamma API is where every bot starts. It returns events (containers like "2026 Midterm Elections") and their child markets (individual questions with tradable outcomes). No signup, no key:

curl "https://gamma-api.polymarket.com/events?closed=false&order=volume&ascending=false&limit=5"

The same thing in Python, filtered the way a real bot would:

import requests

params = {
    "closed": False,
    "order": "volume",       # most active first
    "ascending": False,
    "limit": 100,
    "tag_id": 2,             # politics; omit for all categories
    "volume_min": 10000,     # skip illiquid markets
}
events = requests.get(
    "https://gamma-api.polymarket.com/events",
    params=params, timeout=10,
).json()

for event in events:
    for market in event["markets"]:
        print(market["question"], market.get("outcomePrices"))

Two fields matter more than everything else in the response: conditionId identifies the market on-chain, and clobTokenIds are the ERC-1155 token IDs for each outcome (Yes/No). Every order book lookup, WebSocket subscription, and order you ever place is keyed by token ID — cache the mapping from question → token IDs early and keep it fresh.

Reading order books and prices

The CLOB (central limit order book) API serves the live book for any token ID — bids, asks, spreads, tick size, and last trade. Reads are public:

# Order book for one outcome token
curl "https://clob.polymarket.com/book?token_id=<CLOB_TOKEN_ID>"

# Midpoint and spread
curl "https://clob.polymarket.com/midpoint?token_id=<CLOB_TOKEN_ID>"
curl "https://clob.polymarket.com/spread?token_id=<CLOB_TOKEN_ID>"

Prices are quoted 0.00–1.00 and read directly as implied probability: a best ask of 0.43 on a Yes token means the market prices the event at roughly 43%. For bots, the practical numbers to watch are the spread (your instant cost of taking liquidity) and book depth (how much size you can move before you become the price).

Real-time: the WebSocket market channel

Polling REST endpoints is fine for discovery, but any bot that reacts to the market should be on the WebSocket. Connect to the public market channel and subscribe by token IDs:

wss://ws-subscriptions-clob.polymarket.com/ws/market

# subscribe message
{"type": "market", "assets_ids": ["<CLOB_TOKEN_ID_1>", "<CLOB_TOKEN_ID_2>"]}

You'll receive book snapshots on subscribe, then incremental price changes and trade events as they happen. An authenticated user channel does the same for your own orders and fills. Standard production hygiene applies: apply updates in timestamp order, detect stale connections with heartbeats, and re-snapshot after every reconnect.

Trading through the API

Execution is where Polymarket differs most from a normal exchange API. There is no "create API key" button — authentication is derived from your wallet:

• L1 (wallet signature): your EOA signs a message to derive API credentials and authorize account-level actions.
• L2 (derived credentials): day-to-day order placement and cancellation use the derived credentials, so your private key isn't touched on every request.

The official clients handle this dance for you. The long-standing Python client is py-clob-client, and Polymarket now also ships unified TypeScript and Python SDKs:

pip install py-clob-client

from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    key=PRIVATE_KEY,      # signer — use a dedicated bot wallet
    chain_id=137,         # Polygon
)
# derive L2 creds once, then place/cancel orders
client.set_api_creds(client.create_or_derive_api_creds())

Non-negotiables if real money is involved: use a dedicated wallet funded only with what the bot may lose, keep keys in a secrets manager (never in the repo), start with fill-or-kill orders at trivial size, and build the kill switch before the strategy. If you're in the US, trading happens on Polymarket US — the CFTC-regulated venue with its own API, KYC, and market set; the international API enforces geographic restrictions for trading.

Rate limits and etiquette

Public endpoints sit behind IP-based rate limiting, and order placement/cancellation on the CLOB uses per-signer token-bucket limits. Exact numbers are published in the docs and change, so treat these as design constraints rather than constants to hardcode: batch metadata requests, cache the market catalog instead of re-fetching it, use the WebSocket instead of tight REST polling loops, and back off on 429s. A well-behaved bot rarely hits limits; a naive one hits them in the first hour.

The architecture of a news-driven trading bot

Every profitable Polymarket bot we've seen decomposes into the same four stages:

1. Ingestion — market catalog from Gamma, live books from the WebSocket, and an information source that moves faster than the odds.
2. Signal — deciding that new information implies the current price is wrong, and by how much.
3. Risk — position sizing, exposure caps, and a circuit breaker.
4. Execution — signed orders via the CLOB client, reconciled against fills on the user channel.

Here's the part the official APIs can't give you: stages 1–4 all consume market data, which tells you what already happened. Sub-100ms arbitrage on that data is a latency war you probably don't want to fight. The edge that doesn't require co-location is news — odds on Polymarket reprice over minutes, not milliseconds, after a story breaks.

Frequently asked questions