GET
/api/v1/hyperliquid/whale-positionsStandard tier+ · 300 req/minTop whale positions by USD size, plus coin/side aggregates in one call.
Single-call hydration for the `/hyperliquid/whales` page. Returns the top N positions by notional, optionally alongside aggregate rollups (total long/short USD, unique addresses, per-coin breakdown, side totals).
Query parameters
All query parameters are optional unless marked required.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| limit | number | optional | 50 | Rows in the `top` array. Max 500. |
| includeAggs | boolean | optional | true | Set to `false` to skip aggregate computation. |
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; ... }
// }
{
top: Array<WhalePosition>;
aggregates: {
totalPositions: number;
totalSizeUsd: number;
totalLongUsd: number;
totalShortUsd: number;
uniqueAddresses: number;
averagePnl: number | null;
newestTs: number | null;
byCoin: Array<CoinAgg>;
bySide: Array<SideAgg>;
} | null;
}Example
Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.
Requestbash
curl -sS "http://localhost:3000/api/v1/hyperliquid/whale-positions?limit=5"Responsejson
{
"data": {
"top": [
{
"ts": 1744834800000,
"address": "0xabc...def",
"coin": "BTC",
"side": "long",
"sizeUsd": 18250000,
"entryPx": 63100,
"liqPx": 54200,
"unrealizedPnl": 210000,
"marginUsed": 3650000
}
],
"aggregates": {
"totalPositions": 1, "totalSizeUsd": 18250000,
"totalLongUsd": 18250000, "totalShortUsd": 0,
"uniqueAddresses": 1, "averagePnl": 210000,
"newestTs": 1744834800000, "byCoin": [], "bySide": []
}
},
"meta": { "total": 1, "limit": 5, "includeAggs": true }
}Next
Check the error code reference, or get an API key to try the request against your own account.