---
title: "Get API public v1 live whale trades by coin"
method: GET
path: "/api/public/v1/live/whale-trades/{coin}"
---

# Get API public v1 live whale trades by coin

`GET /api/public/v1/live/whale-trades/{coin}`

## Request

- Base URL: `https://api.coinversa.ai`
- URL: `https://api.coinversa.ai/api/public/v1/live/whale-trades/{coin}`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/coinversa/apis/coinversa-api/docs/api/public/v1/live/whale-trades/:coin/get.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `coin` string, required: Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling.

## Query parameters

- `since` string: Lookback window: digits followed by m, h or d (e.g. 30m, 6h). At least 1m (422 below) and at most 24h: the fills table has no index on notional, so cost grows with the coin's fill count in the window. Longer windows are rejected with 400, never silently narrowed. Equivalent spellings (6h, 360m) share one cache entry.
- `minNotional` number, double: Smallest fill to return, USD notional (price x size). Default 1,000,000; the floor is 100,000; NaN and infinities are rejected. This is trade size, not the 'whale' size tier (lifetime volume).
- `limit` integer: Largest fills to return, by notional.

## Response `200`

OK

- WhaleTradesBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `aggressor` string, required: Always unknown: the fills table does not record which side took liquidity.
  - `coin` string, required: Canonical market symbol.
  - `count` integer, required: Fills returned (len(trades)).
  - `coverage` WhaleTradesCoverage, required
    - `completeness` string, required: Always 'unknown' until the syncer provides an ingestion watermark: fills still in flight at compute time are missing without notice.
  - `minNotional` number, double, required: Notional floor applied, USD.
  - `notes` string[], nullable, required
  - `ranking` string, required: Always notional_desc.
  - `since` string, required: Window as requested.
  - `source` WhaleTradesSource, required
    - `asOf` integer, required: When this body was computed, Unix ms. Preserved on cache hits (refreshes every 60 s). This is compute time, not an ingestion watermark.
    - `cadence` string, required
    - `kind` string, required: Always 'fills': individual matches, not aggregated volume.
    - `observedThrough` integer, nullable, required: Ingestion watermark (how far the fill stream had been indexed), Unix ms. Always null today: the syncer exposes none, so the last minutes of the window may be incomplete.
    - `table` string, required: Always trades: indexed Hyperliquid fills.
  - `tierAssignment` string, required: Always current: cohorts are the wallets' tiers now, not at fill time.
  - `trades` WhaleTrade[], nullable, required: Largest notional first, then newest first.
    - `buyer` WhaleTradeParty, required
      - `address` string, required: Wallet address, 0x-prefixed hex; empty when the counterparty is not an indexed wallet.
      - `direction` string, required: What the fill did to this wallet's position: Open Long, Close Short, Long > Short, ...; empty when unknown.
      - `pnlTier` string, required: Wallet's CURRENT all-time PnL tier (legacy slug); empty when unknown.
      - `sizeTier` string, required: Wallet's CURRENT lifetime-volume tier (legacy slug); empty when unknown.
    - `idKind` string, required: exchange: one fill, both counterparties can be paired. synthetic: one wallet's observation of a fill whose exchange id was missing; its counterparty cannot be paired and may appear as a separate row.
    - `notional` number, double, required: price x size, USD.
    - `price` number, double, required: Fill price, USD per unit.
    - `seller` WhaleTradeParty, required
      - `address` string, required: Wallet address, 0x-prefixed hex; empty when the counterparty is not an indexed wallet.
      - `direction` string, required: What the fill did to this wallet's position: Open Long, Close Short, Long > Short, ...; empty when unknown.
      - `pnlTier` string, required: Wallet's CURRENT all-time PnL tier (legacy slug); empty when unknown.
      - `sizeTier` string, required: Wallet's CURRENT lifetime-volume tier (legacy slug); empty when unknown.
    - `size` number, double, required: Fill size, base units.
    - `tid` string, required: Trade id as a decimal string (64-bit; do not parse into a JavaScript number). Positive: Hyperliquid's exchange id, shared by both counterparties. Negative: a syncer-generated, wallet-specific synthetic id (idKind synthetic).
    - `time` integer, required: Fill time, Unix ms (UTC; independent of the database session time zone).
  - `truncated` boolean, required: True when at least one more fill above minNotional exists in the window beyond the returned limit (the query fetches limit + 1).
  - `windowEnd` integer, required: Exclusive end of the window, Unix ms UTC — captured once before querying.
  - `windowStart` integer, required: Inclusive start of the window, Unix ms UTC — the exact bound passed to SQL.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `504`: Gateway Timeout

## Changes

- **2026-10-12** `7aae8c32ff78`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coinversa/apis/coinversa-api/changes/api/public/v1/live/whale-trades/:coin/get.md)

---

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