Skip to main content
The Market Data API is a read-only HTTP API for Kairos market data: OHLCV candles, trade history, market metadata, resolutions, and mark prices. Use it to paint charts, backfill history, resolve venue identifiers, and check settlement outcomes. It is currently in beta.

​
Start here

Base URL:
No signup is required. Every endpoint works anonymously on the free tier with low per-IP rate limits. This request runs as-is:
For production budgets, move to API-key authentication. The machine-readable contract is published as OpenAPI 3.1 — /openapi/market-data-api.yaml · /openapi/market-data-api.json. The API Reference renders it with live try-it panels.

​
Endpoints

Supported providers: kalshi, polymarket, predictfun, hyperliquid. (opinion is accepted for historical reads.) Portfolio and PnL endpoints are served by the REST API, not by this one.

​
Conventions

  • Prices are quoted on the 0–100 scale (implied probability × 100) throughout — candles, trades, and marks. Two decimal places of precision are significant.
  • Timestamps: request parameters accept ISO 8601 (2026-07-15T00:00:00Z); response timestamps are unix seconds (fractional where the source has millisecond precision) except candle bucket_start, which is ISO 8601 with an explicit UTC offset.
  • Identifiers: contract_id is the venue’s market identifier; token_id identifies a specific outcome token within a market. On multi-outcome markets every outcome has an independent token and independent prices.
  • Volumes are contract quantities on candles and trades; *_usd fields are notional (size × price / 100).

​
Data semantics

  • Candles are sparse. Buckets with no trades are omitted rather than zero-filled. Gaps in a candle series reflect periods with no trading.
  • A mark is the last traded price of an outcome token. Marks are point-in-time snapshots; for streaming updates, use the WebSocket API.
Absence is a valid answer, not an error. Unresolved markets are omitted from /v1/resolutions, never-traded pairs are omitted from /v1/marks, and empty candle windows return 200 with an empty array. Do not treat any of these as failures.

​
Response formats

  • JSON by default. All responses support gzip via Accept-Encoding.
  • Candles are also available in a compact binary format.
  • Historical responses carry Cache-Control and ETag headers — conditional requests with If-None-Match return 304 Not Modified.

​
Two products, one API

Kairos serves prediction markets and perpetual futures from the same services. They share transport, auth, and error envelopes, and differ in identity and price semantics:
Never apply prediction-market probability math to a perpetual price. A perpetual price is a venue price, not a 0–100 probability. Dividing one by 100 produces a silently wrong number.
Hyperliquid appears in both columns and the two are never interchangeable. Its HIP-4 outcome markets are prediction markets (venue coins look like #1210), read under provider=hyperliquid. Its perpetuals are bare coins (BTC, kPEPE) with their own identity scheme, read under GET /v1/perpetuals/hyperliquid/.... See Perpetuals.
The perpetual surface is live on this base URL but is beta and flag-gated: PERPETUALS_PUBLIC_API_ENABLED is on in production and staging, and a deployment with it off returns 404 for the snapshot route. Coverage is not the full venue catalog either — Hyperliquid enrollment is capped. Read Perpetuals → Overview before writing any code against it.

​
Errors

All errors use one envelope:
GET /ready is the one exception to the envelope. On 503 it answers {"ready": false, "failing": "clickhouse"} (or "redis").