221 lines
4.4 KiB
Markdown
221 lines
4.4 KiB
Markdown
# 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
|
|
|
|
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:
|
|
- `slug` — get specific market by slug
|
|
|
|
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:
|
|
- `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:
|
|
```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
|