GET
/api/v1/futures/largest-liquidationsHobbyist tier+ · 30 req/minTop-N single liquidation events by USD notional over a trailing window, filterable.
Ranks individual liquidation prints by notional ($) inside the window. Filter by coin, exchange, side, or minimum size. Response also carries facets (every coin + exchange reporting in the window) so clients can render filter bars without an additional round-trip.
Query parameters
All query parameters are optional unless marked required.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| limit | number | optional | 100 | Rows. Max 500. |
| days | number | optional | 7 | Trailing window. Max 90. |
| coin | string | optional | — | Base asset filter. |
| source | string | optional | — | Exchange filter. |
| side | enum | optional | — | Side filter. longshort |
| minUsd | number | optional | — | Minimum notional, USD. |
Response shape
Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.
data payloadtypescript
// Wrapped in the standard envelope:
// {
// data: /* shape below */,
// meta?: { total?: number; limit?: number; offset?: number; ... }
// }
{
rows: Array<{
id: number;
source: string;
base: string;
canonicalSymbol: string;
side: "long" | "short";
price: number;
qtyBase: number;
qtyUsd: number;
ts: number;
}>;
totalUsd: number;
totalLongUsd: number;
totalShortUsd: number;
biggestUsd: number;
distinctCoins: number;
distinctSources: number;
windowDays: number;
lastTs: number | null;
facets: { coins: string[]; sources: string[] };
}Example
Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.
Requestbash
curl -sS "http://localhost:3000/api/v1/futures/largest-liquidations?days=7&minUsd=1000000" \
-H "Authorization: Bearer cg_live_YOUR_KEY"Responsejson
{
"data": {
"rows": [
{ "id": 4421, "source": "bybit", "base": "BTC", "canonicalSymbol": "BTCUSDT", "side": "long", "price": 63180.5, "qtyBase": 120.5, "qtyUsd": 7610000, "ts": 1744835000000 }
],
"totalUsd": 7610000,
"totalLongUsd": 7610000,
"totalShortUsd": 0,
"biggestUsd": 7610000,
"distinctCoins": 1,
"distinctSources": 1,
"windowDays": 7,
"lastTs": 1744835000000,
"facets": { "coins": ["BTC"], "sources": ["bybit"] }
},
"meta": { "total": 1, "limit": 100, "days": 7 }
}Next
Check the error code reference, or get an API key to try the request against your own account.