Contents

Liquidation map (current)

Liquidation map of one coin from the tracked Hyperliquid positions: USD that would be liquidated per price bucket (longs below the mark, shorts above), plus totals.

GET/api/v1/liqmap/{coin}Every key

Description

404 for unknown coins. Free keys: every coin (as "liquidation levels now" on the web).

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 /liqmap/{coin}
Parameter	Description
`coin`string · pathrequired	Coin name, e.g. BTC (case-insensitive).

Response fields

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

Response fields of /liqmap/{coin}
Field	Description
`coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`mark`number · nullable	Current Hyperliquid mark.
`bucketSize`number · nullable	Width of a price bucket.
`updatedAt`string (ISO 8601) · nullable	Newest data time of this item (ISO 8601 UTC).
`buckets[]`array of objects	Price buckets ascending; long liquidations sit below the mark, short liquidations above it.
`buckets[].px`number	Lower edge of the price bucket.
`buckets[].longUsd`number	Long positions liquidated in this bucket (USD).
`buckets[].shortUsd`number	Short positions liquidated in this bucket (USD).
`buckets[].positions`integer	Positions in the bucket.
`totals`object	Sums over the rows of this object.
`totals.longUsd`number	Total long (USD).
`totals.shortUsd`number	Total short (USD).
`totals.positions`integer	Number of positions.

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)
Liquidation heatmap (real positions) (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/liqmap/BTC"

Example response

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

{
  "data": {
    "coin": "BTC",
    "mark": 80213,
    "bucketSize": 500,
    "updatedAt": "2026-10-27T13:11:35.545Z",
    "buckets": [
      {
        "px": 40000,
        "longUsd": 559491.99,
        "shortUsd": 0,
        "positions": 5
      },
      {
        "px": 40500,
        "longUsd": 1747066.87,
        "shortUsd": 0,
        "positions": 10
      }
    ],
    "totals": {
      "longUsd": 1299628655.09,
      "shortUsd": 713641189.95,
      "positions": 2226
    }
  },
  "meta": {
    "updatedAt": "2026-10-27T13:11:35.545Z",
    "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"
    }
  }
}

Lists shortened to their first items (1 more in the real response).

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

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.