KAkairos
Candles

Fetch OHLCV candles for a single contract

Returns OHLCV candle bars for one (provider, contract_id, outcome) series over [start, end), bucketed at timeframe_seconds.

Auth: accepts an admin secret (X-Admin-Secret), an API key (X-Client-Id + X-Api-Key + X-Api-Secret), or a first-party JWT (Authorization: Bearer or turnkey_session_jwt cookie). No API-key scope is required for this endpoint — any valid credential can read candles.

Cache / data source: responses may be served from cache unless rebuild=true, which always bypasses the cache and reconstructs candles from the underlying trade/candle data, then repopulates the cache. rebuild=true is for callers that explicitly want fresh data regardless of what's cached.

Validation (all return 400): unknown provider (must exist in the live provider registry — currently includes kalshi, polymarket, dome, opinion); empty or >128-char contract_id; timeframe_seconds not one of the fixed allowed values; unparseable start/end (ISO 8601); or end <= start. An outcome index invalid for the given provider/contract (e.g. an out-of-range index on a binary market) also returns 400.

get/candles

Request

  • Base URL
    https://data.kairos.trade
  • Auth
    API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Query parameters

providerstring required

Venue identifier, matched case-insensitively against the live provider registry (e.g. kalshi, polymarket). Unknown providers return 400.

contract_idstring required

Provider-specific contract/market/token identifier. Whitespace is trimmed; empty or >128 chars returns 400.

timeframe_seconds1 | 60 | 300 | 900 | 3600 | 14400 | 86400 required

Candle bucket width in seconds. FastAPI first enforces >= 1; the handler then rejects any value not exactly one of [1, 60, 300, 900, 3600, 14400, 86400] (1s, 1m, 5m, 15m, 1h, 4h, 1d) with 400.

startstring date-time required

Window start, ISO 8601 (any offset; normalized to UTC internally). Unparseable values return 400.

endstring date-time required

Window end, ISO 8601. Must be strictly after start (400 otherwise).

outcomeinteger nullable

Zero-based outcome index for multi-outcome markets. Omitted/null is treated as 0 (the first/primary outcome). An index invalid for the contract's outcome count returns 400.

rebuildboolean

When true, bypasses the cache and forces a fresh fetch/rebuild.

Response

OHLCV series for the requested window.

Example response

{
  "candles": [
    {
      "contract_id": "KXPRESPOLAND-24-DT",
      "timeframe_seconds": 60,
      "bucket_start": "2026-07-21T14:32:00+00:00",
      "open": 63.5,
      "high": 64,
      "low": 63,
      "close": 63.8,
      "volume": 1250,
      "token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.