Contents

Coverage and freshness

Coverage and freshness: tracked wallets and positions, markets per venue, event counts, liquidation-map size and the last run of every collector job.

GET/api/v1/statsEvery key

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

No parameters.

Response fields

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

Response fields of /stats
Field	Description
`wallets`object	Number of distinct wallets.
`wallets.total`integer	Total number.
`wallets.polled`integer	Wallets read at least once.
`wallets.withPositions`integer	Wallets with at least one open position.
`positions`object	Number of positions.
`positions.count`integer	Number of items (liquidations, positions …) in the group.
`positions.totalUsd`number	Open notional (USD).
`positions.longUsd`number	Long (USD).
`positions.shortUsd`number	Short (USD).
`positions.coins`integer	Number of coins.
`markets[]`array of objects	Markets per venue.
`markets[].venue`"hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx"	Trading venue.
`markets[].coins`integer	Number of coins.
`markets[].updatedAt`string (ISO 8601) · nullable	Newest data time of this item (ISO 8601 UTC).
`events`object	Events of this view (newest first) or their count.
`events.radar`integer	Stored radar events.
`events.positionEvents`integer	Stored whale position changes.
`events.liquidations24h`integer	Liquidations in the last 24 hours.
`events.liquidations24hUsd`number	Liquidations in the last 24 h (USD).
`liqLevels`object	Liquidation map: coins, price buckets and the last update.
`liqLevels.coins`integer	Number of coins.
`liqLevels.buckets`integer	Price buckets.
`liqLevels.updatedAt`string (ISO 8601) · nullable	Newest data time of this item (ISO 8601 UTC).
`jobs[]`array of objects	Last successful run of each collector job behind a public data feed, newest first (internal maintenance jobs are not listed since 1.14.0).
`jobs[].job`string	Collector job id.
`jobs[].lastRun`string (ISO 8601)	Last successful run.
`jobs[].feed`string	Public data feed the job belongs to: the id in GET /status feeds[], whose label is its plain-English name (API 1.14.0).
`focus`object	Heatmap, long/short and whale-label tables.
`focus.heatmapSnapshots`integer	Stored heatmap snapshots.
`focus.heatmapCoins`integer	Coins with heatmap snapshots.
`focus.heatmapUpdatedAt`string (ISO 8601) · nullable	Newest heatmap snapshot.
`focus.longShortRows`integer	Stored long/short rows.
`focus.longShortUpdatedAt`string (ISO 8601) · nullable	Newest long/short row.
`focus.whaleLabels`integer	Public wallet labels with a cited source.
`focus.clusterObservations`integer	Liquidation clusters observed for the hit-rate statistic.
`focus.clustersReached`integer	Of those, clusters the price reached.
`focus.telegramCards`integer	Cards posted to the public Telegram channel.

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

Open interest (how it is computed and its limits)

Request

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

Example response

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

{
  "data": {
    "wallets": {
      "total": 49071,
      "polled": 49053,
      "withPositions": 9173
    },
    "positions": {
      "count": 41506,
      "totalUsd": 12283699248.81,
      "longUsd": 5911845552.64,
      "shortUsd": 6371853696.17,
      "coins": 295
    },
    "markets": [
      {
        "venue": "hyperliquid",
        "coins": 347,
        "updatedAt": "2026-10-27T13:11:52.327Z"
      },
      {
        "venue": "binance",
        "coins": 392,
        "updatedAt": "2026-10-27T13:11:50.718Z"
      }
    ],
    "events": {
      "radar": 5353,
      "positionEvents": 225062,
      "liquidations24h": 41720,
      "liquidations24hUsd": 87626913.95
    },
    "liqLevels": {
      "coins": 257,
      "buckets": 4516,
      "updatedAt": "2026-10-27T13:12:06.932Z"
    },
    "jobs": [
      {
        "job": "intel_live",
        "feed": "hl-positions",
        "lastRun": "2026-10-27T13:12:18.456Z"
      },
      {
        "job": "alerts_onchain",
        "feed": "alerts",
        "lastRun": "2026-10-27T13:12:17.518Z"
      }
    ],
    "focus": {
      "heatmapSnapshots": 62786,
      "heatmapCoins": 120,
      "heatmapUpdatedAt": "2026-10-27T13:10:00.000Z",
      "longShortRows": 56753,
      "longShortUpdatedAt": "2026-10-27T13:10:00.000Z",
      "whaleLabels": 7,
      "clusterObservations": 381,
      "clustersReached": 26,
      "telegramCards": 0
    }
  },
  "meta": {
    "updatedAt": "2026-10-27T13:12:18.456Z",
    "source": "aggregate",
    "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"
    }
  }
}

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

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

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.