Contents

Wallets with their liquidation price in a band

Tracked Hyperliquid wallets whose position in this coin has its liquidation price in a band right now: size, side, leverage, liquidation price and its signed distance from the mark (liqDistance, fraction), with a link to the wallet page (url).

GET/api/v1/heatmap/{coin}/walletsEvery key

Description

The same positions the live heatmap columns are built from (the newest poll of each wallet, minutes old; a long whose liquidation price is already at or above the mark, or a short at or below it, is left out as on the heatmap). Reconstructed or daily columns have no wallets: wallets are listed for now only. Ask for one band with lo and hi, the heatmap row holding a price with price, or the N largest levels above and below the mark of the current liquidation map with clusters (the default, clusters=3, when none of them is given; each with its wallets; longLevelUsd / shortLevelUsd = the USD of that level in the map). positions, longUsd and shortUsd count every tracked position in the band, wallets lists the largest (limit). Only wallets we track, not every account on Hyperliquid. Same plan rule as /liqmap/{coin}.

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 /heatmap/{coin}/wallets
Parameter	Description
`coin`string · pathrequired	Coin name, e.g. BTC (case-insensitive).
`lo`number	Lower edge of the band (USD, inclusive). Needs hi; the band is at most 20 % of the price wide.≥ 0
`hi`number	Upper edge of the band (USD, exclusive). Needs lo.≥ 0
`price`number	Instead of lo / hi: the heatmap row (0.5 % bucket of the liquidation map) holding this price.≥ 0
`clusters`integer	Instead of a band: the N (1 to 10) largest levels above and below the mark of the current liquidation map, each with its wallets. Default 3 when neither lo / hi nor price is given.1–10 · default 3
`side`string	long \| short (optional).one of long, short
`minUsd`number	Minimum position notional in USD, default 0.≥ 0 · default 0
`limit`integer	Number of items, default 20, clamped to 1–100.1–100 · default 20

Response fields

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

