Contents

Cluster hit rates (scoreboard)

The cluster scoreboard: how often big liquidation clusters of the tracked Hyperliquid positions were reached by the price within 4, 24 and 72 hours, per coin (first row ALL = every coin), with the number of scored clusters, the median time to the touch and the median distance.

GET/api/v1/scoreboardEvery key

Description

A cluster counts for a horizon only once it is at least that old. With coin: also the big clusters of its liquidation map now (same rule as the observations: within 15 % of the mark, the 3 largest buckets of at least $5M) and, for each, how often past clusters of the same coin, side and distance band (0 to 1 %, 1 to 2 %, 2 to 3 %, 3 to 5 %, 5 to 10 %, 10 to 15 %) were reached: n, reached, rate and a 95 % Wilson interval. Below 10 scored clusters there is no rate (only reached of n), below 30 small: true; when the coin has fewer than 10 at 24 hours, scope all_coins uses the same side and band over every coin. Real computed statistics from our stored observations (method); a lower bound, because wicks between two 30-second price samples are not seen. Past results do not predict prices.

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 /scoreboard
Parameter	Description
`coin`string	Optional: one coin, with the hit rates of its current clusters.
`limit`integer	Number of items, default 50, clamped to 1–500.1–500 · default 50

Response fields

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

Response fields of /scoreboard
Field	Description
`method`string	How clusters are recorded and scored.
`rules`object	The fixed rules behind the numbers.
`rules.minUsd`number	Smallest recorded cluster (USD).
`rules.topN`integer	Clusters recorded per coin and side at most (the largest buckets).
`rules.rangePct`number	Clusters within this many percent of the mark are recorded.
`rules.repeatHours`integer	The same bucket is recorded at most once per this many hours.
`rules.horizons[]`array of integer	Horizons in hours.
`rules.minSample`integer	Below this many scored clusters no rate is given.
`rules.smallSample`integer	Below this many scored clusters a rate is flagged small.
`rules.distanceBands[]`array of string	Distance bands of the comparison (percent from the mark to the near edge).
`coins[]`array of objects	Per coin, most scored clusters first (ALL first without coin).
`coins[].coin`string	Coin, or ALL for every coin.
`coins[].since`string (ISO 8601) · nullable	First observation.
`coins[].horizons[]`array of objects	One entry per horizon (4, 24, 72 hours).
`coins[].horizons[].horizonHours`integer	Horizon in hours.
`coins[].horizons[].clusters`integer	Scored clusters (observed at least the horizon ago).
`coins[].horizons[].reached`integer	Of those, touched by the price within the horizon.
`coins[].horizons[].hitRate`number · nullable	reached / clusters (fraction).
`coins[].horizons[].medianMinutesToReach`number · nullable	Median minutes to the touch over the reached ones.
`coins[].horizons[].medianDistancePct`number · nullable	Median distance from the mark in percent.
`current`object · nullable	With coin: the big clusters of its liquidation map now and how often similar past ones were reached; null without coin.
`current.coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`current.mark`number · nullable	Hyperliquid mark now.
`current.mapUpdatedAt`string (ISO 8601) · nullable	Time of the current liquidation map.
`current.clusters[]`array of objects	The big clusters of the liquidation map now (same rule as the recorded ones).
`current.clusters[].side`"long" \| "short"	Position side (for liquidations: the side of the liquidated position).
`current.clusters[].bucketPx`number	Lower edge of the bucket (USD).
`current.clusters[].bucketTop`number	Upper edge of the bucket (USD).
`current.clusters[].usd`number	Liquidations in the bucket (USD).
`current.clusters[].positions`integer	Tracked positions in the bucket.
`current.clusters[].distancePct`number	Percent from the mark to the near edge of the bucket.
`current.clusters[].rank`integer	1 = the largest of its coin now.
`current.clusters[].distanceBand`string	Distance band of the comparison.
`current.clusters[].scope`"coin" \| "all_coins"	coin = past clusters of this coin; all_coins = this coin had fewer than minSample scored at 24 hours, so every coin (same side and band).
`current.clusters[].horizons[]`array of objects	How often past clusters like it were reached, per horizon.

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/scoreboard?coin=BTC"

Example response

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

{
  "data": {
    "method": "Every 15 minutes Blockmetric takes the liquidation map of the tracked Hyperliquid positions of each coin (real positions, not a model). Within ±15% of the mark it ranks the buckets by USD: long liquidations below the mark, short liquidations above it. The 3 largest buckets that hold at least $5M each are recorded as \"big clusters\" with the distance from the mark to the near edge of the bucket. The same bucket (coin, side, price) is recorded at most once per 24 hours. A cluster counts as reached when the Hyperliquid mark price touches the bucket (longs: mark at or below the top edge; shorts: mark at or above the lower edge). The mark is sampled every 30 seconds; the time of the touch comes from these samples while the collector runs, otherwise from the stored 5-minute highs/lows of the same samples (time rounded to the 5-minute bucket; the bucket in which the cluster was observed is skipped). Wicks between two samples are not seen, so reach rates are a lower bound. A horizon (4 h, 24 h, 72 h) is counted only for clusters observed at least that long ago, so open observations never inflate the hit rate. Observations are checked for 72 hours. Past results do not predict future prices; no investment advice.",
    "rules": {
      "minUsd": 5000000,
      "topN": 3,
      "rangePct": 15,
      "repeatHours": 24,
      "horizons": [
        4,
        24
      ],
      "minSample": 10,
      "smallSample": 30,
      "distanceBands": [
        "0–1%",
        "1–2%"
      ]
    },
    "coins": [
      {
        "coin": "BTC",
        "since": "2026-11-02T15:15:44.592Z",
        "horizons": [
          {
            "horizonHours": 4,
            "clusters": 12,
            "reached": 0,
            "hitRate": 0,
            "medianMinutesToReach": null,
            "medianDistancePct": 11.7975
          },
          {
            "horizonHours": 24,
            "clusters": 8,
            "reached": 0,
            "hitRate": 0,
            "medianMinutesToReach": null,
            "medianDistancePct": 11.7975
          }
        ]
      }
    ],
    "current": {
      "coin": "BTC",
      "mark": 77584,
      "mapUpdatedAt": "2026-11-03T19:58:47.173Z",
      "clusters": [
        {
          "side": "long",
          "bucketPx": 75500,
          "bucketTop": 76000,
          "usd": 92867247,
          "positions": 122,
          "distancePct": 2.042,
          "rank": 1,
          "distanceBand": "2–3%",
          "scope": "all_coins",
          "horizons": [
            {
              "horizonHours": 4,
              "n": 6,
              "reached": 3,
              "rate": null,
              "ci": null,
              "small": false
            },
            {
              "horizonHours": 24,
              "n": 4,
              "reached": 2,
              "rate": null,
              "ci": null,
              "small": false
            }
          ]
        },
        {
          "side": "short",
          "bucketPx": 88500,
          "bucketTop": 89000,
          "usd": 79097098,
          "positions": 18,
          "distancePct": 14.07,
          "rank": 2,
          "distanceBand": "10–15%",
          "scope": "all_coins",
          "horizons": [
            {
              "horizonHours": 4,
              "n": 12,
              "reached": 0,
              "rate": 0,
              "ci": [
                0,
                0.2425007575
              ],
              "small": true
            },
            {
              "horizonHours": 24,
              "n": 6,
              "reached": 0,
              "rate": null,
              "ci": null,
              "small": false
            }
          ]
        }
      ]
    }
  },
  "meta": {
    "updatedAt": "2026-11-03T19:58:47.173Z",
    "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 scoreboard() / scoreboard()

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.