Polymarket API Endpoints Reference
All endpoints are public REST (GET), return JSON, and need no authentication.
Gamma API — gamma-api.polymarket.com
Search Markets
`
GET /public-search?q=QUERY
`
Response structure:
`json
{
"events": [
{
"id": "12345",
"title": "Event title",
"slug": "event-slug",
"volume": 1234567.89,
"markets": [
{
"question": "Will X happen?",
"outcomePrices": "[\"0.65\", \"0.35\"]",
"outcomes": "[\"Yes\", \"No\"]",
"clobTokenIds": "[\"TOKEN_YES\", \"TOKEN_NO\"]",
"conditionId": "0xabc...",
"volume": 500000
}
]
}
],
"pagination": {"hasMore": true, "totalResults": 100}
}
`
List Events
`
GET /events?limit=N&active=true&closed=false&order=volume&ascending=false
`
Parameters:
- -
limit— max results (default varies) - -
offset— pagination offset - -
active— true/false - -
closed— true/false - -
order— sort field:volume,createdAt,updatedAt - -
ascending— true/false - -
tag— filter by tag slug - -
slug— get specific event by slug - -
slug— get specific market by slug - -
market— the conditionId (hex string with 0x prefix) - -
interval— time range:all,1d,1w,1m,3m,6m,1y - -
fidelity— number of data points to return
Response: array of event objects. Each event includes a markets array.
Event fields: id, title, slug, description, volume, liquidity,
openInterest, active, closed, category, startDate, endDate,
markets (array of market objects).
List Markets
`
GET /markets?limit=N&active=true&closed=false&order=volume&ascending=false
`
Same filter parameters as events, plus:
Market fields: id, question, conditionId, slug, description,
outcomes, outcomePrices, volume, liquidity, active, closed,
marketType, clobTokenIds, endDate, category, createdAt.
Important: outcomePrices, outcomes, and clobTokenIds are JSON strings
(double-encoded). Parse with json.loads() in Python.
List Tags
`
GET /tags
`
Returns array of tag objects: id, label, slug.
Use the slug value when filtering events/markets by tag.
CLOB API — clob.polymarket.com
All CLOB price endpoints use token_id from the market's clobTokenIds field.
Index 0 = Yes outcome, Index 1 = No outcome.
Current Price
`
GET /price?token_id=TOKEN_ID&side=buy
`
Response: {"price": "0.650"}
The side parameter: buy or sell.
Midpoint Price
`
GET /midpoint?token_id=TOKEN_ID
`
Response: {"mid": "0.645"}
Spread
`
GET /spread?token_id=TOKEN_ID
`
Response: {"spread": "0.02"}
Orderbook
`
GET /book?token_id=TOKEN_ID
`
Response:
`json
{
"market": "condition_id",
"asset_id": "token_id",
"bids": [{"price": "0.64", "size": "500"}, ...],
"asks": [{"price": "0.66", "size": "300"}, ...],
"min_order_size": "5",
"tick_size": "0.01",
"last_trade_price": "0.65"
}
`
Bids and asks are sorted by price. Size is in shares (USDC-denominated).
Price History
`
GET /prices-history?market=CONDITION_ID&interval=INTERVAL&fidelity=N
`
Parameters:
Response:
`json
{
"history": [
{"t": 1709000000, "p": "0.55"},
{"t": 1709100000, "p": "0.58"}
]
}
`
t is Unix timestamp, p is price (probability).
Note: Very new markets may return empty history.
CLOB Markets List
`
GET /markets?limit=N
`
Response:
`json
{
"data": [
{
"condition_id": "0xabc...",
"question": "Will X?",
"tokens": [
{"token_id": "123...", "outcome": "Yes", "price": 0.65},
{"token_id": "456...", "outcome": "No", "price": 0.35}
],
"active": true,
"closed": false
}
],
"next_cursor": "cursor_string",
"limit": 100,
"count": 1000
}
`
Data API — data-api.polymarket.com
Recent Trades
`
GET /trades?limit=N
GET /trades?market=CONDITION_ID&limit=N
`
Trade fields: side (BUY/SELL), size, price, timestamp,
title, slug, outcome, transactionHash, conditionId.
Open Interest
`
GET /oi?market=CONDITION_ID
`
Field Cross-Reference
To go from a Gamma market to CLOB data:
1. Get market from Gamma: has clobTokenIds and conditionId
2. Parse clobTokenIds (JSON string): ["YES_TOKEN", "NO_TOKEN"]
3. Use YES_TOKEN with /price, /book, /midpoint, /spread
4. Use conditionId with /prices-history and Data API endpoints