Response fields of /heatmap/{coin}/wallets
Field	Description
`coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`mark`number · nullable	Hyperliquid mark now.
`bucketSize`number · nullable	Row width of the current liquidation map (USD).
`mapUpdatedAt`string (ISO 8601) · nullable	Time of the current liquidation map.
`bands[]`array of objects	One band (lo / hi or price), or the clusters largest levels above the mark, then below it.
`bands[].priceLo`number	Lower edge of the band (USD, inclusive).
`bands[].priceHi`number	Upper edge of the band (USD, exclusive).
`bands[].distance`number · nullable	Signed distance from the mark to priceLo, fraction (−0.03 = 3 % below).
`bands[].positions`integer	Tracked positions with their liquidation price in the band now (all of them).
`bands[].longUsd`number	Notional of those long positions (USD).
`bands[].shortUsd`number	Notional of those short positions (USD).
`bands[].updatedAt`string (ISO 8601) · nullable	Newest poll among those positions.
`bands[].wallets[]`array of objects	The largest of them, largest first (limit).
`bands[].wallets[].address`string	Hyperliquid address, lowercase.
`bands[].wallets[].label`string · nullable	Wallet label (leaderboard display name).
`bands[].wallets[].side`"long" \| "short"	Position side (for liquidations: the side of the liquidated position).
`bands[].wallets[].positionUsd`number	Notional (USD).
`bands[].wallets[].size`number	Size in coins.
`bands[].wallets[].entryPx`number · nullable	Entry price.
`bands[].wallets[].leverage`number · nullable	Leverage of the position (notional / margin).
`bands[].wallets[].leverageType`string · nullable	cross \| isolated
`bands[].wallets[].liqPx`number · nullable	Liquidation price.
`bands[].wallets[].liqDistance`number · nullable	Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark).
`bands[].wallets[].accountValue`number · nullable	Account value (USD).
`bands[].wallets[].updatedAt`string (ISO 8601)	When the wallet was last read.
`bands[].wallets[].url`string	The wallet page on the website.
`bands[].longLevelUsd`number	clusters only: long liquidations of this level in the current liquidation map (USD).
`bands[].shortLevelUsd`number	clusters only: short liquidations of this level in the current liquidation map (USD).

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
404not_found Not found
429rate_limited Per-minute limit reachedretry
429daily_limit_exceeded Daily limit reachedretry
429stream_limit Too many open streamsretry
500internal_error Internal errorretry

Methodology

Liquidation clusters (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/heatmap/BTC/wallets?clusters=3&limit=5"

Example response

HTTP 200Real data from 2026-11-03 19:59 UTC

{
  "data": {
    "coin": "BTC",
    "mark": 77584,
    "bucketSize": 500,
    "mapUpdatedAt": "2026-11-03T19:58:47.173Z",
    "bands": [
      {
        "priceLo": 92000,
        "priceHi": 92500,
        "distance": 0.1858115075,
        "longLevelUsd": 0,
        "shortLevelUsd": 114577661.94,
        "positions": 12,
        "longUsd": 0,
        "shortUsd": 114577910.44,
        "updatedAt": "2026-11-03T19:59:11.958Z",
        "wallets": [
          {
            "address": "0xfc27136e42af1732ddc9ce2605ea9bff1b959d9d",
            "label": null,
            "side": "short",
            "positionUsd": 111263508.71,
            "size": 1435.54889,
            "entryPx": 79888,
            "leverage": 25,
            "leverageType": "cross",
            "liqPx": 92384.6929626,
            "liqDistance": 0.1907699134,
            "accountValue": 23846598.75,
            "updatedAt": "2026-11-03T19:57:42.201Z",
            "url": "https://blockmetric.io/wallet/0xfc27136e42af1732ddc9ce2605ea9bff1b959d9d"
          },
          {
            "address": "0x4180847debea25583c4dc0b925c6b1c750d34bf7",
            "label": "ole",
            "side": "short",
            "positionUsd": 2715758.5,
            "size": 35,
            "entryPx": 78934.4,
            "leverage": 40,
            "leverageType": "cross",
            "liqPx": 92242.0581887,
            "liqDistance": 0.1889314574,
            "accountValue": 250400.39,
            "updatedAt": "2026-11-03T19:59:11.958Z",
            "url": "https://blockmetric.io/wallet/0x4180847debea25583c4dc0b925c6b1c750d34bf7"
          }
        ]
      },
      {
        "priceLo": 62000,
        "priceHi": 62500,
        "distance": -0.200866158,
        "longLevelUsd": 113250355.87,
        "shortLevelUsd": 0,
        "positions": 28,
        "longUsd": 111378261.78,
        "shortUsd": 0,
        "updatedAt": "2026-11-03T19:58:59.899Z",
        "wallets": [
          {
            "address": "0xefe4c06b6d310978bead596e1798a4fc1d9d194b",
            "label": null,
            "side": "long",
            "positionUsd": 70834198.81,
            "size": 912.91772,
            "entryPx": 83284.8,
            "leverage": 20,
            "leverageType": "cross",
            "liqPx": 62107.8818946,
            "liqDistance": -0.1994756407,
            "accountValue": 18386519.23,
            "updatedAt": "2026-11-03T19:58:59.899Z",
            "url": "https://blockmetric.io/wallet/0xefe4c06b6d310978bead596e1798a4fc1d9d194b"
          },
          {
            "address": "0xebe837cd345469cbc5d6e1fd3d15ee5079ac885f",
            "label": null,
            "side": "long",
            "positionUsd": 26705220.97,
            "size": 344.30805,
            "entryPx": 84266,
            "leverage": 5,
            "leverageType": "isolated",
            "liqPx": 62244.6585515,
            "liqDistance": -0.1977126914,
            "accountValue": 5541775.68,
            "updatedAt": "2026-11-03T19:58:16.650Z",
            "url": "https://blockmetric.io/wallet/0xebe837cd345469cbc5d6e1fd3d15ee5079ac885f"
          }
        ]
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-11-03T19:59:11.958Z",
    "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-11-03T20:00:00.000Z"
    }
  }
}

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

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.