Market Data

Get Market By Slug

Resolve 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

markets

by-slug

{slug}

Get Market By Slug

curl --request GET \
  --url https://api.polysimulator.com/v1/markets/by-slug/{slug} \
  --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

slug

string

required

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 Order BookFetch the CLOB order book for a market outcome. Returns bids and asks with configurable depth. Requires a valid token_id in the cache (from the price enrichment data). If `outcome` is omitted, the first available outcome is used automatically (supports binary Yes/No and categorical Up/Down markets).

Get Market By Slug

curl --request GET \
  --url https://api.polysimulator.com/v1/markets/by-slug/{slug} \
  --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
}