Contents

Liquidation totals

Liquidation totals of the last hours (default 24): long/short USD and count, per venue, the 50 coins with the most USD, the largest single liquidation and an hourly series.

GET/api/v1/liquidations/summaryEvery key

Description

CEX totals are what the venues report (they undercount); coveredSince tells from when every venue was collected, and the series starts at the first covered hour (meta.warnings names the cut). Licence review: totals, per-venue sums and the series include every venue (our own aggregates), except that byVenue leaves out a withheld venue whose sum holds a single liquidation (that sum would be the liquidation itself; the totals still count it); largest is a single liquidation of a venue the API serves.

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 /liquidations/summary
Parameter	Description
`coin`string	Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.
`hours`integer	Look-back window in hours, default 24, clamped to 1–26280 (1095 days; single events 120 days, older hours are hourly sums, see hourlySumsBefore; liquidations of $10,000 or more are kept 3 years for largest) and to the plan history (free key 30 days, keyless 24 h).1–26280 · default 24

Response fields

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

Response fields of /liquidations/summary
Field	Description
`hours`number	Window in hours.
`totalUsd`number	Total (USD).
`longUsd`number	Long positions liquidated (USD).
`shortUsd`number	Short positions liquidated (USD).
`count`integer	Number of items (liquidations, positions …) in the group.
`byVenue[]`array of objects	Split per venue.
`byVenue[].venue`string	Trading venue the row comes from.
`byVenue[].longUsd`number	Long (USD).
`byVenue[].shortUsd`number	Short (USD).
`byVenue[].count`integer	Number of items (liquidations, positions …) in the group.
`byCoin[]`array of objects	The 50 coins with the most USD.
`byCoin[].coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`byCoin[].longUsd`number	Long (USD).
`byCoin[].shortUsd`number	Short (USD).
`byCoin[].count`integer	Number of items (liquidations, positions …) in the group.
`largest`object · nullable	Largest single liquidation in the window (of a venue the API serves), null when there is none.
`largest.id`integer	Stable id of the item; on paginated feeds the order key together with ts.
`largest.ts`string (ISO 8601)	Time of the event (ISO 8601 UTC).
`largest.venue`"hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx"	Trading venue.
`largest.coin`string	Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
`largest.side`"long" \| "short" · nullable	Side of the liquidated position.
`largest.price`number · nullable	Fill price.
`largest.qty`number · nullable	Quantity in coins.
`largest.usd`number · nullable	Notional (USD).
`series[]`array of objects	Hourly series, oldest → newest. null = the hour is not covered (before coveredSince, a CEX stream was silent for more than 30 min inside it, or the collector was offline in it); 0 = covered, nothing liquidated.
`series[].t`string (ISO 8601)	Start of the UTC hour.
`series[].longUsd`number · nullable	Long; null = hour not covered (USD).
`series[].shortUsd`number · nullable	Short; null = hour not covered (USD).
`coveredSince`string (ISO 8601) · nullable	From when every venue stream was collected (totals before that are incomplete).
`updatedAt`string (ISO 8601) · nullable	Newest stored liquidation in the window.
`hourlySumsBefore`string (ISO 8601) · nullable	Liquidations before this time are kept as hourly sums only (single events 120 days, then hourly sums): they count in totals, per venue / coin and the series. Of those hours the single liquidations of $10,000 or more are kept 3 years: largest is the largest single event after this time or, when bigger, the largest of $10,000 or more before it. null = no compacted hours in the window.
`offlineMinutes`integer	Minutes of the window in which the collector was offline: no data was collected then, so those liquidations are missing from every total. Absent when 0.

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

Liquidations (reported totals) (how it is computed and its limits)

Request

curl -s -H "X-Blockmetric-Access: public" \
  "https://api.blockmetric.io/v1/liquidations/summary?hours=24"

Example response

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

{
  "data": {
    "hours": 24,
    "totalUsd": 87626913.95,
    "longUsd": 45040168.79,
    "shortUsd": 42586745.16,
    "count": 41720,
    "byVenue": [
      {
        "venue": "binance",
        "longUsd": 36832351.85,
        "shortUsd": 32523143.65,
        "count": 31025
      },
      {
        "venue": "bybit",
        "longUsd": 7730566.19,
        "shortUsd": 7924491.54,
        "count": 10689
      }
    ],
    "byCoin": [
      {
        "coin": "BTC",
        "longUsd": 10729795.17,
        "shortUsd": 9543197.16,
        "count": 1467
      },
      {
        "coin": "ETH",
        "longUsd": 5920035.9,
        "shortUsd": 8695988.38,
        "count": 1272
      }
    ],
    "largest": {
      "id": 240641,
      "ts": "2026-10-26T15:21:04.781Z",
      "venue": "hyperliquid",
      "coin": "BTC",
      "side": "short",
      "price": 80736.4290138,
      "qty": 22.9291,
      "usd": 1851213.65
    },
    "series": [
      {
        "t": "2026-10-26T13:00:00.000Z",
        "longUsd": 9339543.97,
        "shortUsd": 1113072.12
      },
      {
        "t": "2026-10-26T14:00:00.000Z",
        "longUsd": 2025809.46,
        "shortUsd": 3477513.42
      }
    ],
    "coveredSince": "2026-10-23T00:27:23.214Z",
    "updatedAt": "2026-10-27T13:12:16.218Z",
    "hourlySumsBefore": null
  },
  "meta": {
    "updatedAt": "2026-10-27T13:12:16.218Z",
    "source": "hyperliquid,binance,bybit",
    "sources": [
      "hyperliquid",
      "binance"
    ],
    "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 · Binance · Bybit",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-10-27T13:14:00.000Z"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}

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

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

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.