The Polymarket APIs at a glance
| API | Base URL | Use it for | Key needed? |
|---|---|---|---|
| Gamma | https://gamma-api.polymarket.com | Events, markets, slugs, outcomes, token IDs, fee settings, search | No |
| CLOB | https://clob.polymarket.com | Order books, prices, midpoints, price history; placing and cancelling orders | Only for trading |
| Data API | https://data-api.polymarket.com | Positions, trades and activity for a wallet (use the /v2 endpoints; v1 was retired on November 2, 2026) | No |
| Market WebSocket | wss://ws-subscriptions-clob.polymarket.com/ws/market | Live order book, price and market updates | No |
| User WebSocket | wss://ws-subscriptions-clob.polymarket.com/ws/user | Your own orders and fills | Yes |
| Live data (PolyBolt) | wss://ws-live-v2.polymarket.com/ws | Reference prices for crypto and equities (replaces the older RTDS price feed) | Yes, CLOB API credentials |
| RTDS (legacy) | wss://ws-live-data.polymarket.com | Comments; price topics have moved to PolyBolt | No |
The full list, including the Relayer and sports feeds, is in Polymarket's API overview.
Step 1: list markets with the Gamma API
Gamma is where a bot finds things to trade. GET /markets takes filters such as active, closed, limit and order; GET /events returns groups of related markets; GET /markets?slug=… fetches one market by its URL name.
"""List the most active open Polymarket markets. Public Gamma API, no key."""
import json
import urllib.request
GAMMA = "https://gamma-api.polymarket.com"
def get(url):
request = urllib.request.Request(url, headers={"User-Agent": "my-polymarket-bot/0.1"})
with urllib.request.urlopen(request, timeout=20) as response:
return json.load(response)
def trading_ids(market):
"""Token IDs to trade. Protocol V2 markets use positionIds instead."""
if market.get("version") == "v2":
return market["positionIds"]
return json.loads(market["clobTokenIds"]) # a JSON list stored as a string
markets = get(GAMMA + "/markets?active=true&closed=false&limit=5"
"&order=volume24hr&ascending=false")
for market in markets:
outcomes = json.loads(market["outcomes"]) # also JSON in a string
prices = json.loads(market["outcomePrices"])
fee = market.get("feeSchedule") or {}
print(market["slug"])
print(" ends", market["endDate"], "| 24h volume $%.0f" % market["volume24hr"],
"| taker fee rate", fee.get("rate", 0) if market.get("feesEnabled") else 0)
for name, price, token in zip(outcomes, prices, trading_ids(market)):
print(" %-12s %s token %s..." % (name, price, token[:14]))
Output on November 15, 2026 at 21:57 UTC (trimmed). The 49ers game was in progress, so its prices moved between runs:
nfl-sf-dal-2026-11-15
ends 2026-11-15T21:25:00Z | 24h volume $4577284 | taker fee rate 0.03
49ers 0.735 token 55797876453514...
Cowboys 0.265 token 11111644521510...
Three things to know about Gamma records:
outcomes,outcomePricesandclobTokenIdsare JSON lists stored as strings. Decode them withjson.loadsbefore use. This catches almost everyone once.- Each outcome has its own token ID. Order books, prices and orders are per token, not per market. A Yes/No market has two tokens.
- Each market carries its own fee settings in
feesEnabledandfeeSchedule. Use them instead of a category table; the fee guide explains why.
Step 2: read the order book and midpoint
The CLOB's public endpoints take a token ID. GET /book returns every price level on both sides; GET /midpoint, GET /price and GET /spread return single numbers; POST /books and POST /midpoints take many tokens at once and are kinder to rate limits.
"""Read one outcome's order book and midpoint from the public CLOB API."""
import json
import sys
import urllib.request
CLOB = "https://clob.polymarket.com"
GAMMA = "https://gamma-api.polymarket.com"
def get(url):
request = urllib.request.Request(url, headers={"User-Agent": "my-polymarket-bot/0.1"})
with urllib.request.urlopen(request, timeout=20) as response:
return json.load(response)
if len(sys.argv) > 1:
token = sys.argv[1]
else: # default: first outcome of the most active market
market = get(GAMMA + "/markets?active=true&closed=false&limit=1"
"&order=volume24hr&ascending=false")[0]
token = json.loads(market["clobTokenIds"])[0]
print("market:", market["slug"])
book = get(CLOB + "/book?token_id=" + token)
# Prices and sizes are strings. Do not rely on list order for the best level:
# pick the highest bid and the lowest ask explicitly.
bids = sorted(book["bids"], key=lambda level: float(level["price"]), reverse=True)
asks = sorted(book["asks"], key=lambda level: float(level["price"]))
print("best bid %s x %s | best ask %s x %s" % (
bids[0]["price"], bids[0]["size"], asks[0]["price"], asks[0]["size"]))
print("%d bid levels, %d ask levels, tick size %s" % (len(bids), len(asks), book["tick_size"]))
print("midpoint:", get(CLOB + "/midpoint?token_id=" + token)["mid"])
Output on November 15, 2026:
market: nfl-sf-dal-2026-11-15
best bid 0.62 x 30097.44 | best ask 0.63 x 78597.25
43 bid levels, 27 ask levels, tick size 0.01
midpoint: 0.625
- Prices and sizes are strings. Convert them before comparing;
"0.9" > "0.10"is true as text. - Do not assume the best level is first. In our tests bids came back lowest first and asks highest first, so the best prices were at the end of each list. Sorting explicitly, as the script does, works either way.
- Respect the tick size. Orders must be on the market's price grid, which can be 0.01 or finer.
- The midpoint is not a price you can trade at. Size and simulate against the bid and ask.
API keys and authentication
Trading on Polymarket International uses two layers, described in the authentication docs:
| Layer | How it works | Used for |
|---|---|---|
| L1 | Your wallet signs an EIP-712 message on Polygon (chain 137) | Proving you control the wallet, and creating or re-deriving API credentials |
| L2 | Requests are signed with HMAC-SHA256 using the API secret | Every private CLOB request: orders, cancels, your open orders and trades |
To get a Polymarket API key, sign the L1 message and call POST /auth/api-key (or GET /auth/derive-api-key to recover existing credentials). You get back three values: apiKey, secret and passphrase. Private requests then send POLY_ADDRESS, POLY_API_KEY, POLY_PASSPHRASE, POLY_TIMESTAMP and POLY_SIGNATURE headers. Placing an order needs both: L2 to authenticate the request and a wallet signature on the order itself.
The official SDK does all of this for you. Writing the signing yourself is only worth it if your language has no SDK. Keep the private key and the API secret out of your code and logs; the security guide covers how.
Rate limits
Polymarket's rate limits are per IP address and enforced by Cloudflare. Going over usually slows your requests down rather than rejecting them, which can be worse for a bot: it just gets late. Selected limits, all per 10 seconds:
| Endpoint | Limit |
|---|---|
Gamma, overall / /markets / /events | 4,000 / 300 / 500 |
CLOB /book, /price, /midpoint | 1,500 each |
CLOB /books, /prices, /midpoints (batch) | 500 each |
CLOB /prices-history | 1,000 |
Data API /v2 overall / /v2/trades / /v2/positions | 800 / 300 / 200 |
| API key endpoints | 100 |
Order and cancel requests also have limits per signer address that grow with 30-day volume: the standard tier allows 40 orders per second with bursts of 60, and 80 cancels per second with bursts of 120. Responses carry Poly-RateLimit-Remaining and Poly-RateLimit-Reset headers; read them rather than guessing. Polymarket introduced these limits in a warning mode in July 2026, with a Poly-RateLimit-Warning header on requests that would be rejected, and said it would announce live enforcement.
For anything that watches prices continuously, use the market WebSocket instead of polling.
Paper trading against the live book
Polymarket does not offer paper trading on its live markets, so test a strategy by running it against the real order book and recording what it would have done. This script buys at the real asks, sells at the real bids, walks down the book when your size is bigger than the best level, charges the market's own taker fee, and logs every decision to a CSV file. It never sends an order.
"""Paper-trade one Polymarket outcome against the live order book.
Reads public data only and never sends an order. Simulated buys fill at the
real asks and sells at the real bids, level by level, and pay the market's own
taker fee. Every decision is appended to paper_trades.csv.
python3 paper_trade.py [market-slug] [outcome-index]
"""
import csv
import json
import sys
import time
import urllib.request
from datetime import datetime, timezone
CLOB = "https://clob.polymarket.com"
GAMMA = "https://gamma-api.polymarket.com"
SECONDS = 10 # how often to check the book
ROUNDS = 6 # how many checks before stopping
SIZE = 50 # shares per simulated order
TAKE_PROFIT = 0.02 # sell when the bid is 2 cents above our average price
STOP_LOSS = 0.03 # sell when the bid is 3 cents below it
def get(url):
request = urllib.request.Request(url, headers={"User-Agent": "my-polymarket-bot/0.1"})
with urllib.request.urlopen(request, timeout=20) as response:
return json.load(response)
def fill(levels, shares, fee_rate):
"""Walk the book. Returns (shares filled, average price, total fee)."""
left, cost, fee = shares, 0.0, 0.0
for level in levels:
price, size = float(level["price"]), float(level["size"])
take = min(left, size)
cost += take * price
fee += take * fee_rate * price * (1 - price)
left -= take
if left <= 0:
break
done = shares - left
return done, (cost / done if done else None), round(fee, 5)
slug = sys.argv[1] if len(sys.argv) > 1 else None
outcome = int(sys.argv[2]) if len(sys.argv) > 2 else 0
if slug:
market = get(GAMMA + "/markets?slug=" + slug)[0]
else:
market = get(GAMMA + "/markets?active=true&closed=false&limit=1"
"&order=volume24hr&ascending=false")[0]
token = json.loads(market["clobTokenIds"])[outcome]
fee_rate = float((market.get("feeSchedule") or {}).get("rate", 0)) if market.get("feesEnabled") else 0.0
print("paper trading", market["slug"], "outcome", json.loads(market["outcomes"])[outcome],
"| taker fee rate", fee_rate)
shares, entry, cash, best_bid = 0.0, None, 0.0, None
with open("paper_trades.csv", "a", newline="") as log:
writer = csv.writer(log)
for round_number in range(ROUNDS):
book = get(CLOB + "/book?token_id=" + token)
bids = sorted(book["bids"], key=lambda l: float(l["price"]), reverse=True)
asks = sorted(book["asks"], key=lambda l: float(l["price"]))
if not bids or not asks:
print("empty book, skipping")
else:
best_bid, best_ask = float(bids[0]["price"]), float(asks[0]["price"])
action = "hold"
# Your strategy goes here. This demo buys once, then exits on a
# take-profit or stop-loss measured at the price it could sell at.
if shares == 0 and entry is None:
done, avg, fee = fill(asks, SIZE, fee_rate)
shares, entry, cash = done, avg, cash - done * avg - fee
action = "BUY %g @ %.4f fee %.5f" % (done, avg, fee)
elif shares and (best_bid >= entry + TAKE_PROFIT or best_bid <= entry - STOP_LOSS):
done, avg, fee = fill(bids, shares, fee_rate)
cash += done * avg - fee
action = "SELL %g @ %.4f fee %.5f" % (done, avg, fee)
shares -= done
now = datetime.now(timezone.utc).isoformat(timespec="seconds")
writer.writerow([now, market["slug"], outcome, best_bid, best_ask, action])
print(now, "bid %.3f ask %.3f" % (best_bid, best_ask), action)
if round_number < ROUNDS - 1:
time.sleep(SECONDS)
mark = shares * best_bid if shares and best_bid else 0.0
print("result: %g shares held, cash %+.2f, value at the bid %.2f, total %+.2f"
% (shares, cash, mark, cash + mark))
The script as published, run on November 15, 2026 with python3 paper_trade.py nfl-lac-bal-2026-11-17 1 (buying the Ravens in a game market with a 0.03 fee rate):
paper trading nfl-lac-bal-2026-11-17 outcome Ravens | taker fee rate 0.03
2026-11-15T22:11:31+00:00 bid 0.660 ask 0.670 BUY 50 @ 0.6700 fee 0.33165
2026-11-15T22:11:42+00:00 bid 0.660 ask 0.670 hold
2026-11-15T22:11:52+00:00 bid 0.660 ask 0.670 hold
2026-11-15T22:12:02+00:00 bid 0.660 ask 0.670 hold
2026-11-15T22:12:13+00:00 bid 0.660 ask 0.670 hold
2026-11-15T22:12:23+00:00 bid 0.660 ask 0.670 hold
result: 50 shares held, cash -33.83, value at the bid 33.00, total -0.83
Notice the result: the position is down 83 cents the moment it is opened, one cent of spread on 50 shares plus the fee. That is the hurdle every strategy has to clear. Replace the demo rule with yours, run it for weeks rather than minutes, and read the risk guide before switching to real orders.
Placing real orders with the official SDK
Polymarket's current Python SDK is polymarket-client (version 0.18.0 on November 15, 2026; it needs Python 3.11 or newer). It covers the CLOB, Gamma, the Data API, the Relayer and builder signing, and offers a PublicClient for data and a SecureClient for trading. TypeScript has the matching @polymarket/client.
py-clob-clientis deprecated. Most open-source bots and older tutorials still use it. Its last release predates Polymarket's April 2026 CLOB V2 upgrade, which changed the order format and collateral, so code built on it needs updating before it can trade. Polymarket's migration guide moves projects topolymarket-client.- Orders are limit orders on the CLOB. Fees are applied when an order matches; you do not set a fee in the order.
- Collateral is pUSD, a token on Polygon backed one-to-one by USDC. Deposits through Polymarket's bridge convert automatically.
- Check eligibility first.
GET https://polymarket.com/api/geoblocktells you whether your IP may place orders. See US vs International.
Start from the SDK's own examples in Polymarket's Python guide, and keep the paper-trading loop running beside your live bot so you can compare expected and actual fills.
What changes with Protocol V2 (from November 23, 2026)
Polymarket is moving new markets to Protocol V2, with new position tokens and contracts, in phases:
| Phase (Eastern time) | Markets |
|---|---|
| Monday, November 23, 8:30 AM | BNB, DOGE, HYPE, SOL, XRP and ZEC up/down (5 and 15 minutes); some temperature markets |
| Tuesday, November 24 | BTC and ETH up/down (5 minutes, 15 minutes, 4 hours); other crypto, weather, commodities, finance, minor sports |
| Tuesday, December 1 | Soccer, NFL and college football, basketball, tennis, esports, social counts |
Existing markets keep trading on their current contracts, and holdings are not converted. What a bot has to change:
- Choose the ID by the market's
version. V2 markets listpositionIds; older ones keepclobTokenIds. Thetrading_ids()helper in the first script already does this. - Approve the new exchange contract for pUSD (buys) and positions (sells). Approvals for the old contracts do not carry over; the SDK's approval setup handles it.
- Sign V2 orders with the new EIP-712 domain version. The current SDK does this automatically.
- Read resolution from Gamma's
resolutionStatusfor V2 markets.
When V2 markets go live, check that the market lists your bot reads actually return them, using the filters in Polymarket's current Gamma documentation, rather than assuming an empty result means nothing is listed.
Separately, Polymarket has announced CLOB query changes taking effect on December 14, 2026, including a required market filter on /data/orders. Check the changelog if your bot reads its own order history.
The Polymarket US API
If you are a US resident trading on Polymarket US, none of the International endpoints above apply. The Polymarket US API has a public part at https://gateway.polymarket.us (markets, events, order books, best bid and offer, price history; no key) and an authenticated part at https://api.polymarket.us for orders, positions and balances, plus WebSocket streams for markets and your account. Keys come from the developer portal after your account passes identity verification, and official Python and TypeScript SDKs handle signing. The general limit is 25 requests per second per IP. Details and the differences that matter for bots are in Polymarket US vs International.
Questions people ask
Does Polymarket have an API?
Yes. Polymarket International offers the Gamma, CLOB and Data APIs and WebSocket feeds; Polymarket US has its own Retail API. Both have official Python and TypeScript SDKs.
Is the Polymarket API free?
We found no charge for API access in Polymarket's documentation, and public market data needs no key. Trading fees apply to taker orders; see the fee guide.
Do I need an API key to get Polymarket prices?
No. Markets, order books, prices and price history are public. You need credentials only to place or manage orders and read your own account.
Where is the official Polymarket API documentation?
At docs.polymarket.com for International and docs.polymarket.us for Polymarket US. Both publish a machine-readable index at /llms.txt.
Can I build a Polymarket trading bot in Python?
Yes. Start with the three scripts on this page, then move to the official polymarket-client SDK for orders. The bot handbook covers which kinds of bot tend to work.
Published November 15, 2026, replacing our US API note and order book guide. Sources checked November 15, 2026: API overview and authentication, rate limits, trading rate limits, Protocol V2 migration, polymarket-client on PyPI, Polymarket US API.