Polymarket APIpolymarket.com ↗
Access Polymarket events, order books, price history, leaderboards, and trade data via a structured API. 8 endpoints covering markets, odds, and traders.
What is the Polymarket API?
This API exposes 8 endpoints for Polymarket prediction market data, covering everything from trending events and top markets to real-time order books and historical price series. The get_event_details endpoint returns full market metadata including CLOB token IDs, resolution criteria, volume, and liquidity — the identifiers you need to query order books and price history for any individual market outcome token.
curl -X GET 'https://api.parse.bot/scraper/20b82f08-34e9-4c9e-91cd-eb4ff7b7814f/search_markets?limit=5&query=bitcoin' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace polymarket-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.polymarket_api import (
Polymarket, EventSummary, Event, MarketOrder, PriceInterval,
LeaderboardSort, LeaderboardTimeframe,
)
client = Polymarket()
# Search for Bitcoin prediction markets
for event in client.events.search(query="bitcoin", limit=5):
print(event.title, event.slug, event.active)
# Get trending markets by 24h volume
for event in client.events.trending(limit=3):
print(event.title, event.volume_24hr, event.liquidity)
for market in event.markets:
print(" ", market.question, market.outcome_prices)
# Get top markets sorted by volume, filtered to active
for event in client.events.top(order=MarketOrder.VOLUME_24HR, active="true", limit=5):
print(event.title, event.slug)
# Fetch full event details from a summary
first_event = next(iter(client.events.search(query="bitcoin", limit=1)))
details = first_event.details()
print(details.title, details.volume, details.liquidity, details.markets_count)
# Access market-level CLOB token IDs from the detailed event
market = details.markets[0]
print(market.question, market.clob_token_ids, market.last_trade_price)
# Get order books for a token
token_id = market.clob_token_ids[0]
for book in client.orderbooks.list(token_ids=token_id):
print(book.asset_id, book.last_trade_price, book.tick_size)
for bid in book.bids:
print(" bid:", bid.price, bid.size)
# Get price history
for point in client.pricepoints.history(token_id=token_id, interval=PriceInterval.ONE_WEEK, fidelity="1440"):
print(point.t, point.p)
# Get last trade prices
for trade in client.trades.last(token_ids=token_id):
print(trade.token_id, trade.price, trade.side)
# Get leaderboard
lb = client.leaderboards.fetch(sort=LeaderboardSort.PROFIT, timeframe=LeaderboardTimeframe.MONTHLY)
print(lb.traders_count, lb.biggest_wins_count)
for trader in lb.traders:
print(trader.rank, trader.name, trader.profit_loss, trader.volume)
Full-text search over prediction market events by keyword. Returns matching events with their associated markets, current prices, and status. has_more indicates additional results exist beyond the returned set.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return per type. |
| queryrequired | string | Search keyword to find prediction market events. |
{
"type": "object",
"fields": {
"query": "string — the search keyword used",
"events": "array of event objects with nested markets, prices, and status",
"has_more": "boolean — whether more results are available",
"total_results": "integer — number of events returned"
},
"sample": {
"data": {
"query": "bitcoin",
"events": [
{
"id": "555627",
"slug": "bitcoin-above-on-june-10-2026",
"image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png",
"title": "Bitcoin above ___ on June 10?",
"active": true,
"closed": false,
"markets": [
{
"slug": "bitcoin-above-58k-on-june-10-2026",
"active": true,
"closed": false,
"spread": 0.002,
"best_ask": 0.98,
"best_bid": 0.978,
"outcomes": [
"Yes",
"No"
],
"question": "Will the price of Bitcoin be above $58,000 on June 10?",
"outcome_prices": [
"0.979",
"0.021"
],
"group_item_title": "58,000",
"last_trade_price": 0.979
}
],
"end_date": "2026-06-10T16:00:00Z",
"neg_risk": false,
"start_date": "2026-06-03T16:26:45.640718Z"
}
],
"has_more": true,
"total_results": 10
},
"status": "success"
}
}About the Polymarket API
Market Discovery
Three endpoints handle market discovery. search_markets accepts a query string and returns matching events with nested market objects, current prices, and a has_more flag for pagination awareness. get_trending_markets returns events sorted by 24-hour trading volume, with each event carrying yes/no price odds, liquidity, and category tags. get_top_markets adds sorting (volume24hr, volume, liquidity), filtering by active or closed status, category slug filtering, and offset-based pagination — making it the right entry point for building browsable market directories.
Market Detail and Token IDs
get_event_details takes an event slug (obtained from discovery endpoints) and returns the complete event record: id, title, description, volume, liquidity, markets_count, and a markets array where each entry includes CLOB token IDs. Those token IDs are the keys for all order book and price queries. The description field typically contains resolution criteria, which is useful for displaying settlement logic.
Order Book, Prices, and Trades
get_order_book accepts one or more comma-separated CLOB token IDs and returns an array of books, each containing bids, asks, tick_size, and last_trade_price. get_price_history takes a single token_id with an optional interval (1h, 6h, 1d, 1w, 1m) and fidelity (minutes between points), returning a history array of {t, p} pairs — unix timestamp and price. get_last_trade_prices returns the most recent trade price and side (BUY or SELL) for each requested token.
Leaderboard
get_leaderboard returns ranked trader data filterable by sort (profit or volume) and timeframe (today, weekly, monthly, all). Each entry in the traders array includes rank, wallet_address, name, profit_loss, and volume. A separate biggest_wins array surfaces the highest-profit individual trades for the period, with event_title and profit per entry.
The Polymarket API is a managed, monitored endpoint for polymarket.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when polymarket.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official polymarket.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a prediction market dashboard showing trending events with live yes/no odds from
get_trending_markets. - Chart probability over time for a specific outcome token using
get_price_historywith configurable fidelity intervals. - Display real-time bid/ask spreads and last trade prices for market tokens via
get_order_bookandget_last_trade_prices. - Filter and rank open markets by 24-hour volume or liquidity using
get_top_marketswithorderandactiveparams. - Show top traders by profit or volume for a given timeframe using the
tradersandbiggest_winsarrays fromget_leaderboard. - Resolve event slugs to CLOB token IDs with
get_event_detailsto wire up downstream order book and price queries. - Power a keyword search interface over prediction markets using
search_marketswithqueryandlimitparameters.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Polymarket have an official developer API?+
How do I get the token IDs needed for `get_order_book` and `get_price_history`?+
get_event_details with an event slug. Each object in the markets array includes clob_token_ids — typically two IDs per binary market (one for YES, one for NO). Pass those IDs as comma-separated values to get_order_book or individually to get_price_history.Does `get_price_history` cover the full lifetime of a market?+
interval parameter supports up to 1m (one month) of history with configurable fidelity down to per-minute granularity. Longer historical series going back to market inception are not currently exposed by this endpoint. You can fork the API on Parse and revise it to add an endpoint covering extended historical ranges.Does the API expose individual trade history or position data for a wallet address?+
What does the `biggest_wins` array in `get_leaderboard` contain?+
rank, username, event_title, and profit — representing the single highest-profit trades made by any user in the selected timeframe. It is separate from the traders array, which aggregates total profit or volume across all activity by a trader.