---
title: "Fetch normalized, Kairos-ingested trade history for a contract"
method: GET
path: "/trades/history"
tags: ["Trades"]
---

# Fetch normalized, Kairos-ingested trade history for a contract

`GET /trades/history`

## Request

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

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.

## Query parameters

- `provider` string, required
- `contract_id` string, required
- `window_seconds` integer
- `before` integer, nullable
- `limit` integer, nullable
- `trigger_ingest` boolean

## Response `200`

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

- TradesHistoryResponse
  - `trades` TradesTrade[], required
    - `trade_id` string, required
    - `order_id` string, nullable, required: Venue order identifier or hash shared by fills from the same order. Null when the source venue does not provide an order identifier. This is not a Kairos order UUID.
    - `contract_id` string, required
    - `size` integer, required: Traded size (contracts/shares).
    - `price` number, required: Trade price of the traded outcome, 0-100 cents scale.
    - `outcome` string, required: Outcome name/index the trade was executed against (e.g. "yes", "no", or a token-based outcome label).
    - `timestamp` number, required: Unix timestamp, seconds.
    - `token_id` string: Outcome token identifier, present only when applicable.
    - `metadata` string: Provider-specific JSON blob serialized as a string, present only when available.
    - `taker_address` string: Taker wallet address, present only for on-chain venues where it's known.
    - `maker_address` string: Counterparty wallet/contract address; may be the canonical exchange contract on aggressor-summary rows or a real wallet on maker-fill legs. Present only when known.
    - `side` 'BUY' | 'SELL': Trade direction (distinct from `outcome`), present only when known.
    - `yes_price` number, required: Legacy field: price expressed on the 'yes' outcome, 0-100 scale, derived from `price`/`outcome`.
    - `no_price` number, required: Legacy field: price expressed on the 'no' outcome, 0-100 scale, derived from `price`/`outcome`.
    - `taker_side` string, required: Legacy alias, always equal to `outcome`.
  - `has_more` boolean, required: True if more trades exist before the oldest trade in this response (pagination via `before`).
  - `oldest_available_ts` number, nullable: Unix timestamp (seconds) of the oldest trade Kairos has ingested for this contract, or null if unknown.
  - `source` string, 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_hours` number, required: Hours of trade history coverage available/considered for this response.
  - `indexing` boolean, required: True if ingestion was triggered/in progress for this window (only meaningful with `trigger_ingest=true`).

## Other responses

- `400`: Invalid trade history request (unknown provider, invalid contract_id, or a request the service itself rejected as malformed).
- `401`: No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token.
- `403`: API-key credential lacks the `trade:read` scope, or API access to the requested provider is currently disabled.
- `422`: Request failed FastAPI parameter validation.
- `429`: Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below.
- `500`: Trade history fetch failed on the backend.
- `503`: Per-venue API-access flag could not be read or validated.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)