On this page9 sections
Four APIs, one bot
"The Polymarket API" is really four services with different jobs, different hosts and different rules. Every bot in the catalog touches at least two of them.
| Service | Host | What it is for | Auth |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | Discovery: events, markets, tags, search, slugs, resolution dates, outcome token ids | None |
| CLOB | clob.polymarket.com | Prices, order books, midpoints, tick sizes; placing and cancelling orders; your orders and fills | None to read, L2 credentials to trade |
| Data API | data-api.polymarket.com | Positions, trade history, holders, leaderboards — for any wallet | None |
| WebSocket | wss://ws-subscriptions-clob.polymarket.com | Live order-book and price updates (market channel); your own order and trade events (user channel) | None for market, L2 for user |
Around them sit a few smaller pieces: a geoblock endpoint on polymarket.com that tells a client whether its IP may trade, a relayer that executes gasless wallet operations for smart-wallet accounts, and a bridge API for deposits. Copy-trading tools live on the Data API; market makers live on the WebSocket and the CLOB; everyone starts at Gamma.
How the CLOB works
The order book is a hybrid. Orders are signed by the user's wallet (EIP-712 typed data) and submitted to Polymarket's off-chain matching engine; when two orders match, the trade settles on Polygon through the CTF Exchange contracts, moving collateral one way and outcome shares the other. Outcome shares are conditional tokens — one token per outcome per market — that redeem for one unit of collateral if that outcome resolves true. The collateral is pUSD, a token backed one-to-one by USDC.
Two consequences matter for a bot. Settlement is asynchronous: a fill is reported immediately but the on-chain transaction lands seconds later, which is why the SDKs ship a "wait for settlement" helper. And negative-risk markets — multi-outcome events where outcomes are mutually exclusive — settle through a separate exchange contract, so an order signed against the wrong contract is rejected as an invalid signature. The book endpoint reports the flag; the current SDKs resolve it automatically.
What changed in 2026
The CLOB moved to V2 on 28 April 2026, and V1 clients stopped working that day. The visible changes: collateral moved from USDC.e to pUSD; the order struct dropped the nonce and the signed fee rate (fees are now set by the protocol at match time) and gained a millisecond timestamp, a metadata field and a builder field; the exchange signing domain moved to version 2. Since 4 May 2026 new accounts get a Deposit Wallet — a smart wallet that the SDK can deploy for you — rather than the older proxy and Safe wallets.
The client libraries changed with it, twice. The original py-clob-client and @polymarket/clob-client were archived; the interim -v2 packages have themselves been superseded by unified SDKs: @polymarket/client for TypeScript (built on viem) and polymarket-client for Python, each with a public client for reading and a secure client for trading. Method names shifted to list/fetch patterns and the clients resolve tick size and negative-risk for you.
The practical test when you evaluate any bot: if its README still mentions USDC.e, feeRateBps, a nonce, or installs py-clob-client, it was written for V1 and needs porting before it can trade. Polymarket keeps a migration guide at docs.polymarket.com under "migrate from previous SDKs".
Authentication, in two levels
Reading needs nothing. Trading needs two levels of credential:
- L1 — one EIP-712 signature from your signing key attesting that you control the wallet. You make it once.
- L2 — an API key, secret and passphrase that the CLOB issues against that signature (create with POST /auth/api-key, recover with GET /auth/derive-api-key). Every trading request then carries HMAC-signed headers built from the L2 secret. Credentials can be revoked and re-derived; a bot should hold L2 credentials and, unless it is an EOA, a signer for the wallet — never more.
Accounts also need standing token approvals: pUSD approved to both the standard and the negative-risk exchange, and the conditional tokens approved for both. The SDKs and the relayer set these up for smart-wallet accounts; an externally-owned account (type 0) needs allowlisting and pays its own gas in POL. The wallets guide goes through the four wallet types and what each credential can do.
Orders: types, ticks, expiry
- GTC rests until filled or cancelled; GTD rests until an expiry you set — and expires one minute *before* the stated time as a safety margin, with a minimum lifetime of a few minutes, so a GTD meant to live N seconds is set to now + 60 + N.
- FOK fills entirely now or not at all; FAK fills what it can now and cancels the rest. These are the market-order types; the SDKs' market-order helpers take an amount in collateral or in shares plus a worst acceptable price.
- Post-only adds liquidity only: if it would match immediately it is rejected, which is how a market maker makes sure it never pays a taker fee by accident.
- Prices must sit on the market's tick size — 0.01, 0.001 or 0.0001, read from the book — and sizes above its minimum order size. A price of 0.501 is valid in a 0.001 market and rejected in a 0.01 market.
- Up to 15 orders can be posted in one batch; cancels have their own endpoints, including cancel-all.
- Some markets impose a matching delay: an order comes back with status "delayed" and matching starts when the delay elapses.
Fees
Only takers pay. The fee on a fill is
| Quantity | Meaning |
|---|---|
| fee = C × rate × p × (1 − p) | C shares at price p |
| rate | 0.07 crypto · 0.05 sports, economics, culture, weather, other · 0.04 finance, politics, mentions, tech · 0 geopolitics |
So the fee peaks at a 50-cent price — 1.75% of notional on a crypto market, 1.25% on sports, 1% on politics, nothing on geopolitics — and falls toward zero near 0 and 1. It is charged in collateral at match time and is not part of the signed order. Makers pay nothing and receive a rebate of a share of the taker fees; takers also earn tiered rebates by volume. Each market's fee parameters are readable from its market details, and any strategy that crosses the spread should be priced against them before it is switched on.
Rate limits
Two layers. Per IP, at the edge, in ten-second windows — at the time of writing 9,000 requests for the CLOB in general, 1,500 each for the book, price and midpoint endpoints, 300 for the Gamma market list, 150 for Data API positions, 5,000 burst for single-order placement and 250 for cancel-all. And per signing key, since July 2026: token buckets for placing and cancelling, refilling at a rate that rises with your 30-day maker volume; an empty bucket returns 429 with Retry-After and remaining-budget headers. Subscribe to WebSockets, batch your orders, respect Retry-After, and keep a per-endpoint budget in the bot — the numbers above change, and the docs' rate-limit pages are the source of truth.
Geography
The geoblock endpoint returns whether the calling IP may trade, with its country and region. New orders are refused from more than thirty jurisdictions — the US, UK, France, Germany, Australia, Brazil, several Canadian provinces, Russia among them — where accounts are close-only; a few sanctioned territories are blocked entirely; reads work everywhere. A bot should call it at start-up and fail loudly rather than discover the answer from rejected orders. What is and isn't allowed covers the rest.
Where to read the real thing
Polymarket's documentation at docs.polymarket.com is the source for everything above, and it publishes an llms.txt index that lists every page; the trading quickstart, the place-orders page, the fees page, the two rate-limit pages and the migration guide are the ones a bot author reads first. For the Python side of this — installing the SDK and getting to a first order — see the Python guide; for the whole loop from idea to deployed bot, the build guide.
Polymarket Agents
Sentiment / NewsOfficial open-source framework from Polymarket for building AI agents that trade autonomously. Combines Polymarket & Gamma market data, news and web-search sourcing, and RAG-powered LLM tooling so an agent can research a market and place trades from the command line.
Dome
Platforms & ToolsPrediction-market APIs and SDK for developers. One integration for Polymarket and Kalshi data — historical order books, real-time trade webhooks and WebSockets, and backtesting — via REST plus TypeScript and Python SDKs.
PolyData
Platforms & ToolsAnalytics workspace and trading terminal for Polymarket. Track positions, liquidity and market flow in real time, analyze any wallet's PnL, exposure and win rate from live on-chain data, rank top traders on a leaderboard, and execute in a focused terminal — from market signal to order entry in one place.
Frequently asked questions
- Is the Polymarket API free?
- Yes. Reading markets, books, prices, positions and trades needs no key and costs nothing; placing orders needs credentials derived from your wallet and costs nothing beyond the market's taker fee when an order matches. What is not free is unlimited use: every endpoint is rate-limited per IP, and order placement is additionally budgeted per signing key.
- Do I need to know Solidity or run a node?
- No. The CLOB matches orders off-chain and settles them on Polygon for you; a bot signs orders with a key and talks HTTP and WebSocket. You never call a contract directly unless you choose to — the SDKs and the relayer handle approvals, deposits and settlement for smart-wallet accounts.
- My bot's README mentions USDC.e, feeRateBps or py-clob-client. Is it outdated?
- Yes. Those belong to CLOB V1, which stopped working on 28 April 2026. A working 2026 bot uses pUSD as collateral, never sets a fee in the order, and talks to the CLOB through the unified SDKs (@polymarket/client or polymarket-client) or the V2 REST shape. A README that still shows the old names is a useful red flag in itself.
- Which API do I poll for live prices?
- None, if you can help it. Subscribe to the market WebSocket channel, which pushes order-book and price changes and costs you no request budget; use REST snapshots of /book, /price and /midpoint to initialise and to heal after a reconnect. Polling the book at full speed burns the 1,500-per-ten-seconds limit and still lags the feed.