Polymarket API: How It Works, How to Get a Key and How to Build a Trading Bot
Yes, Polymarket has an API, and it’s free to use. Market data requires no key at all, and trading only costs the normal trading fees. The catch is that Polymarket runs two separate APIs. The international API at docs.polymarket.com is the one most tutorials cover, but it doesn’t allow U.S. users to open new positions. U.S. traders need the Polymarket US API, which has its own keys, its own SDKs and identity verification.
This guide covers both, starting with what you can do without any credentials.
What Is the Polymarket API?
The Polymarket API is a set of REST and WebSocket endpoints for reading market data and placing trades programmatically. On the international platform, which Polymarket now calls Polymarket Predictions, each API handles a separate job:
| API | Base URL | What it does | Key needed? |
|---|---|---|---|
| Gamma API | gamma-api.polymarket.com | Finds events and markets, and returns their metadata | No |
| CLOB API | clob.polymarket.com | Prices and order books (public); placing and canceling orders (authenticated) | Only for trading |
| Data API | data-api.polymarket.com | Positions, trade history and activity | No |
| Relayer API | relayer-v2.polymarket.com | Submits wallet transactions without holding POL for gas | Yes |
| Bridge API | bridge.polymarket.com | Funding and withdrawals | Yes |
| WebSockets | ws-subscriptions-clob, ws-live-data, sports-api | Live order books, account updates, trades and live game scores | Only the user channel |
The Sports WebSocket is worth knowing about if you trade games. It streams live game status and scores, so a bot can react to game state without a separate data feed.
Does Polymarket Have an API? Yes, Two of Them
| International Polymarket | Polymarket US | |
|---|---|---|
| Operator | Polymarket’s offshore entity | QCX LLC, a CFTC-registered exchange |
| Docs | docs.polymarket.com | docs.polymarket.us |
| Can U.S. users open positions? | No (the U.S. is close-only) | Yes |
| Account setup | Crypto wallet; no identity check for credentials | Identity verification required |
| Authentication | Wallet signature (L1) plus HMAC API credentials (L2) | Ed25519 API keys |
| Settlement | USDC on the Polygon blockchain | U.S. dollars |
| SDKs | Python, TypeScript and Rust clients | polymarket-us for Python and TypeScript |
The keys don’t cross over. Polymarket US credentials won’t work on the international CLOB, and international credentials won’t work on Polymarket US. The order formats are different too, so a bot built for one needs real changes to run on the other.
Don’t use a VPN or an overseas server to reach the international API from the U.S. The international platform checks location, rejects orders from restricted regions, and its terms prohibit getting around the restriction. If your account is flagged, you have no recourse on funds or positions. Polymarket has asked the CFTC to let U.S. users back onto the international exchange, but that request is still pending.
Is the Polymarket API Free?
Yes. There’s no paid tier or subscription on either platform:
- Market data is free and needs no account, key or wallet on the international API.
- Trading costs only normal trading fees. On the international platform, fees scale with price using the formula fee rate × p × (1 − p), so they’re highest near 50¢ and lowest near the extremes. Polymarket US publishes its own fee schedule.
- Rate limits are generous for most individual traders (see the bot section below).
Your real costs are hosting if you run a bot around the clock, and the spread you pay on every trade.
How to Use the Polymarket Gamma API
The Gamma API is the best place to start, because it needs no setup. Every market lookup begins here.
List active markets
curl -G “https://gamma-api.polymarket.com/markets” \
–data-urlencode “closed=false” \
–data-urlencode “limit=5”
That returns five open markets with their questions, outcomes, prices and IDs. Paste it into a terminal and you’ll get live data back.
Filter for what you want
The Gamma API has two main endpoints:
- /events returns grouped markets, like every market tied to one NFL game.
- /markets returns individual Yes/No markets.
Filter with parameters like closed, active and limit, or with a tag. For example, tag_slug=soccer on the events endpoint returns only soccer events. There’s also a /public-search endpoint for keyword lookups.
Grab the token ID
Each outcome in a market has a token ID. That’s the identifier the CLOB API uses for order books, prices and orders. The standard workflow is:
- Find the market on Gamma.
- Take the outcome’s token ID.
- Use it on the CLOB API to read the order book or place an order.
Add live prices
Gamma prices are fine for browsing, but a bot needs live order books. Use the CLOB’s public /book and /price endpoints with the token ID, or subscribe to the CLOB Market Channel WebSocket for continuous updates. Neither requires a key.
How to Get a Polymarket API Key
Polymarket US (for U.S. traders)
Create an account in the Polymarket US app
And complete identity verification. Most users are verified automatically; some are asked for a government ID and selfie.
Sign in at polymarket.us/developer
Using the same login method.
Create a key.
You’ll get a Key ID and a Secret Key. Store the secret immediately, because you won’t be able to view it again.
Install the SDK
(pip install polymarket-us or npm install polymarket-us). It handles Ed25519 request signing for you.
International Polymarket (outside the U.S.)
International credentials aren’t issued from a dashboard. You generate them from your wallet:
L1
Sign a typed-data message with your wallet’s private key to prove you control the wallet.
Create or derive credentials
Send that signature to the /auth/api-key endpoint (or /auth/derive-api-key if credentials already exist). You’ll get an apiKey, secret and passphrase.
L2
Sign each private request with the secret using HMAC-SHA256 and send it with five POLY_ headers.
The official SDKs do all of this with one call (create_or_derive_api_key in Python). Note that placing an order needs both layers: L2 authenticates the request, and a separate wallet signature authorizes the order itself.
Building a Polymarket API Trading Bot
A Polymarket API trading bot has four parts, whichever platform you build on:
Market discovery.
Pull the markets you care about from Gamma (international) or the market data endpoints (Polymarket US).
Live data.
Subscribe to order book and price WebSockets. For sports, add the Sports WebSocket for live scores.
Decision logic
Your model or rules. This is the only part that can give you an edge, and it’s the part no tutorial can hand you.
Execution and risk controls.
Place, cancel and track orders, with hard limits on position size, daily loss and open orders.
Rate limits that matter (international API)
| Endpoint | Limit |
|---|---|
| Gamma general | 4,000 requests / 10 seconds |
| Gamma /markets | 300 requests / 10 seconds |
| CLOB general | 9,000 requests / 10 seconds |
| CLOB /book | 1,500 requests / 10 seconds |
| Place or cancel order | 5,000 / 10 seconds burst; 48,000 / 10 minutes sustained |
When you exceed a limit, requests are throttled rather than rejected outright. Polymarket US publishes separate limits in its own docs.
What bot tutorials leave out
- You’re competing with professionals. Market makers with dedicated infrastructure quote most liquid markets. A bot that just reacts to public prices faster than you can click is still slower than them.
- Fees and spreads decide whether a strategy works. A strategy that looks profitable on midpoint prices often loses money once you pay the spread and the taker fee on every fill.
- Live sports markets move fastest and thin out most. That’s where bots seem most useful, and also where slippage hurts most.
- Test with tiny sizes first. Run new logic on the smallest order sizes for at least a few days before scaling up.
Polymarket API Security Checklist
- Never put a private key in code you share or commit to GitHub. Use environment variables or a secrets manager.
- Be wary of free “Polymarket bot” repos. Some open-source bots ask for your private key or seed phrase. Read every line before running one, and never paste a seed phrase anywhere.
- Use a dedicated wallet or account for automated trading, funded only with what the bot needs.
- Rotate or delete keys you’re not using. Both platforms let you manage active credentials.
Want to compare Polymarket with other platforms before building? See our guide to the best sports prediction markets, check where prediction markets are legal in your state, or the best overall prediction market apps.
Polymarket API FAQ
It’s a set of REST and WebSocket APIs for reading Polymarket market data and trading programmatically. The international version includes the Gamma, CLOB, Data, Relayer and Bridge APIs plus live WebSockets. Polymarket US has its own separate API.
Yes, two of them. The international API is documented at docs.polymarket.com, and Polymarket US, the CFTC-regulated platform for U.S. users, has its own at docs.polymarket.us.
Yes. Market data is free, and there’s no paid tier. You only pay normal trading fees when you trade.
On Polymarket US, verify your identity in the app, then create a Key ID and Secret Key at polymarket.us/developer. On the international platform, you generate credentials by signing a message with your wallet and calling the create or derive endpoint.
Send GET requests to gamma-api.polymarket.com/markets or /events, filtering with parameters like closed, active, limit or tag_slug. No key is needed. Use the token IDs it returns to read order books and place orders on the CLOB API.
Yes, using the Polymarket US API with your own verified account. The international API is close-only for U.S. users, so you can’t open new positions through it, and using a VPN to get around that violates its terms.
