Meta description: Polymarket API deep dive covering Polymarket API docs, Polymarket API rate limits, Polymarket US API constraints, Gamma API, Data API, WebSocket usage, and how Codex standardizes trading‑grade prediction market feeds.
Polymarket API Deep Dive: Gamma, Data, WebSocket & Analytics (with Codex)
Polymarket has become the leading on‑chain prediction market, and its APIs now power everything from trading bots to consumer dashboards.
At the same time, the API surface is fragmented: Gamma, Data, CLOB, WebSockets, and trading endpoints all have different jobs, auth flows, and rate limits.
This guide is a practical, authoritative reference for product and engineering teams.
We’ll cover:
- How the Polymarket API ecosystem is structured
- Polymarket API docs links, including Gamma, Data, WebSocket, and trading
- Polymarket US API constraints and geoblocking
- Polymarket API rate limits and how to handle them
- How to standardize Polymarket data (market‑first vs token‑first schemas)
- How Codex abstracts Polymarket and other prediction markets into one trading‑grade API layer
- FAQ answers to common integration questions
All time‑sensitive numbers and limits below use snapshot date: 2026‑08‑28 and can change; always double‑check the official docs.
Table of Contents
- Polymarket API Ecosystem Overview
- Polymarket Gamma API: Discovery & Analytics
- Polymarket Data API: Accounts, Trades & Positions
- Polymarket WebSocket API & CLOB Market Data
- Polymarket US API Constraints & Geoblocking
- Polymarket API Rate Limits: What You Need to Design For
- Rate‑Limit Handling Strategies That Actually Work
- Standardizing Polymarket Data: Market‑First vs Token‑First
- Third‑Party Prediction Market API Providers Compared
- How Codex Exposes Trading‑Grade Prediction Feeds
- Polymarket API Docs — Example Requests
- FAQ: Common Polymarket API Questions
Polymarket API Ecosystem Overview
Polymarket’s API stack is modular. Each surface has a distinct responsibility, and understanding that separation is key to a robust integration.
According to the official Polymarket API docs (checked 2026‑08‑28):
- Gamma API — market discovery, metadata, events, categories, and search.
- Docs: https://docs.polymarket.com/api-reference/predictions/overview
- Data API — historical account and market activity: trades, positions, analytics.
- Docs: https://docs.polymarket.com/market-data/public-analytics
- CLOB Market Data API — live prices and order books for outcome tokens.
- Docs: https://docs.polymarket.com/api-reference/market-data/get-order-book
- WebSocket APIs — real‑time streams (markets, sports, RTDS, user streams).
- Docs: https://docs.polymarket.com/market-data/realtime-data
- Trading API — order placement, cancellation, and account actions.
- Docs: https://docs.polymarket.com/api-reference/trading
Polymarket also documents where to use third‑party on‑chain analytics providers, including Goldsky, Dune, and Allium for deeper historical data.
- Docs: https://docs.polymarket.com/resources/blockchain-data
Polymarket Gamma API: Discovery & Analytics
The Gamma API is Polymarket’s discovery and metadata layer. It’s your first stop to find markets, events, categories, and basic analytics.
Key roles (per Gamma API docs, checked 2026‑08‑28):
- List markets and events
- Filter by category (e.g., Sports, Finance, Politics)
- Retrieve market metadata: title, slug,
conditionId, outcome tokens, fees - Support search (
/public-search) across titles and descriptions
Representative endpoints and rate limits (snapshot 2026‑08‑28):
- Base path: documented at https://docs.polymarket.com/api-reference/predictions/overview
/events— list events/markets— list markets/markets + /events— joint listings/public-search— search markets
Polymarket’s Gamma API rate limits (from https://docs.polymarket.com/api-reference/rate-limits, checked 2026‑08‑28) are:
- Gamma total: 4,000 req / 10s
/events: 500 req / 10s/markets: 300 req / 10s/markets + /events listing: 900 req / 10s/public-search: 350 req / 10s
Public vs authenticated access
Polymarket’s docs note that public market data is available without credentials, while trading flows require authentication.
For Gamma:
- Public endpoints: market discovery (
/events,/markets,/public-search) - Auth scheme: typically none for public reads; check docs if Polymarket introduces API keys for heavy usage.
A minimal Gamma response includes fields like:
id(market identifier)conditionIdslugtitlecategory- outcome token IDs
- fees, tick size, status
Official market details docs: https://docs.polymarket.com/market-data/market-details
Polymarket Data API: Accounts, Trades & Positions
The Data API focuses on historical activity: trades, positions, closed positions, and analytics.
Per Data API docs (checked 2026‑08‑28):
- Docs: https://docs.polymarket.com/market-data/public-analytics
You’ll use the Data API to:
- Retrieve trade history for a market or user
- Query open and closed positions
- Build P&L dashboards or trader leaderboards
Key endpoint families:
/trades— historical trades for markets/users/positions— open positions/closed-positions— closed positions
Polymarket Data API rate limits (from https://docs.polymarket.com/api-reference/rate-limits, snapshot 2026‑08‑28):
- Data API total: 1,000 req / 10s
/trades: 200 req / 10s/positions: 150 req / 10s/closed-positions: 150 req / 10s
Public vs authenticated access
Polymarket’s docs describe public analytics endpoints that can be called without trading auth.
Fields in public analytics responses include (per docs, checked 2026‑08‑28):
side(buy/sell)conditionIdsizepricetimestamptitleslugoutcomewallettokenId
Docs: https://docs.polymarket.com/market-data/public-analytics
Trading or user‑specific endpoints may require authenticated flows (see Trading API section below).
Polymarket WebSocket API & CLOB Market Data
For trading‑grade apps, polling REST endpoints is not enough. Polymarket’s WebSocket API and CLOB market data endpoints provide real‑time order books and prices.
Per WebSocket docs (checked 2026‑08‑28):
- Docs: https://docs.polymarket.com/market-data/realtime-data
Polymarket offers:
- Market streams — real‑time updates on prices and trades
- Sports streams — specialized feeds for sports markets
- RTDS streams — real‑time data service streams
- Authenticated user streams — account‑level updates
On the REST side, the CLOB market data API includes:
/book— order book for a single outcome token/books— multiple books/price— current price for a single token/prices,/midpoints— batch price data/prices-history— historical prices
Docs: https://docs.polymarket.com/api-reference/market-data/get-order-book
Polymarket explicitly frames prices as probabilities emerging from a CLOB (central limit order book), rather than fixed odds.
Docs: https://docs.polymarket.com/concepts/prices-orderbook
CLOB market data rate limits
From the official rate limit docs (snapshot 2026‑08‑28):
/bookand/price: 1,500 req / 10s/books,/prices,/midpoints: 500 req / 10s/prices-history: 1,000 req / 10s
Docs: https://docs.polymarket.com/api-reference/rate-limits
Auth for market data vs trading
- Market data (REST + WebSocket): largely public for read‑only access.
- Trading: authenticated, with per‑signer rate limiting.
Trading API and rate limit change docs (checked 2026‑08‑28):
- Trading rate limits overview: https://docs.polymarket.com/api-reference/trading-rate-limits
- Trading API reference: https://docs.polymarket.com/api-reference/trading
Polymarket announced that starting 2026‑07‑24, CLOB order/cancel limiting would run in warning mode for two weeks, returning Poly-RateLimit-Warning: true on requests that would later be rejected (docs snapshot 2026‑08‑28).
Docs: https://docs.polymarket.com/api-reference/trading-rate-limits
Polymarket US API Constraints & Geoblocking
Regulatory constraints drive a lot of Polymarket’s API behavior, especially for US users.
Per the Geoblock API docs (checked 2026‑08‑28):
- Docs: https://docs.polymarket.com/api-reference/geoblock
Key points:
- The United States is classified as “close‑only” on both frontend and API.
- Some jurisdictions are blocked completely, others have frontend‑only close restrictions.
- The geoblock endpoint is intended to gate order placement, ensuring trading flows respect jurisdiction rules.
When integrating Polymarket for a global audience, product and engineering teams must:
- Call the geoblock APIs before enabling order placement.
- Implement jurisdiction‑aware UX (e.g., show "close‑only" for US accounts).
- Respect Polymarket’s constraints even if using a proxy or shared backend.
Docs: https://docs.polymarket.com/api-reference/geoblock
Polymarket API Rate Limits: What You Need to Design For
Polymarket publishes explicit rate limits for each surface.
From the Rate Limits docs (snapshot 2026‑08‑28):
- General: 15,000 req / 10s overall ceiling
- Gamma API: 4,000 req / 10s total
- Data API: 1,000 req / 10s total
- CLOB market data: see section above
Docs: https://docs.polymarket.com/api-reference/rate-limits
Trading CLOB order/cancel flows additionally use per‑signer token‑bucket limits (warning mode as of 2026‑07‑24, per docs).
Docs: https://docs.polymarket.com/api-reference/trading-rate-limits
These limits matter for:
- Bot operators issuing high‑frequency orders
- High‑traffic consumer apps behind shared infrastructure
- Analytics platforms running bulk queries

Rate‑Limit Handling Strategies That Actually Work
To build resilient integrations, treat polymarket api rate limits as a first‑class design constraint.
Below are reproducible patterns that engineering teams can implement.
1. Exponential backoff with jitter
When you receive HTTP 429 or rate‑limit headers:
- Parse
Retry-Afterif present. - Apply exponential backoff with random jitter.
Pseudocode:
function callWithBackoff(requestFn):
baseDelayMs = 200
maxDelayMs = 5000
attempt = 0
while true:
response = requestFn()
if response.status != 429:
return response
retryAfter = response.headers['Retry-After']
if retryAfter:
sleep(retryAfter * 1000)
else:
delay = min(maxDelayMs, baseDelayMs * (2 ^ attempt))
jitter = random(0, 0.3 * delay)
sleep(delay + jitter)
attempt += 1
2. Respect Polymarket’s warning headers
For trading requests, Polymarket may return Poly-RateLimit-Warning: true before actually rejecting.
Design your client to:
- Detect this header.
- Gradually reduce per‑signer order frequency.
- Log warnings for ops visibility.
Docs: https://docs.polymarket.com/api-reference/trading-rate-limits
3. Conditional caching and ETags
For read‑heavy endpoints (Gamma, Data, market data):
- Use HTTP caching where supported.
- If Polymarket supplies
ETag/Last-Modifiedheaders, send conditional requests (If-None-Match,If-Modified-Since).
This reduces:
- Duplicate
GET /marketscalls on unchanged data. - Pressure on
/prices-historywhen charts are already cached.
4. Batching requests
Polymarket exposes batch endpoints such as /books, /prices, /midpoints.
Prefer:
- One
GET /prices?tokenIds=...over many individual/pricecalls. - One
GET /books?tokenIds=...over multiple/bookcalls.
5. Client concurrency planning
Set per‑service concurrency caps based on rate limits.
Example for CLOB data (snapshot 2026‑08‑28):
/booklimit: 1,500 req / 10s- Safe app concurrency: 100–150 parallel requests if you batch aggressively
Algorithm:
- Define a global token bucket per endpoint group.
- Each request consumes 1 token.
- Refill tokens according to documented limits (e.g., 150 tokens per second for 1,500/10s).
bucketCapacity = 1500
refillRatePerSecond = 150
tokens = bucketCapacity
lastRefillTs = now()
function acquireToken():
nowTs = now()
elapsed = nowTs - lastRefillTs
tokens = min(bucketCapacity, tokens + elapsed * refillRatePerSecond)
lastRefillTs = nowTs
if tokens >= 1:
tokens -= 1
return true
else:
return false
Use this at your HTTP client layer to smooth bursts.
Standardizing Polymarket Data: Market‑First vs Token‑First
Polymarket’s own docs describe the market object as the core unit for integrations, encapsulating the question, outcomes, state, and fields needed to read prices or trade.
Docs: https://docs.polymarket.com/market-data/market-details (checked 2026‑08‑28)
However, for pricing and cross‑venue normalization, a token‑first view can be cleaner.
Per Polymarket’s concepts docs, the hierarchy is:
- Event → Market → Outcome token
Docs: https://docs.polymarket.com/concepts/markets-events
Below are sample normalized schemas you can adopt.
Market‑first normalized schema (JSON example)
{
"marketId": "12345",
"conditionId": "0xabc-condition",
"questionId": "q-67890",
"slug": "will-btc-close-above-100k-2026",
"title": "Will BTC close above $100k by end of 2026?",
"category": "Crypto",
"status": "open", // open, closed, resolved
"enableOrderBook": true,
"tickSize": 0.01,
"minOrderSize": 1.0,
"feeRate": 0.02,
"liquidity": 150000.0,
"event": {
"eventId": "evt-555",
"eventTitle": "2026 BTC price",
"startTime": "2026-01-01T00:00:00Z",
"endTime": "2026-12-31T23:59:59Z"
},
"outcomes": [
{
"tokenId": "0xoutcome-yes",
"label": "Yes",
"symbol": "BTC100K-YES",
"decimals": 18,
"currentPrice": 0.62,
"lastTradePrice": 0.61,
"volume24h": 25000.0
},
{
"tokenId": "0xoutcome-no",
"label": "No",
"symbol": "BTC100K-NO",
"decimals": 18,
"currentPrice": 0.38,
"lastTradePrice": 0.39,
"volume24h": 21000.0
}
]
}
This schema:
- Centers on the market and condition ID.
- Includes event metadata for grouping.
- Adds enriched fields (current price, last trade, volume) that you can compute or fetch from market data APIs.
Token‑first normalized schema (JSON example)
For cross‑venue analytics (Polymarket, Kalshi, Gemini, etc.), a token‑first schema can simplify time series and portfolio views.
{
"tokenId": "0xoutcome-yes",
"protocol": "polymarket",
"venue": "polymarket-global",
"conditionId": "0xabc-condition",
"marketId": "12345",
"questionId": "q-67890",
"slug": "will-btc-close-above-100k-2026",
"outcomeLabel": "Yes",
"symbol": "BTC100K-YES",
"category": "Crypto",
"status": "open",
"price": 0.62,
"midpoint": 0.615,
"orderBook": {
"bids": [[0.62, 100], [0.61, 200]],
"asks": [[0.63, 150], [0.64, 300]]
},
"metrics": {
"volume24h": 25000.0,
"openInterest": 120000.0,
"uniqueTraders24h": 420
},
"timestamps": {
"createdAt": "2026-02-01T12:00:00Z",
"lastUpdated": "2026-08-28T10:30:00Z"
}
}
This schema:
- Keys off
tokenIdfor pricing and book lookups. - Still links back to market and condition IDs.
- Adds venue metadata, which is critical when you normalize across platforms.
Third‑party providers like Allium explicitly build crosschain schemas with shared fields (project, protocol, category, status, trade size, fees, market identifiers) to support venue comparisons.
Docs: https://docs.allium.so/historical-data/predictions/crosschain/markets (checked 2026‑08‑28)
Third‑Party Prediction Market API Providers Compared
Polymarket’s docs recommend several third‑party providers for on‑chain analytics and historical data.
Docs: https://docs.polymarket.com/resources/blockchain-data (checked 2026‑08‑28)
Below is a simplified comparison table for common prediction‑market data providers.
| Provider | Coverage (snapshot 2026‑08‑28) | Features | Pricing model | Latency profile | Example endpoints |
|----------|---------------------------------------------------------------------------|----------------------------------------------------|----------------------------------|----------------------------------|----------------------------------------------------|
| Codex | Polymarket, Kalshi (beta), other venues; 80+ chains; 70M+ tokens; 700M+ wallets | Unified token + prediction data, charts, holders | Commercial; volume‑ & feature‑based | Trading‑grade, sub‑second | filterPredictionMarkets, filterPredictionEvents |
| Goldsky | Polymarket v2 datasets via Turbo Pipelines | On‑chain tables, indexing, ETL | Usage‑based infra pricing | Near‑real‑time, pipeline based | Polymarket Turbo dataset API |
| Dune | Polymarket curated tables (markets, trades, OHLCV, positions, prices) | SQL analytics, dashboards, hourly refresh | Freemium + commercial tiers | Hourly refresh (docs) | prediction_markets.polymarket_trades tables |
| Allium | Crosschain prediction markets (Polymarket, Polymarket US, Kalshi, Gemini, Solana venues) | Normalized cross‑venue schema, historical data | Enterprise data platform | Batch; optimized for analytics | /predictions/crosschain/markets |
Key documented behaviors:
- Goldsky: April 28, 2026 contract migration means public subgraphs may be incomplete; v2 Turbo Pipelines are recommended.
- Docs: https://docs.goldsky.com/chains/polymarket (checked 2026‑08‑28)
- Dune: Polymarket tables are curated and typically refreshed hourly.
- Docs: https://docs.dune.com/data-catalog/curated/prediction-markets/polymarket/overview
- Allium: Crosschain schema focuses on shared fields for venue comparison.
- Docs: https://docs.allium.so/historical-data/predictions/crosschain/markets
Compared with these, Codex is positioned as a unified, trading‑grade API layer rather than raw tables or analytics SQL.
How Codex Exposes Trading‑Grade Prediction Feeds
Codex is a specialized blockchain data infrastructure provider that ingests and enriches raw blockchain data across 80+ networks and 700M+ wallets, indexing thousands of transactions per second.
For prediction markets, Codex:
- Normalizes Polymarket and other venues into a unified schema.
- Exposes data via an all‑in‑one GraphQL‑style API.
- Focuses on trading‑ready feeds: prices as probabilities, order books, charts, aggregated metrics.
Key capabilities for prediction market builders (per Codex docs, checked 2026‑08‑28):
- Real‑time and historical prices (USD and native)
- Trading‑ready chart data (OHLC, candles, volume)
- Aggregated metrics: liquidity, volume, unique wallets
- Trader analytics: positions, P&L, activity across venues
- Dedicated prediction market endpoints (in beta):
filterPredictionEventsfilterPredictionMarkets- Trader stats endpoints
Docs: https://docs.codex.io/prediction-markets
Instead of:
- Running your own Polymarket indexers
- Maintaining custom ETL pipelines and RPC nodes
You can:
- Plug Codex’s API into your trading UI or analytics app.
- Use Codex’s normalized schemas (similar to the market‑first/token‑first structures above).
- Rely on sub‑second latencies for trading‑adjacent experiences.
Codex already powers leading apps including Coinbase, TradingView, Uniswap, Magic Eden, Rainbow, MoonPay, Farcaster, and pump.fun, which speaks to its infrastructure‑grade reliability.
More at: https://www.codex.io/?utm_source=openai
Polymarket API Docs — Example Requests
This section provides concrete examples that match Polymarket API docs intent and can be adapted directly in your integration.
Example 1: Gamma API — list markets
Public request (no auth):
GET https://api.polymarket.com/gamma/markets?status=open&category=Sports HTTP/1.1
Accept: application/json
Sample response (simplified):
{
"markets": [
{
"id": "98765",
"conditionId": "0xcond-sports-1",
"slug": "will-team-a-win-championship",
"title": "Will Team A win the championship?",
"category": "Sports",
"status": "open",
"enableOrderBook": true,
"tickSize": 0.01,
"minOrderSize": 1,
"fees": 0.02,
"outcomeTokens": ["0xtoken-yes", "0xtoken-no"]
}
]
}
Refer to the official Gamma docs for exact paths and parameters: https://docs.polymarket.com/api-reference/predictions/overview
Example 2: Data API — trades for a market
GET https://api.polymarket.com/data/trades?conditionId=0xcond-sports-1 HTTP/1.1
Accept: application/json
Sample response (simplified):
{
"trades": [
{
"side": "buy",
"conditionId": "0xcond-sports-1",
"size": 100,
"price": 0.55,
"timestamp": "2026-08-28T09:45:00Z",
"title": "Will Team A win the championship?",
"slug": "will-team-a-win-championship",
"outcome": "Yes",
"wallet": "0xwallet-123",
"tokenId": "0xtoken-yes"
}
]
}
Fields and filters are documented here: https://docs.polymarket.com/market-data/public-analytics
Example 3: CLOB Market Data API — order book
GET https://api.polymarket.com/market-data/book?tokenId=0xtoken-yes HTTP/1.1
Accept: application/json
Sample response (simplified):
{
"tokenId": "0xtoken-yes",
"tick_size": 0.01,
"min_order_size": 1,
"last_trade_price": 0.56,
"bids": [[0.56, 200], [0.55, 300]],
"asks": [[0.57, 150], [0.58, 250]],
"hash": "0xbookhash"
}
Docs: https://docs.polymarket.com/api-reference/market-data/get-order-book
Example 4: Polymarket WebSocket API — subscribe to market stream
While exact URLs and topics can change, a typical WebSocket subscribe flow looks like:
const ws = new WebSocket("wss://stream.polymarket.com/markets");
ws.onopen = () => {
const subscribeMessage = {
type: "subscribe",
channel: "market",
payload: {
conditionId: "0xcond-sports-1"
}
};
ws.send(JSON.stringify(subscribeMessage));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// data may include price updates, trades, order book deltas
};
Refer to official real‑time docs for concrete message schemas: https://docs.polymarket.com/market-data/realtime-data
FAQ: Common Polymarket API Questions
What are Polymarket US API constraints?
Per the Geoblock docs (snapshot 2026‑08‑28), the United States is classified as “close‑only” on both frontend and API.
That means:
- US users can close positions but cannot open new ones.
- Some jurisdictions are fully blocked; others are frontend‑only close restrictions.
- The geoblock endpoint is designed to gate order placement, and you must respect its responses in your app.
Docs: https://docs.polymarket.com/api-reference/geoblock
How to use the Polymarket WebSocket API?
To use the Polymarket WebSocket API:
- Connect to the documented WebSocket URL for markets, sports, or RTDS.
- Send a
subscribemessage with the appropriate channel and payload (e.g.,conditionIdor token ID). - Handle incoming messages for price updates, trades, or book deltas.
For authenticated user streams, you’ll typically need to include auth tokens or signed requests as documented.
Docs: https://docs.polymarket.com/market-data/realtime-data (checked 2026‑08‑28)
Where are Polymarket API docs?
Polymarket maintains a centralized docs site:
- Overview of prediction APIs and Gamma: https://docs.polymarket.com/api-reference/predictions/overview
- Market data (CLOB, books, prices): https://docs.polymarket.com/api-reference/market-data/get-order-book
- Data API & public analytics: https://docs.polymarket.com/market-data/public-analytics
- Trading API: https://docs.polymarket.com/api-reference/trading
- Trading rate limits: https://docs.polymarket.com/api-reference/trading-rate-limits
- Rate limits (Gamma, Data, CLOB): https://docs.polymarket.com/api-reference/rate-limits
- Geoblock & jurisdiction constraints: https://docs.polymarket.com/api-reference/geoblock
Always check these before deploying changes.
Are Polymarket prices real‑time?
Polymarket emphasizes real‑time data via WebSocket streams and low‑latency CLOB APIs.
Recent changelog entries document explicit latency improvements, e.g., reducing crypto taker delay from 250ms to 50ms as of 2026‑08‑17.
Docs: https://docs.polymarket.com/changelog/predictions (checked 2026‑08‑28)
For trading‑grade UX, combine:
- WebSocket streams for live updates.
- REST endpoints for initial state and backfill.
How does Codex fit into a Polymarket integration?
Codex provides a unified, enriched, low‑latency API for tokens and prediction markets.
Instead of directly stitching together Gamma, Data, CLOB, WebSockets, and third‑party analytics, you can:
- Use Codex’s prediction market endpoints (
filterPredictionMarkets,filterPredictionEvents, trader stats) for normalized data. - Pull charts, prices, liquidity, and wallet metrics from the same API used for your on‑chain tokens.
- Reduce infra complexity and focus on product features.
Docs: https://docs.codex.io/prediction-markets
If you’re building a trading UI, analytics dashboard, or consumer app that relies on Polymarket and other prediction markets, plugging into Codex’s trading‑grade data layer can save months of engineering and give you one consistent, reliable source of truth.
