Skip to main content
GET
Get API public v1 live whale trades by coin

Authorizations

X-API-Key
string
header
required

Create an API key at https://developers.coinversa.ai/keys. REST limits are shared across keys by account; access uses the effective tier of the presented key.

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
default:6h

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.

Pattern: ^[0-9]+[mhd]$
minNotional
number<double>
default:1000000

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

Required range: x >= 100000
limit
integer<int32>
default:50

Largest fills to return, by notional.

Required range: 1 <= x <= 200

Response

OK

aggressor
string
required

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

coin
string
required

Canonical market symbol.

count
integer<int64>
required

Fills returned (len(trades)).

coverage
object
required
minNotional
number<double>
required

Notional floor applied, USD.

notes
string[] | null
required
ranking
string
required

Always notional_desc.

since
string
required

Window as requested.

source
object
required
tierAssignment
string
required

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

trades
object[] | null
required

Largest notional first, then newest first.

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<int64>
required

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

windowStart
integer<int64>
required

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

$schema
string<uri>
read-only

A URL to the JSON Schema for this object.

Example:

"https://api.coinversa.ai/schemas/WhaleTradesBody.json"