24h Volume—Open Interest—24h Liquidations$1.36B24h Long/Short—BTC Dominance—ETH Dominance—
App
Language ▾
$ USD ▾
/api/hl/whale/:addr
GETAvailable

Hyperliquid single-whale detail

Hyperliquid single-whale detail (positions and activity)

GET/api/hl/whale/:addr
When the stored snapshot of the address is older than 10 minutes, the request refreshes it from the Hyperliquid public API before answering, so the first call can be slower.

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
addr pathstringRequired——0x-prefixed 40-hex address; 400 on bad format (lowercase). Example: 0x5b5d51203a0f9079f8aeb098a6523a13f298c060

Parameters marked “path” are part of the URL.

Example request

curl -s "https://www.coinboss.com/api/hl/whale/0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

Response fields

The field table is generated from real responses, so it lists exactly what the endpoint returns. Paths use a[] for array items and {*} for objects keyed by a dynamic name such as a coin or an exchange.

FieldTypeUnitDescription
successboolean—true when the request succeeded. On failure the body is `{ success: false, code, error, request_id }`.
updatednumbermsWhen the data was last updated.
addressstring—On-chain address.
trackedboolean—True when the address is in the tracked whale pool.
labelsarray—Labels.
labels[]object—Labels.
labels[].labelstring—Label.
labels[].typestring—Type.
profileobject—Pool record of the address; null when it is not tracked.
profile.firstSeennumbermsFirst time the address was recorded in a large fill or a liquidation.
profile.lastActivenumbermsLast time the address was seen in a large fill or a liquidation.
profile.totalVolumeUsdnumberUSDCumulative notional of the address's large fills recorded since `firstSeen`; not its full trading volume.
profile.tradeCountnumbercountNumber of large fills recorded for the address since `firstSeen`.
profile.maxFillUsdnumberUSDLargest single fill recorded for the address.
profile.liqCountnumbercountLiquidations of this address on Hyperliquid recorded since it has been tracked.
profile.sourcestring—Where the value comes from.
profile.accountValuenumberUSDAccount equity.
profile.totalUpnlnumberUSDTotal unrealised PnL.
profile.totalPosValuenumberUSDSum of the position values of all open positions at the last poll (`posPolledAt`); null when never polled.
profile.posPolledAtnumbermsWhen positions were last polled.
positionsarray—Open positions.
positions[]object—Open positions.
positions[].coinstring—Coin symbol, upper case (for example BTC).
positions[].sidestring—`long` / `short` or `buy` / `sell`.
positions[].szinumber—Signed position size in coins (negative = short).
positions[].entryPxnumberUSDAverage entry price.
positions[].positionValuenumberUSDPosition notional.
positions[].unrealizedPnlnumberUSDUnrealised profit and loss.
positions[].roenumberfractionUnrealised PnL divided by the margin of the position, as Hyperliquid reports it (0.13 = 13 %); null when it is zero or missing.
positions[].leveragenumber—Leverage of the position.
positions[].leverageTypestring—Margin mode of the position: `cross` or `isolated`.
positions[].marginUsednumberUSDMargin used by the position.
positions[].liquidationPxnumber|nullUSDEstimated liquidation price.
positions[].snapshotTsnumbermsTime of the position snapshot.
recentLiquidationsarray—Up to 50 most recent liquidations of this address on Hyperliquid, newest first; empty when none are recorded. empty in the samples used to generate this table
statsobject—Trading statistics computed from the address's most recent perpetual fills (at most 2,000); null until they have been computed.
stats.windowDaysnumberdaysDays between the oldest and newest fill analysed (minimum 1).
stats.fillsAnalyzednumbercountNumber of fills analysed: the most recent fills Hyperliquid returns for the address, at most 2,000.
stats.closedTradesnumbercountClosing events among the analysed perpetual fills (fills with non-zero closed PnL, grouped by transaction and coin).
stats.winsnumbercountClosing events with positive closed PnL.
stats.winRatenumberfraction`wins` ÷ `closedTrades` (0.6 = 60 %); null when there are no closing events.
stats.realizedPnlnumberUSDSum of closed PnL over the analysed fills, before fees.
stats.feesPaidnumberUSDSum of trading fees over the analysed perpetual fills.
stats.volumeUsdnumberUSDSum of price × size over the analysed perpetual fills.
stats.maxDrawdownnumberUSDLargest peak-to-trough fall of cumulative closed PnL within the analysed fills; null when there was no drawdown.
stats.roinumberfraction30-day return on the account from Hyperliquid's own leaderboard (0.1 = 10 %); null when the address is not on that leaderboard.
stats.topCoinsarray—Largest coins.
stats.topCoins[]string—Largest coins.
stats.computedAtnumbermsTimestamp.

