API
Discovering Polymarket markets via the /markets API
Building a market index starts with the /markets endpoint. This guide covers filtering by coin and timeframe, cursor-based pagination, slug resolution, and how to build a complete market catalog for analysis or trading.
What this guide covers
- GET /v1/markets returns up to 100 markets per page with cursor pagination
- Filter by coin, timeframe, and active/resolved status
- Each market has a unique slug used for books, prices, and metrics
- Resolved markets include the winning outcome in the response
The /markets endpoint
The /markets endpoint is the entry point for market discovery. It returns an array of market objects, each containing a slug, coin identifier, timeframe tag, resolution timestamp, and status.
Every market on Polymarket’s crypto Up/Down section has a corresponding entry here. The slug is the primary key you use to query order books, prices, and metrics on downstream endpoints.
The response includes metadata that helps you categorize markets: coin (btc, eth, sol, etc.), timeframe (5m, 1h, 1d), whether the market is currently active or already resolved, and the Unix timestamp at which it resolves.
Using this endpoint, you can build a complete catalog of every market Polymarket has ever run, organized by coin and timeframe. This catalog is the foundation for any batch analysis or trading system.
Filtering by coin, timeframe, and status
The most common filter is coin. Pass ?coin=btc to get only Bitcoin markets, ?coin=eth for Ethereum, and so on. The coin parameter is case-insensitive.
Timeframe filtering narrows results further. Use ?timeframe=5m for 5-minute markets, ?timeframe=1h for hourly, and ?timeframe=1d for daily. You can combine coin and timeframe filters to find, for example, all active BTC 5-minute markets.
Status filtering lets you choose between active and resolved markets. Use ?status=active to see markets that are currently accepting orders, or ?status=resolved to see markets that have already settled. By default, the endpoint returns both.
These filters can be combined freely. A query like ?coin=eth&timeframe=5m&status=resolved returns all resolved Ethereum 5-minute markets, which is useful for historical analysis.
| Parameter | Type | Description |
|---|---|---|
| coin | string | Filter by cryptocurrency (btc, eth, sol, etc.) |
| timeframe | string | Filter by market duration (5m, 1h, 1d) |
| status | string | Filter by status (active, resolved) |
| limit | integer | Number of results per page (max 100) |
| cursor | string | Pagination cursor from the previous response |
Cursor-based pagination
The API returns a maximum of 100 markets per request. For larger result sets, use cursor-based pagination. The response includes a next_cursor field when more results are available.
Pass the cursor value as ?cursor=<value> on your next request to get the following page. The cursor is opaque — don’t try to construct or decode it. Just pass it through as received.
Pagination continues until next_cursor is null or absent, which means you have reached the end of the result set. This approach is more reliable than offset-based pagination because it handles markets being added or removed between requests.
For a typical market index build, you will make 5 to 20 requests to capture all active and recently resolved markets. Cache the result and refresh periodically rather than paginating on every analysis run.
Building a market index
A market index is a local cache of all available markets, refreshed periodically. It is the first thing you build in any multi-market analysis or trading system.
Start by paginating through the full /markets response and storing each market’s slug, coin, timeframe, status, and resolution timestamp. Store this in a dictionary keyed by slug for O(1) lookups.
Refresh the index periodically — every 5 to 15 minutes for active trading, every hour for batch analysis. The /markets endpoint is lightweight and fast, so frequent refreshes do not burn many API requests.
With a market index in place, you can quickly find markets matching any criteria: all active BTC markets, all resolved ETH 1h markets in the last week, or markets resolving within the next 10 minutes.
Code examples
import requests
BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}
def build_market_index():
index = {}
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
r = requests.get(f"{BASE}/markets", headers=HEADERS, params=params)
r.raise_for_status()
page = r.json()
for m in page:
index[m["slug"]] = m
cursor = r.headers.get("X-Next-Cursor")
if not cursor:
break
return index
idx = build_market_index()
print(f"Indexed {len(idx)} markets")Free tier
The Starter plan is free, includes order books, prices, and metrics at 1-second resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.
Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.
FAQ
How many markets does Polymarket have?
Thousands. New 5-minute markets are created every 5 minutes, and longer timeframes (1h, 1d) are created regularly. The /markets endpoint is the authoritative source for the current count.
What is a slug?
A slug is a unique identifier for each market, like btc-updown-5m-1787486400. You use it to query order books, prices, and metrics. Slugs encode the coin, timeframe, and resolution timestamp.
How often should I refresh my market index?
For active trading, every 5 to 15 minutes. For batch analysis, every hour is fine. The /markets endpoint is lightweight and does not count heavily against your rate limit.
Can I get only resolved markets?
Yes. Pass ?status=resolved to see only markets that have already settled. Each resolved market includes the winning outcome, which is useful for historical analysis and backtesting.