24h Volume—Open Interest—24h Liquidations$1.36B24h Long/Short—BTC Dominance—ETH Dominance—
App
Language ▾
$ USD ▾
/api/hl/position-summary
GETAvailable

Hyperliquid position summary

Hyperliquid position summary (whale-pool scope)

GET/api/hl/position-summary

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
scopestringOptionalwhale_poolwhale_pool, all_networkScope. Example: whale_pool

Example request

curl -s "https://www.coinboss.com/api/hl/position-summary?scope=whale_pool"

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.
scopestring—Address universe of the summary: `whale_pool` (tracked whale addresses). `all_network` is accepted but currently returns no snapshot.
snapshotobject—Latest aggregate of all tracked whale positions (a snapshot is stored every 5 minutes); null when none exists.
snapshot.tsnumbermsTimestamp.
snapshot.addrCountnumbercountDistinct tracked addresses with at least one open position.
snapshot.longAddrsnumber—Number of addresses that are long.
snapshot.shortAddrsnumber—Number of addresses that are short.
snapshot.longValuenumberUSDLong notional.
snapshot.shortValuenumberUSDShort notional.
snapshot.longMarginnumberUSDMargin used by the long positions.
snapshot.shortMarginnumberUSDMargin used by the short positions.
snapshot.longUpnlnumberUSDSum of unrealised PnL of the long positions.
snapshot.shortUpnlnumberUSDSum of unrealised PnL of the short positions.
snapshot.longFundingnumberUSDSum of funding since open over the long positions, in Hyperliquid's sign convention (positive = paid, negative = received).
snapshot.shortFundingnumberUSDSum of funding since open over the short positions, in Hyperliquid's sign convention (positive = paid, negative = received).
prev24hobject—Newest stored snapshot that is at least 24 hours older than `snapshot`, for comparison; null when none exists.
prev24h.tsnumbermsTimestamp.
prev24h.addrCountnumbercountDistinct tracked addresses with at least one open position in the earlier snapshot.
prev24h.longAddrsnumber—Number of addresses that are long.
prev24h.shortAddrsnumber—Number of addresses that are short.
prev24h.longValuenumberUSDLong notional.
prev24h.shortValuenumberUSDShort notional.
prev24h.longMarginnumberUSDMargin used by the long positions in the earlier snapshot.
prev24h.shortMarginnumberUSDMargin used by the short positions in the earlier snapshot.
prev24h.longUpnlnumberUSDSum of unrealised PnL of the long positions in the earlier snapshot.
prev24h.shortUpnlnumberUSDSum of unrealised PnL of the short positions in the earlier snapshot.
prev24h.longFundingnumberUSDSum of funding since open over the long positions in the earlier snapshot (positive = paid).
prev24h.shortFundingnumberUSDSum of funding since open over the short positions in the earlier snapshot (positive = paid).

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

Example response

/api/hl/position-summary?scope=whale_pool · Real response captured 2026-11-13 03:53:08 UTC.

  • {
    • "success": true,
    • "updated": 1794541988572,
    • "scope": "whale_pool",
    • "snapshot": {
      • "ts": 1794541833226,
      • "addrCount": 1707,
      • "longAddrs": 1250,
      • "shortAddrs": 761,
      • "longValue": 2317647288.5,
      • "shortValue": 2668492906.07,
      • "longMargin": 266041962.88,
      • "shortMargin": 344054602.74,
      • "longUpnl": -225343054.98,
      • "shortUpnl": 319405247.39,
      • "longFunding": 41171557.592659,
      • "shortFunding": -92766854.054105
      },
    • "prev24h": {
      • "ts": 1794455433182,
      • "addrCount": 1731,
      • "longAddrs": 1282,
      • "shortAddrs": 754,
      • "longValue": 2508207564.38,
      • "shortValue": 2900101148.16,
      • "longMargin": 290106695.23,
      • "shortMargin": 372506105.81,
      • "longUpnl": -199152142.42,
      • "shortUpnl": 256448952.11,
      • "longFunding": 41667716.017602,
      • "shortFunding": -92718942.253169
      }
    }

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
60s
Edge micro-cache
10s
Update frequency
every 5 min (kept 90 days); API cache 60 s
Window
latest snapshot vs snapshot 24h earlier
Data sources
Aggregate long/short exposure of the tracked Hyperliquid whale pool, snapshotted in-house.
Exchange coverage
tracked whale pool (addresses that made a single fill >= 50,000 USD, were liquidated, or run a vault); not the whole network
Pagination
none
Units
USD; counts
Timestamps
Unix epoch milliseconds (UTC) unless the field description says otherwise
Response format
json
Stability
Stable

Live status

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

Availability, last 30 days

100% of 408 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/position-summaryAvailable
Parameters

string · default whale_pool — Scope.

Request URLhttps://www.coinboss.com/api/hl/position-summary?scope=whale_pool
Choose an endpoint and press “Send request”. The response, headers and timing will appear here.