API Docs
Response format
Every endpoint responds with { success, data, meta? } on success and { success: false, error, code } on failure. Error codes include BAD_REQUEST (400, invalid parameters), NOT_FOUND (404), UPSTREAM_UNAVAILABLE (503), UPSTREAM_ERROR, INVALID_RESPONSE and INTERNAL_ERROR (500).
Prices are strings between 0 and 1 in outcomePrices, ordered like outcomes (usually Yes, No). Successful responses are cached at the edge for the time listed below.
Endpoints
GET/api/markets
Active markets, as returned by the Polymarket Gamma API.
| Parameter | Type | Description |
|---|---|---|
| limit | integer 1–100 | Page size. Default 20. |
| offset | integer ≥ 0 | Number of markets to skip. Default 0. |
| active | true | false | Only active markets. Default true. |
| closed | true | false | Include closed markets. Default false. |
- Returns
- Market[] with meta { count, limit, offset }
- Cache
- 60s
- Example
/api/markets?limit=5
GET/api/events
Open events (groups of related markets) ordered by 24h volume.
| Parameter | Type | Description |
|---|---|---|
| limit | integer 1–50 | Page size. Default 20. |
| offset | integer ≥ 0 | Number of events to skip. Default 0. |
| tag | tag slug | Filter by a tag such as politics or crypto (a–z, 0–9, -). |
- Returns
- Event[] with meta { count, limit, offset, tag? }
- Cache
- 60s
- Example
/api/events?tag=crypto&limit=10
GET/api/search
Searches the questions and descriptions of the top 500 markets by 24h volume.
| Parameter | Type | Description |
|---|---|---|
| q | string, 2–200 chars | Required search text. |
| limit | integer 1–100 | Maximum results. Default 50. |
- Returns
- Market[] with meta { query, count }
- Cache
- 30s
- Example
/api/search?q=bitcoin
GET/api/trending
The 10 markets with the highest 24h volume.
- Returns
- Market[]
- Cache
- 60s
- Example
/api/trending
GET/api/market/[id]
A single market by its numeric id. Responds 404 if it does not exist.
| Parameter | Type | Description |
|---|---|---|
| id | path, digits | Market id, e.g. from /api/markets. |
- Returns
- Market
- Cache
- 30s
- Example
/api/market/12345
GET/api/orderbook/[tokenId]
Live CLOB orderbook for one outcome token, best prices first.
| Parameter | Type | Description |
|---|---|---|
| tokenId | path, digits | Outcome token id from a market’s clobTokenIds. |
- Returns
- { bids, asks, spread, midpoint, tokenId } where each level is { price, size }
- Cache
- 10s
- Example
/api/orderbook/<tokenId>
GET/api/health
Liveness check for this server. Never cached.
- Returns
- { status: "ok", timestamp, uptime }
- Cache
- none
- Example
/api/health