Market Data

Get Market

Fetch a single market’s detail with live price.

If include_book is true, the response also includes a book key with the CLOB order-book snapshot (async, best-effort). (include_book=true bypasses the SSR cache wrapper since each book snapshot is volatile and would dirty the cached payload.)

P2.3 cache-hit DB-hold fix (sibling of P2.2 on auth.py): no db: Session = Depends(get_db) at signature level. The Redis cache-hit branch (the common case) returns without ever touching DB; only the cache-miss branch lazily acquires a session via _lazy_db_session(). This frees one pool slot per cache-hit request, multiplied by the entire request lifetime — same pattern as the P2.2 keystone fix.

PR (2026-05-17): wrapped in the SSR cache + single-flight helper. Under FE Next.js SSR fan-out (~30-60 parallel reads per render), every concurrent cache-cold request was doing its own DB lookup + response assembly. The wrapper coalesces them to ONE compute per (worker, condition_id, 15s window) — definitive fix for the pool-starvation failure class. See PR body for the full story.

GET

markets

{condition_id}

Get Market

curl --request GET \
  --url https://api.polysimulator.com/v1/markets/{condition_id} \
  --header 'X-API-Key: <api-key>'

{
  "condition_id": "<string>",
  "slug": "<string>",
  "question": "<string>",
  "outcomes": [
    "<string>"
  ],
  "active": true,
  "closed": false,
  "is_hot": false,
  "image_url": "<string>",
  "category": "<string>",
  "clob_token_ids": [
    "<string>"
  ],
  "volume_24h": "<string>",
  "last_price": "<string>",
  "live_price": {
    "buy": "<string>",
    "sell": "<string>",
    "volume": "<string>",
    "updated_at": "<string>",
    "source": "<string>",
    "outcomes": []
  },
  "event_group_id": "<string>",
  "event_title": "<string>",
  "end_date": "<string>",
  "resolved_outcome": "<string>",
  "archived": false,
  "archived_at": "<string>",
  "tokens": [
    {
      "token_id": "<string>",
      "outcome": "<string>",
      "price": 0,
      "winner": false
    }
  ],
  "question_id": "<string>",
  "market_slug": "<string>",
  "neg_risk": true
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

X-API-Key

string | null

Your PolySimulator API key

POLY_API_KEY

string | null

Polymarket-CLOB-compat alias for X-API-Key (underscore form). SDK clients ported from Polymarket can authenticate without changing header names. X-API-Key takes precedence when both are provided.

Poly-API-Key

string | null

PM-CLOB-compat dashed-form alias for X-API-Key. Same value semantics as POLY_API_KEY but with HTTP-conventional dash separators. Audit P1 (staging audit 2026-05-16 0817 PR #1296): the per-tier middleware accepts both spellings but the auth dependency originally only matched the underscore form — now both work end-to-end.

authorization

string | null

PM-CLOB-compat: Authorization: Bearer ps_live_... (or ps_test_...) is accepted as an alias for X-API-Key so py-clob-client and other ported SDKs authenticate without header name changes. Bearer JWTs are NOT accepted here — use the dashboard-auth endpoints for those.

Path Parameters

condition_id

string

required

Query Parameters

include_book

boolean

default:false

Include CLOB order book

Response

Successful Response

condition_id

string

required

slug

string | null

question

string | null

outcomes

string[] | null

active

boolean

default:true

closed

boolean

default:false

is_hot

boolean

default:false

image_url

string | null

category

string | null

clob_token_ids

string[] | null

CLOB token ids for this market's outcomes ([yes_id, no_id]). Pass to /v1/clob/book/{token_id} to fetch the L2 order book. May be null for archived markets with no tracked outcomes.

volume_24h

string | null

Rolling 24-hour volume from the poller cache (USD). Stringified for floating-point precision safety. null when the poller has not yet observed this market — distinct from "0" which means zero trades.

last_price

string | null

Last trade price for the YES token (0.0–1.0 implied probability). Stringified for precision. null when untracked; for the real-time top-of-book bid/ask use live_price.buy / live_price.sell.

live_price

LivePrice · object

Show child attributes

event_group_id

string | null

event_title

string | null

end_date

string | null

resolved_outcome

string | null

archived

boolean

default:false

archived_at

string | null

tokens

MarketToken · object[] | null

PM-shape per-outcome token list. Each entry carries {token_id, outcome, price, winner} — the documented Polymarket contract that py-clob-client reads. price is the YES/NO probability at response-build time; winner is True only when the market is resolved AND this outcome is the settled winner (NEVER derived from price >= 0.99). For the legacy CLOB asset-id string list use clob_token_ids.

Show child attributes

question_id

string | null

PM-shape: alias of condition_id (the on-chain market identifier). PM SDKs read this key by name; we surface the same value under both keys for cross-SDK compatibility.

market_slug

string | null

PM-shape: alias of slug. PM SDKs use market_slug; polysim has historically used slug. Both are exposed with the same value so SDKs that branch on either key work.

neg_risk

boolean | null

PM-shape: negative-risk routing flag. true when the market is part of a negative-risk auction (single-winner across many outcomes); false for standard binary. null if not classified — treat as false.

Get Market By SlugResolve a market by its slug for short-URL / SDK lookups. Tries Redis ``MARKET_SLUG_INDEX_PREFIX`` first, then the ``markets`` table, then the R2 archive — same chain the root ``/markets/by-slug`` handler uses, but typed and gated by ``X-API-Key`` on the v1 surface. Wrapped in a 60 s endpoint-level Redis cache (override via ``MARKET_BY_SLUG_CACHE_TTL_S``). Slug → condition_id mapping is stable; even closed markets stay reachable for the full TTL. Negative-404 caching: gated on ``MARKET_DETAIL_NEG_CACHE_TTL_S`` (default 0 = off; operator opt-in commonly 15 s) per the 2026-05-20 prod-wedge RCA — dead-slug 404 storms from FE SSR fan-out were stampeding the Gamma round-trip + archive lookup chain. Trade-off when enabled: a brand-new on-chain market surfaces up to the configured TTL late on this endpoint until the negative-cache entry expires. Default-off ships per the stability policy: operator flips to 15 in Dokploy stored env after a 4 h staging canary. PR-α (2026-05-06) — registered after the audit found the path was documented in ``api-beta-launch-plan.md`` but only existed at the root path (no ``/v1`` prefix), so SDK consumers calling ``/v1/markets/by-slug/...`` got 404. P2.3 cache-hit DB-hold fix: no ``db: Session = Depends(get_db)`` at signature level. The cache hit (the common case) returns without touching DB. The cache-miss closure ``_compute_lazy`` lazily acquires a session via ``_lazy_db_session()`` only when invoked.

Get Market

curl --request GET \
  --url https://api.polysimulator.com/v1/markets/{condition_id} \
  --header 'X-API-Key: <api-key>'

{
  "condition_id": "<string>",
  "slug": "<string>",
  "question": "<string>",
  "outcomes": [
    "<string>"
  ],
  "active": true,
  "closed": false,
  "is_hot": false,
  "image_url": "<string>",
  "category": "<string>",
  "clob_token_ids": [
    "<string>"
  ],
  "volume_24h": "<string>",
  "last_price": "<string>",
  "live_price": {
    "buy": "<string>",
    "sell": "<string>",
    "volume": "<string>",
    "updated_at": "<string>",
    "source": "<string>",
    "outcomes": []
  },
  "event_group_id": "<string>",
  "event_title": "<string>",
  "end_date": "<string>",
  "resolved_outcome": "<string>",
  "archived": false,
  "archived_at": "<string>",
  "tokens": [
    {
      "token_id": "<string>",
      "outcome": "<string>",
      "price": 0,
      "winner": false
    }
  ],
  "question_id": "<string>",
  "market_slug": "<string>",
  "neg_risk": true
}