KAkairos
Trades

Fetch normalized, Kairos-ingested trade history for a contract

Returns normalized trade history for a single (provider, contract_id) from Kairos's own ingested trade store. It serves from data Kairos has already ingested, so coverage depends on how much history has been backfilled/streamed for that contract.

Auth: requires the trade:read scope (admin/JWT bypass the scope check; API keys need trade:read), plus API access to the requested provider being enabled for API-key callers — 403 if disabled.

Data source / staleness: reads ingested trade rows for the window [before - window_seconds, before] (or ending "now" if before is omitted). If trigger_ingest=true and the data is missing or stale, an ingestion job is kicked off for that contract and reported via the indexing flag in the response — the returned trades may still be incomplete for that call.

get/trades/history

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.

contract_idstring required

Provider-specific contract identifier. Empty or >128 chars returns 400.

window_secondsinteger

Lookback window in seconds, ending at before (or now). Clamped to [3600, 86400] (1 hour to 24 hours).

beforeinteger nullable

Unix-seconds cursor — return trades at or before this timestamp. Omit to end the window at "now".

limitinteger nullable

Max trades returned. If omitted, the service applies its own internal default.

trigger_ingestboolean

If true, kicks off ingestion when data for this window is stale or missing, rather than just returning what's already stored.

Response

Normalized trade rows for the window plus pagination/coverage metadata.

has_moreboolean required

True if more trades exist before the oldest trade in this response (pagination via before).

oldest_available_tsnumber nullable

Unix timestamp (seconds) of the oldest trade Kairos has ingested for this contract, or null if unknown.

sourcestring required

Opaque internal marker indicating how the response was served. NOT a stable part of the contract — its value may change without notice; do not depend on or switch on it.

coverage_hoursnumber required

Hours of trade history coverage available/considered for this response.

indexingboolean required

True if ingestion was triggered/in progress for this window (only meaningful with trigger_ingest=true).

Example response

{
  "trades": [
    {
      "trade_id": "kalshi:KXPRESPOLAND-24-DT:9f2a1c",
      "order_id": "0x9f2a1c...7bd4",
      "contract_id": "KXPRESPOLAND-24-DT",
      "size": 50,
      "price": 63,
      "outcome": "yes",
      "timestamp": 1753142400,
      "yes_price": 63,
      "no_price": 37,
      "taker_side": "yes"
    }
  ],
  "oldest_available_ts": 1750000000,
  "coverage_hours": 24
}

Changes

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