Generated 2026-11-11 23:00 UTC from 1 real responses.

Example response

/api/hl/whale/0x5b5d51203a0f9079f8aeb098a6523a13f298c060 · Real response captured 2026-11-13 03:58:41 UTC. Long arrays and maps are shortened for display: labels had 3 items; positions had 23 items.

  • {
    • "success": true,
    • "updated": 1794542321546,
    • "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
    • "tracked": true,
    • "labels": [
      • { … 2 },
      • { … 2 }
      ],
    • "profile": {
      • "firstSeen": 1784647213853,
      • "lastActive": 1794431032742,
      • "totalVolumeUsd": 1925599.62,
      • "tradeCount": 21,
      • "maxFillUsd": 207800.94,
      • "liqCount": 0,
      • "source": "bigfill",
      • "accountValue": 72162095.74,
      • "totalUpnl": 69508245.45,
      • "totalPosValue": 332670116.98,
      • "posPolledAt": 1794542171319
      },
    • "positions": [
      • { … 12 },
      • { … 12 }
      ],
    • "recentLiquidations": [],
    • "stats": {
      • "windowDays": 1,
      • "fillsAnalyzed": 2000,
      • "closedTrades": 1262,
      • "wins": 772,
      • "winRate": 0.6117,
      • "realizedPnl": 44221.53,
      • "feesPaid": 164.6835,
      • "volumeUsd": 1047900.19,
      • "maxDrawdown": 2774.11,
      • "roi": 0.812723,
      • "topCoins": [ … 5 ],
      • "computedAt": 1793024816450
      }
    }

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
20s
Edge micro-cache
10s
Update frequency
positions every 5 min for top addresses, refreshed on request when older than 10 min; API cache 20 s
Window
latest positions; liquidation history as stored
Data sources
Profile of one Hyperliquid address: positions (polled from the official info API, refreshed on request if stale), liquidation history from our own node, statistics and labels.
Exchange coverage
Any address; richer data for addresses already in the tracked pool
Pagination
none
Units
USD
Timestamps
Unix epoch milliseconds (UTC) unless the field description says otherwise
Response format
json
Stability
Stable

Live status

AvailableChecked 2026-11-13 03:58:41 UTCHTTP 2004 msSchema matchesNewest data point 0s old

Availability, last 30 days

99.76% of 409 checks passed

Errors

Failed calls share one shape on every endpoint. The full list is on the errors page. Errors and rate limits →

CodeHTTPMeaningWhat to do
INVALID_PARAM400A required parameter is missing or a value is not accepted. `param` names the parameter when it is known.Do not retry unchanged; fix the request.
UNAUTHORIZED401The `CB-API-KEY` header was sent but the key is unknown or revoked. Public data needs no key — drop the header or use a valid key.Do not retry unchanged.
FORBIDDEN403The route is not part of the public API (internal or account-only).Do not retry.
NOT_FOUND404Unknown route, or the requested coin / exchange / fund does not exist.Do not retry; check the path and identifiers against the catalog.
RATE_LIMITED429More requests than the per-minute limit. `Retry-After` gives the seconds to wait.Wait for `Retry-After`, then retry with backoff.
INTERNAL500Unexpected server error. The message is generic by design; quote `request_id` when reporting it.Retry once after a few seconds; report it with the request id if it persists.
UPSTREAM_FAILED503The data source behind this endpoint did not answer in time. No stale or substitute numbers are returned in its place.Retry with backoff; check the status page.
UNAVAILABLE501 / 503The dataset is temporarily not ready (cache warming) or the endpoint has no lawful public source yet.Retry later; the catalog marks endpoints that are unavailable by design.
REQUEST_FAILED200Some older endpoints answer HTTP 200 with `success: false`. Always check `success`, not only the HTTP status.Depends on the message; treat as a failed request.

Try it

GET/api/hl/whale/:addrAvailable
Parameters

string — 0x-prefixed 40-hex address; 400 on bad format (lowercase).

Request URLhttps://www.coinboss.com/api/hl/whale/0x5b5d51203a0f9079f8aeb098a6523a13f298c060
Choose an endpoint and press “Send request”. The response, headers and timing will appear here.