COcoinversa

Get API public v1 live whale trades by coin

Changed on
get/api/public/v1/live/whale-trades/{coin}

Request

Path parameters

coinstring required

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

Query parameters

sincestring

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.

minNotionalnumber 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).

limitinteger

Largest fills to return, by notional.

Response

OK

$schemastring uri

A URL to the JSON Schema for this object.

aggressorstring required

Always unknown: the fills table does not record which side took liquidity.

coinstring required

Canonical market symbol.

countinteger required

Fills returned (len(trades)).

minNotionalnumber double required

Notional floor applied, USD.

notesstring[] nullable required
rankingstring required

Always notional_desc.

sincestring required

Window as requested.

tierAssignmentstring required

Always current: cohorts are the wallets' tiers now, not at fill time.

truncatedboolean required

True when at least one more fill above minNotional exists in the window beyond the returned limit (the query fetches limit + 1).

windowEndinteger required

Exclusive end of the window, Unix ms UTC — captured once before querying.

windowStartinteger required

Inclusive start of the window, Unix ms UTC — the exact bound passed to SQL.

Example response

{
  "$schema": "https://api.coinversa.ai/schemas/WhaleTradesBody.json"
}

Changes