---
title: "Replay historical whale trades"
method: GET
path: "/api/v1/whale-trades/history"
tags: ["Whale Trades"]
---

# Replay historical whale trades

`GET /api/v1/whale-trades/history`

Returns historical whale trades from local whale_alerts rows, not request-time provider fetches. Filter by condition_id, trader, category, minimum grade, platform, and RFC3339 from/to windows. All filters are pushed into SQL before LIMIT, every request uses SQL-backed limit + 1 pagination, and results are ordered newest first by traded_at desc, id desc. Metadata exposes local_replay source and best_effort completeness.

## Query parameters

- `limit` integer
- `cursor` string
- `min_size` number
- `condition_id` string
- `trader` string
- `category` string
- `min_grade` 'S' | 'A' | 'B' | 'C' | 'D' | 'F'
- `platform` 'polymarket' | 'kalshi' | 'all'
- `from` string, date-time
- `to` string, date-time

## Headers

- `If-None-Match` string

## Response `200`

Historical whale trade replay

- object
  - `object` 'list', required
  - `data` WhaleTrade[], required
    - `id` string, required — Prefixed ID (wt_...).
    - `traded_at` string, date-time, required
    - `size_usd` number, required
    - `side` 'BUY' | 'SELL', required
    - `outcome` string, nullable — Traded outcome label (e.g. "Yes"/"No"/team name), resolved provider-first from the trade's outcome_index against market_canonical (index 0 -> yes, 1 -> no). Distinct axis from side (BUY/SELL): side is the trade direction, outcome is which leg was traded. null for multi-outcome (outcome_index >= 2) or unsynced markets; a Kalshi row carries its provider label here (only token_id is null for Kalshi, since there is no CLOB token).
    - `token_id` string, nullable — The Polymarket CLOB token id (ERC1155 asset id, decimal string) for the traded outcome; null when unavailable (e.g. Kalshi markets, unsynced markets).
    - `price` number, required
    - `signal_score` number, required — 0.0–1.0 normalized signal score.
    - `trader` object, required
      - `id` string, required
      - `address` string, required
      - `username` string, nullable
      - `grade` string, nullable
    - `market` object, required
      - `id` string, required
      - `condition_id` string, required
      - `title` string, required
      - `slug` string, nullable
      - `category` string, nullable — Provider-backed market_canonical category.
  - `has_more` boolean, required
  - `next_cursor` string, nullable
  - `meta` WhaleTradeHistoryMeta, required
    - `request_id` string, required — Unique request ID (req_ prefix).
    - `cached` boolean, required
    - `cache_age_s` integer, nullable — Cache age in seconds, null if not cached.
    - `source` object, required
      - `kind` 'local_replay', required
      - `table` 'whale_alerts', required
      - `provider_fetch_at_request_time` false, required
    - `completeness` object, required
      - `status` 'best_effort', required
      - `reason` string, required — Explains that local replay completeness can vary by market and time window.

## Other responses

- `304` — Not Modified. Returned when If-None-Match matches the current payload.
- `400` — Invalid request parameter
- `401` — Missing or invalid API key
- `402` — Active Insider subscription required
- `403` — Account access denied
- `408` — Request exceeded the server's 30-second transport timeout. The timeout response has an empty body because it is generated before handler-level JSON error shaping.
- `423` — Account is locked
- `429` — Rate limit exceeded (100 req/min; batch endpoints also reserve 100 batch item units/min before execution)
- `503` — Redis-backed authenticated rate limiter unavailable; retry after the per-process outage cooldown

## Changes

- **2026-07-01** `e31231c630fb` — 2 info
  - added the optional property `data/items/outcome` to the response with the `200` status
  - added the optional property `data/items/token_id` to the response with the `200` status
- **2026-06-01** `422bd4dc1611` — 63 warning, 3 info
  - added the new `account_locked` enum value to the `error/code` response property for the response status `400`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `401`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `402`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `403`
  - …62 more
- **2026-05-08** `80e8658e5acf` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/0xinsider/apis/0xinsider-api/changes/api/v1/whale-trades/history/get.md)

---

[API](https://skmtc.dev/0xinsider/apis/0xinsider-api.md) · [All operations](https://skmtc.dev/0xinsider/apis/0xinsider-api/llms.txt) · [OpenAPI document](https://skmtc.dev/0xinsider/apis/0xinsider-api/revisions/137fa0fd3297?raw)