polymarket.com APIpolymarket.com ↗
Access Polymarket events, order books, price history, leaderboards, and trade data via a structured API. 8 endpoints covering markets, odds, and traders.
curl -X GET 'https://api.parse.bot/scraper/20b82f08-34e9-4c9e-91cd-eb4ff7b7814f/search_markets?limit=3&query=bitcoin' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for prediction market events by keyword query. Returns matching events with their associated markets, current prices, and status.
| 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": "36173",
"slug": "when-will-bitcoin-hit-150k",
"image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png",
"title": "When will Bitcoin hit $150k?",
"active": true,
"closed": false,
"markets": [
{
"slug": "will-bitcoin-hit-150k-by-september-30",
"active": true,
"closed": true,
"spread": 0.001,
"best_ask": 0.001,
"best_bid": null,
"outcomes": [
"Yes",
"No"
],
"question": "Will Bitcoin hit $150k by September 30?",
"outcome_prices": [
"0",
"1"
],
"group_item_title": "by September 30, 2025",
"last_trade_price": 1
}
],
"end_date": null,
"neg_risk": false,
"start_date": "2025-08-07T16:32:57.401533Z"
}
],
"has_more": true,
"total_results": 3
},
"status": "success"
}
}About the polymarket.com 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.
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.
- 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 | 250 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.