Markets

List and search marketsPermalink to this section

curl -G "$RIDDLE_API_BASE/v1/markets" \
  --data-urlencode "q=shutdown" \
  --data-urlencode "platform=kalshi,polymarket" \
  --data-urlencode "sort=market_id" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=50" \
  -H "x-api-key: $RIDDLE_API_KEY"

Response envelopePermalink to this section

Market fieldsPermalink to this section

Retrieve one marketPermalink to this section

curl "$RIDDLE_API_BASE/v1/markets/kalshi/$MARKET_ID" \
  -H "x-api-key: $RIDDLE_API_KEY"

Observation historyPermalink to this section

{
  "data": [
    {
      "observed_at": "2026-09-20T00:00:00Z",
      "yes_probability": 0.28,
      "indicative_basis": "midpoint",
      "price_semantics_version": 2
    },
    {
      "observed_at": "2026-09-21T00:00:00Z",
      "yes_probability": 0.30,
      "indicative_basis": "midpoint",
      "price_semantics_version": 2
    }
  ],
  "meta": {
    "platform": "kalshi",
    "market_id": "$MARKET_ID",
    "days": 30,
    "window": {
      "requested_days": 30,
      "since": "2026-08-22T00:00:00Z",
      "until": "2026-09-21T00:00:00Z"
    },
    "returned_points": 2,
    "first_observation_at": "2026-09-20T00:00:00Z",
    "last_observation_at": "2026-09-21T00:00:00Z",
    "rows_examined": 2,
    "excluded_invalid_points": 0,
    "limits": {
      "requested_limit": 500,
      "effective_point_limit": 500,
      "max_points": 2000
    },
    "truncated": false,
    "completeness": "partial_by_construction",
    "completeness_note": "Riddle observations only. No claim of full venue retention across the requested window.",
    "series_type": "riddle_observations"
  },
  "request_id": "req_2c90fe11"
}

Read the meta block before you analyse the series. The window fields tell you what was looked at, returned_points and the observation bounds tell you what came back, and truncated with excluded_invalid_points tells you whether the slice you are holding is the whole of what was examined. A window you asked for is not evidence that observations exist across it, so treat these series as partial by construction rather than as backtest coverage.

resp = session.get(
    f"{BASE}/v1/markets/{platform}/{market_id}/history",
    params={"days": 90, "limit": 2000},
    timeout=20,
)
payload = resp.json()
meta = payload["meta"]

if meta["truncated"]:
    print("series hit the point limit", meta["limits"]["effective_point_limit"])
if meta["excluded_invalid_points"]:
    print("dropped from the examined slice:", meta["excluded_invalid_points"])

if meta["returned_points"] == 0:
    raise SystemExit("no observations in this window")

print("requested", meta["window"]["since"], "to", meta["window"]["until"])
print("observed", meta["first_observation_at"], "to", meta["last_observation_at"])

# Analyse against the observed bounds, not the requested window.
points = payload["data"]

Research snapshotPermalink to this section

Research uses the same x-api-key header and the same account quota as the rest of v1. It is addressed the same way as detail and history: the exact platform and the exact platform-native market id. There is no title matching and no inference that a market on one venue is the same contract as a similarly worded market on another.

• Market identity: the platform and platform-native market id the snapshot was built for.
• The resolution rule text Riddle has stored, with its provenance and a flag when the stored text was truncated.
• The resolution date associated with the market, where one is stored.
• Independently retrieved yes and no quotes: bid and ask with the size shown against them at retrieval.
• Timestamps for the source and for Riddle's receipt of it.
• The price semantics version and the model version that produced the snapshot.
• A staleness indication for the snapshot as a whole.

Where a quote, a size or a rule text is not available, the field is null or is reported as explicitly unavailable. Null means unavailable, never zero and never a quote of zero size.

Snapshots carry a five-minute freshness classification. That threshold is a research convention for deciding whether a stored observation is recent enough to reason about, not a latency guarantee and not a statement about tradability.

curl "$RIDDLE_API_BASE/v1/markets/kalshi/KXPRESPERSON-28-JVAN/research" \
  -H "x-api-key: $RIDDLE_API_KEY"

Contract research workspacePermalink to this section

An authenticated workspace at https://app.getriddle.ai/research sits alongside this endpoint. It compares two exactly addressed market identities, works through conditional binary settlement scenarios, and exports the working as JSON or CSV so a result can be reproduced.

• Payout is a fixed, disclosed assumption of $1 per winning unit. It is not configurable.
• Fees and slippage are the totals you enter yourself, per leg.
• USD and USDC are treated at parity; no conversion or basis is modelled.