Skip to main content

​
Markets

Discover and browse Polymarket prediction markets with live pricing data.

​
List Markets

GET /v1/markets
Returns markets with attached live prices from Polymarket’s CLOB.

​
Query Parameters

ParameterTypeDefaultDescription
limitint50Max results (1–200)
offsetint0Pagination offset
hot_onlyboolfalseOnly high-volume markets
active_onlybool—PM-shape alias: when true, only return markets where active=true AND closed=false.
categorystring—Filter to a single category (e.g. crypto, sports, politics). Case-insensitive substring match against each market’s category, which is populated by the background poller (~5 min cadence) from the parent event’s tags. Use unquoted values: ?category=crypto, NOT ?category="crypto". Leading/trailing single or double quotes are stripped defensively for users pasting from Postman.
qstring—Free-text search over question and slug (case-insensitive substring). Empty string is ignored.
envelopeboolfalseWhen true, wrap the response in a PM-shape {data, next_cursor} envelope (recommended for py-clob-client / other PM-ported SDKs). Default false returns a bare array for back-compat.
sort is not supported — the underlying list is volume-ordered server-side. For domain-specific ordering, fetch a wide page (limit=200) and sort client-side.

​
Examples

# Bare-array (back-compat default)
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets?hot_only=true&limit=10"

# PM-shape envelope (recommended for PM-ported SDKs)
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets?category=crypto&envelope=true&limit=10"

# Search by keyword (matches against question OR slug, case-insensitive)
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets?q=trump&limit=5"

​
Response

[
  {
    "condition_id": "0x1a2b3c...",
    "slug": "will-bitcoin-reach-100k-by-2026",
    "question": "Will Bitcoin reach $100K by end of 2026?",
    "outcomes": ["Yes", "No"],
    "active": true,
    "closed": false,
    "is_hot": true,
    "image_url": "https://polymarket-upload.s3.us-east-2.amazonaws.com/...",
    "category": "crypto",
    "clob_token_ids": [
      "71321234567890123456789012345678901234567890",
      "71321234567890123456789012345678901234567891"
    ],
    "volume_24h": "125000.50",
    "last_price": "0.65",
    "live_price": {
      "buy": "0.65",
      "sell": "0.35",
      "volume": "125000.50",
      "outcomes": [
        {"label": "Yes", "price": "0.65", "token_id": "71321..."},
        {"label": "No", "price": "0.35", "token_id": "71322..."}
      ],
      "updated_at": "2026-02-06T12:00:45Z",
      "source": "gamma_poller"
    }
  }
]

​
Field reference

FieldTypeDescription
condition_idstringOn-chain market identifier. Pass to GET /v1/markets/{condition_id} for full detail.
slugstring | nullURL-friendly market identifier (PM canonical name).
questionstring | nullHuman-readable market question.
outcomesstring[] | nullOutcome labels — typically ["Yes", "No"]; categorical markets may list more.
categorystring | nullCanonical category slug (crypto, sports, politics, general, …). Use ?category=X to filter.
clob_token_idsstring[] | nullCLOB asset ids ordered [yes_id, no_id]. Pass either to GET /v1/clob/book/{token_id} for the L2 order book. null for archived markets with no tracked outcomes.
volume_24hstring | nullRolling 24-hour volume in USD (stringified for precision). null means “no data yet” (poller has not observed this market); "0" means real zero.
last_pricestring | nullLast trade price for the YES token (0.0–1.0 implied probability, stringified). null until the poller catches up.
live_priceLivePrice | nullReal-time best-bid / best-ask snapshot — see String Numerics.
Cache cadence: volume_24h, last_price, and category are populated by the background poller that scans Polymarket’s catalog on a ~5 minute cycle. Newly-discovered markets surface immediately with these fields as null and gain real values on the next poll pass. Treat null as “data pending” rather than “missing market”.
best_bid / best_ask / spread / last_trade price fields aren’t returned on the list endpoint today. Use GET /v1/spread?token_id=... and GET /v1/midpoint?token_id=... for top-of-book / mid. The detail endpoint GET /v1/markets/{condition_id} does return richer fields (event_group_id, event_title, end_date, resolved_outcome, archived, archived_at) plus the list-item shape.
All numeric values (buy, sell, price, volume, volume_24h, last_price) are strings for floating-point precision safety. See String Numerics.

​
Order Book Lookup Recipe

Combine the list response with GET /v1/clob/book/{token_id} to render an L2 order book in two requests: 
# Step 1: get the clob_token_ids for a market
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets?q=bitcoin&limit=1" | jq '.[0].clob_token_ids'
# → ["71321...", "71322..."]   # [yes_id, no_id]

# Step 2: fetch the YES book (clob_token_ids[0])
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/clob/book/71321..."
Convention: clob_token_ids[0] is the YES outcome, clob_token_ids[1] is NO. Pass either to GET /v1/clob/book/{token_id} for that side’s order book. The IDs are stable for the lifetime of the market.
GET /v1/clob/book/{token_id} (path form) and GET /v1/book?token_id=... (query-string form) return the same OrderBookSnapshot shape. Use whichever matches your SDK’s routing convention — both are first-class endpoints.

​
Get Market Detail

GET /v1/markets/{market_id}
Returns full market detail with an optional order book snapshot.

​
Query Parameters

ParameterTypeDefaultDescription
include_bookboolfalseInclude CLOB order book snapshot
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets/0x1a2b3c?include_book=true"
The response is the same as a list item, plus an optional order_book field when include_book=true, plus the following Polymarket-shape parity fields that py-clob-client SDKs read by name:
FieldTypeDescription
tokensMarketToken[] | nullPM-shape per-outcome token list — the canonical Polymarket contract that py-clob-client reads (market["tokens"][i]["outcome"], .find(t => t.winner), etc). Each entry is an object: {token_id, outcome, price, winner} (see below). For the flat CLOB asset-id string list, use clob_token_ids instead.
question_idstringAlias of condition_id. PM SDKs read this key by name.
market_slugstring | nullAlias of slug. PM SDKs use market_slug; polysim has historically used slug. Both are exposed with the same value.
neg_riskboolNegative-risk routing flag. Polysim does not host negative-risk markets — always false.
Each tokens[] entry (a MarketToken) carries:
Sub-fieldTypeDescription
token_idstringCLOB outcome (asset) ID for this side.
outcomestringOutcome label, e.g. "Yes", "No", "Up", "Down".
pricenumberYES/NO probability for this outcome at response-build time.
winnerbooltrue only when the market is resolved AND this outcome is the settled winner. Never derived from price >= 0.99.
tokens (object list) and clob_token_ids (flat string list) are both returned and both stable for the market’s lifetime — pick whichever your SDK expects. tokens matches the Polymarket get_market() / getClobMarketInfo() shape; clob_token_ids is the PolySimulator convenience list ordered [yes_id, no_id].

​
Hot Markets

Markets with trading volume exceeding $5,000 are flagged as is_hot: true. Use hot_only=true to filter for actively traded markets — recommended for bots to ensure sufficient liquidity. 
# Only hot markets
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets?hot_only=true"

​
Next Steps