Contents

Whale leaderboard

Whale leaderboard of tracked Hyperliquid wallets with public labels (label + labelSource URL; otherwise the self-chosen leaderboard name), open notional, PnL, largest position with liquidation distance and the number of fill-confirmed liquidations.

GET/api/v1/whalesEvery key

Description

venue=lighter: tracked Lighter accounts (address = account index, l1Address, the self-chosen account name as label; sort size or pnl; liquidations null: not attributed per account).

Who can call it

Available with every key and keyless (X-Blockmetric-Access: public). Keys of Free accounts get free-tier data (real-time feeds, 30 days of history, heatmap over time for every coin over the last 24 hours, liquidation levels now for every coin, the same as the free web plan); Pro and Desk keys the data of their plan; API Dev / API Pro raise the limits.

No key: 24 h
Free: 30 days
Pro: 365 days
Desk: 1095 days
API Dev: 365 days
API Pro: 1095 days

History window per plan. Limits: Authentication & limits.

Parameters

Parameters of /whales
Parameter	Description
`sort`string	size (open notional, default) \| pnl (all-time PnL) \| near_liq (closest liquidation of a position ≥ $100k) \| liquidated (most fill-confirmed liquidations).one of size, pnl, near_liq, liquidated · default size
`coin`string	Only wallets with a position in this coin (sort=liquidated: liquidations in this coin).
`labelled`boolean	true = only wallets with a public label from a cited source; default false.one of true, false · default false
`limit`integer	Number of items, default 50, clamped to 1–500.1–500 · default 50
`venue`string	hyperliquid (default, the Hyperliquid answer as before) \| lighter (tracked Lighter accounts: address = the Lighter account index, venue = "lighter", liqPx as the exchange reports it). A switched-off venue answers 400.one of hyperliquid, lighter · default hyperliquid
`fields`string	Comma-separated fields of every item to return, e.g. address,label,accountValue,positionsUsd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field.
`format`string	json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON.one of json, csv, ndjson · default json

Response fields

Every success is { data, meta }; these are the fields of data. meta is the same on every endpoint.

Response fields of /whales
Field	Description
`[].address`string	Hyperliquid address (lowercase), or with venue "lighter" the Lighter account index.
`[].label`string · nullable	Public label, else the self-chosen leaderboard name.
`[].labelSource`string · nullable	Source URL of a public label, or "hyperliquid-leaderboard" (unverified).
`[].accountValue`number · nullable	Account value (USD).
`[].pnlMonth`number · nullable	30-day PnL (USD).
`[].pnlAllTime`number · nullable	All-time PnL (USD).
`[].positionsUsd`number	Open notional (USD).
`[].positionCount`integer	Number of open positions.
`[].top`object · nullable	Largest position.
`[].top.coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`[].top.side`"long" \| "short"	Position side (for liquidations: the side of the liquidated position).
`[].top.usd`number	Notional (USD).
`[].top.leverage`number · nullable	Leverage of the position (notional / margin).
`[].top.liqPx`number · nullable	Liquidation price of the position.
`[].top.liqDistance`number · nullable	Signed fraction.
`[].liquidations`integer · nullable	Fill-confirmed liquidations in the stored history (null for Lighter accounts: liquidations are not attributed per account).
`[].updatedAt`string (ISO 8601) · nullable	Newest data time of this item (ISO 8601 UTC).
`[].venue`"hyperliquid" \| "lighter"	Venue of the position (present for Lighter rows; absent = Hyperliquid).
`[].l1Address`string · nullable	Lighter: the account’s Ethereum address.

Errors

400invalid_param Invalid parameter
401unauthorized Missing or invalid API key
403plan_required Plan does not include this
403scope_required Key not scoped for this API
403ip_not_allowed Address not on the IP allowlist of the key
403origin_not_allowed Key used from a browser origin it does not allow
403source_restricted Exchange data not redistributed
403https_required https required
429rate_limited Per-minute limit reachedretry
429daily_limit_exceeded Daily limit reachedretry
429stream_limit Too many open streamsretry
500internal_error Internal errorretry

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/whales?sort=size&limit=20"

Example response

HTTP 200Real data from 2026-10-27 13:10 UTC

{
  "data": [
    {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "label": "Abraxas Capital (reported)",
      "labelSource": "https://info.arkm.com/research/abraxas-capital-still-shorting-500m-of-crypto",
      "accountValue": 141229571.24,
      "pnlMonth": 122795733.29,
      "pnlAllTime": 195588125.05,
      "positionsUsd": 707092087.02,
      "positionCount": 25,
      "top": {
        "coin": "ETH",
        "side": "short",
        "usd": 247633252.94,
        "leverage": 5,
        "liqPx": 3743.37777395,
        "liqDistance": 0.607089617
      },
      "liquidations": 0,
      "updatedAt": "2026-10-27T13:10:10.972Z"
    },
    {
      "address": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
      "label": null,
      "labelSource": null,
      "accountValue": 123993441.35,
      "pnlMonth": 100514969.15,
      "pnlAllTime": 146855674.72,
      "positionsUsd": 589886257.5,
      "positionCount": 32,
      "top": {
        "coin": "BTC",
        "side": "short",
        "usd": 201675393.64,
        "leverage": 5,
        "liqPx": 126573.437539,
        "liqDistance": 0.5779666331
      },
      "liquidations": 0,
      "updatedAt": "2026-10-27T13:09:54.879Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:10.972Z",
    "source": "hyperliquid",
    "sources": [
      "hyperliquid"
    ],
    "plan": "api_dev",
    "delayMinutes": 0,
    "commercial": false,
    "license": {
      "id": "internal",
      "display": false,
      "attributionRequired": false,
      "attribution": null,
      "redistribution": false,
      "mauCap": null,
      "terms": "https://blockmetric.io/terms#api-license"
    },
    "attribution": {
      "text": "Data by Blockmetric · Source: Blockmetric Research",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-10-27T13:14:00.000Z"
    }
  }
}

More options: open in the explorer · SDK method whales() / whales()

Code snippets in these docs are licensed under MIT-0: copy them into your own code without attribution. The SDKs, CLI and MCP server will be, once published, Apache-2.0; the name Blockmetric is not licensed (forks must be renamed). Data from the API is governed by the API terms; third-party exchange data by the exchange’s terms.