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). 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.

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>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/markets/by-slug/{slug}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/markets/by-slug/{slug}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/markets/by-slug/{slug}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/markets/by-slug/{slug}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "condition_id": "<string>",
  "slug": "<string>",
  "question": "<string>",
  "outcomes": [
    "<string>"
  ],
  "active": true,
  "closed": false,
  "is_hot": false,
  "image_url": "<string>",
  "category": "<string>",
  "display_label": "<string>",
  "clob_token_ids": [
    "<string>"
  ],
  "volume_24h": "<string>",
  "volume_total": "<string>",
  "last_price": "<string>",
  "live_price": {
    "buy": "<string>",
    "sell": "<string>",
    "volume": "<string>",
    "updated_at": "<string>",
    "source": "<string>",
    "outcomes": [],
    "synced_at": "<string>"
  },
  "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,
  "canonical_redirect_slug": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

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. Both spellings are accepted 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

display_label

string | null

What this market is called inside its event group (e.g. "Bernadette Wilson" for "Will Bernadette Wilson win the 2026 Alaska governor election?"). null when the market sync has not computed one yet — fall back to question.

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 in USD — the volume traded on this market over the trailing 24 hours, and nothing else. Stringified for floating-point precision safety. null when no 24-hour figure has been reported for this market yet — distinct from "0", which means the market traded zero volume in the last 24 hours. For the all-time figure use volume_total.

volume_total

string | null

Cumulative all-time volume in USD for this market, since it opened. Stringified for floating-point precision safety. null when no cumulative figure has been reported yet — distinct from "0", which means the market has never traded. This is a much larger number than volume_24h for any market older than a day.

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 | null

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.

canonical_redirect_slug

string | null

SEO redirect target: populated with the current canonical slug when this market was requested via a deprecated/historical slug alias.

Get Market By Slug

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

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/markets/by-slug/{slug}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/markets/by-slug/{slug}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/markets/by-slug/{slug}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/markets/by-slug/{slug}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "condition_id": "<string>",
  "slug": "<string>",
  "question": "<string>",
  "outcomes": [
    "<string>"
  ],
  "active": true,
  "closed": false,
  "is_hot": false,
  "image_url": "<string>",
  "category": "<string>",
  "display_label": "<string>",
  "clob_token_ids": [
    "<string>"
  ],
  "volume_24h": "<string>",
  "volume_total": "<string>",
  "last_price": "<string>",
  "live_price": {
    "buy": "<string>",
    "sell": "<string>",
    "volume": "<string>",
    "updated_at": "<string>",
    "source": "<string>",
    "outcomes": [],
    "synced_at": "<string>"
  },
  "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,
  "canonical_redirect_slug": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Overview

Endpoints

Get Market By Slug

Authorizations

Headers

Path Parameters

Response