Contents

Whale stop / TP map

Stop / take-profit map of the largest tracked Hyperliquid wallets (default the 150 largest by open notional, open orders read every ~40 min): with coin, the trigger orders per price bucket (sell stops below / buy stops above the price, TPs separately), a heatmap overlay (overlay: price, label, side, usd) and coverage; without coin, a per-coin table with the largest stop cluster below and above the price.

GET/api/v1/whales/stopsEvery key

Description

Only these wallets and only the main dex, not the whole market. The free key covers BTC, ETH and HYPE.

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/stops
Parameter	Description
`coin`string	Coin for the bucket map and the overlay (optional; without it: per-coin table).

Response fields

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

Response fields of /whales/stops
Field	Description
`coin`string · nullable	The coin of `map` / `overlay`; null = per-coin table.
`map`object · nullable	Stop / take-profit buckets of the coin (with ?coin=), else null.
`map.coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`map.mark`number · nullable	Hyperliquid mark.
`map.bucketSize`number	Bucket width (same rule as the liquidation map).
`map.buckets[]`array of objects	Buckets within ±30 % of the mark, ascending.
`map.buckets[].px`number	Lower edge of the price bucket.
`map.buckets[].top`number	Upper edge.
`map.buckets[].stopSellUsd`number	Sell stop orders (trigger when the price falls to them) (USD).
`map.buckets[].stopBuyUsd`number	Buy stop orders (trigger when the price rises to them) (USD).
`map.buckets[].tpSellUsd`number	Sell take-profit orders (USD).
`map.buckets[].tpBuyUsd`number	Buy take-profit orders (USD).
`map.buckets[].orders`integer	Number of orders.
`map.buckets[].wallets`integer	Number of distinct wallets.
`map.totals`object	Sums over the rows of this object.
`map.totals.stopSellUsd`number	Sell stops (USD).
`map.totals.stopBuyUsd`number	Buy stops (USD).
`map.totals.tpSellUsd`number	Sell TPs (USD).
`map.totals.tpBuyUsd`number	Buy TPs (USD).
`map.totals.limitBuyUsd`number	Resting buy limits (USD).
`map.totals.limitSellUsd`number	Resting sell limits (USD).
`map.totals.orders`integer	Number of orders.
`map.totals.wallets`integer	Number of distinct wallets.
`map.coverage`object	Which wallets the stop map covers (the largest tracked wallets in the rotation, main dex only).
`map.coverage.walletsFresh`integer	Wallets whose open orders were read within the freshness limit (default 3 h).
`map.coverage.walletsWithOrders`integer	Of those, wallets with at least one order (on this coin, when a coin is given).
`map.coverage.oldestFetch`string (ISO 8601) · nullable	Oldest open-orders read among the covered wallets.
`map.coverage.newestFetch`string (ISO 8601) · nullable	Newest open-orders read among the covered wallets.
`map.updatedAt`string (ISO 8601) · nullable	Newest order read.
`overlay[]`array of objects	Items to draw on top of the liquidation heatmap.
`overlay[].price`number	Bucket middle.
`overlay[].label`string	Plain-language label.
`overlay[].side`"long" \| "short"	Position side (for liquidations: the side of the liquidated position).
`overlay[].usd`number	Orders in the bucket (USD).
`table[]`array of objects	Per-coin table (without coin), largest first.
`table[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`table[].mark`number · nullable	Hyperliquid mark price.
`table[].stopSellUsd`number	Sell stops (USD).
`table[].stopBuyUsd`number	Buy stops (USD).
`table[].tpSellUsd`number	Sell TPs (USD).
`table[].tpBuyUsd`number	Buy TPs (USD).
`table[].orders`integer	Number of orders.
`table[].wallets`integer	Number of distinct wallets.
`table[].nearestBelow`object · nullable	Largest sell-stop bucket below the mark.
`table[].nearestBelow.px`number	Price (lower edge of a price bucket where the object is a bucket).
`table[].nearestBelow.usd`number	Sell stops (USD).
`table[].nearestBelow.distance`number	Fraction of the mark.
`table[].nearestAbove`object · nullable	Largest buy-stop bucket above the mark.
`table[].nearestAbove.px`number	Price (lower edge of a price bucket where the object is a bucket).
`table[].nearestAbove.usd`number	Buy stops (USD).
`table[].nearestAbove.distance`number	Fraction of the mark.
`limited`boolean	Rows were left out by the plan (free key: BTC, ETH, HYPE).
`coverage`object	Which wallets the stop map covers (the largest tracked wallets in the rotation, main dex only).
`coverage.walletsFresh`integer	Wallets whose open orders were read within the freshness limit (default 3 h).
`coverage.walletsWithOrders`integer	Of those, wallets with at least one order (on this coin, when a coin is given).
`coverage.oldestFetch`string (ISO 8601) · nullable	Oldest open-orders read among the covered wallets.
`coverage.newestFetch`string (ISO 8601) · nullable	Newest open-orders read among the covered wallets.
`method`string	How the figures are computed, in plain words.

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

Methodology

Whale stops and take-profits (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/whales/stops?coin=BTC"

Example response

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

{
  "data": {
    "coin": "BTC",
    "map": {
      "coin": "BTC",
      "mark": 80213,
      "bucketSize": 500,
      "buckets": [
        {
          "px": 73000,
          "top": 73500,
          "stopSellUsd": 23279637.22,
          "stopBuyUsd": 0,
          "tpSellUsd": 0,
          "tpBuyUsd": 0,
          "orders": 1,
          "wallets": 1
        },
        {
          "px": 76500,
          "top": 77000,
          "stopSellUsd": 0,
          "stopBuyUsd": 0,
          "tpSellUsd": 0,
          "tpBuyUsd": 10789254.77,
          "orders": 1,
          "wallets": 1
        }
      ],
      "totals": {
        "stopSellUsd": 42283248.92,
        "stopBuyUsd": 61340173,
        "tpSellUsd": 8287979.05,
        "tpBuyUsd": 12123931.02,
        "limitBuyUsd": 73930103.43,
        "limitSellUsd": 28667291.83,
        "orders": 393,
        "wallets": 24
      },
      "coverage": {
        "walletsFresh": 154,
        "walletsWithOrders": 24,
        "oldestFetch": "2026-10-27T10:26:24.871Z",
        "newestFetch": "2026-10-27T13:12:14.393Z"
      },
      "updatedAt": "2026-10-27T13:10:39.449Z"
    },
    "overlay": [
      {
        "price": 99750,
        "side": "short",
        "usd": 40043891.56,
        "label": "whale stops · buy · 1 wallet"
      },
      {
        "price": 89250,
        "side": "long",
        "usd": 8287979.05,
        "label": "whale TPs · sell · 1 wallet"
      }
    ],
    "table": [],
    "limited": false,
    "coverage": {
      "walletsFresh": 154,
      "walletsWithOrders": 54,
      "oldestFetch": "2026-10-27T10:26:24.871Z",
      "newestFetch": "2026-10-27T13:12:14.393Z"
    },
    "method": "Open trigger orders (stop-loss, stop-entry, take-profit) of the largest tracked Hyperliquid wallets, read from Hyperliquid’s public order data on a slow rotation (default: the 150 largest by open notional, each every ~40 min). Prices are trigger prices; sell orders sit where longs would exit (usually below the price), buy orders where shorts would. Only these wallets and only the main dex; orders can be changed or cancelled at any time."
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:39.449Z",
    "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 whaleStops() / whale_stops()

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.