# Blockmetric API reference (v1, 1.24.0)

> Read-only JSON API over HTTPS for crypto derivatives data: liquidation heatmap and levels from real Hyperliquid positions, liquidations, funding, open interest, long/short, whales, order flow and a risk radar. Generated from the OpenAPI document (https://api.blockmetric.io/v1/openapi.json); web version https://blockmetric.io/docs/api.

## Basics

- **Base URL:** https://api.blockmetric.io/v1. Every endpoint is a GET.
- **Auth:** `Authorization: Bearer bm_live_…` or `x-api-key: bm_live_…` (keys on https://blockmetric.io/account/api, headers only; a key in the URL answers 400). Without a key: `X-Blockmetric-Access: public` (free-tier data, 24 h of history, 10/min and 300/day per IP).
- **Envelope:** success `{ "data": …, "meta": { … } }`, error `{ "error": { "code", "message", "doc_url", "request_id" } }`. Branch on `error.code`, never on the message. Unknown fields may be added; ignore them.
- **Units:** times ISO 8601 UTC; money USD; prices in the venue quote currency; funding, distances and every field ending in Pct are fractions (0.01 = 1 %); ratios long / short.
- **Pagination:** feeds take `limit` + `cursor`; pass `meta.nextCursor` until it is null. Cursors are signed; do not edit them.
- **Caching:** every 200 has an ETag; send If-None-Match to get 304 without a body.
- **Rate limits** (per account, all keys together, UTC day): Free 10/min and 1,000/day · Pro 20/min and 5,000/day · Desk 30/min and 10,000/day · API Dev 60/min and 50,000/day · API Pro 300/min and 500,000/day. 429 carries Retry-After.
- **History by plan:** No key 24 h · Free 30 days · Pro 365 days · Desk 1095 days · API Dev 365 days · API Pro 1095 days.
- **Versioning:** /api/v1 changes only additively; breaking changes ship as /api/v2 with at least six months of overlap and Deprecation / Sunset headers.

### meta

| Field | Type | Description |
|---|---|---|
| `updatedAt` | string (ISO 8601), nullable | Newest data timestamp in the response; null when there is no data yet. |
| `source` | string | Venues / public sources the data comes from, comma-separated. |
| `sources` | array | Enabled data sources this response is built from (ids as on /methodology#sources). Name them next to the data (attribution). |
| `plan` | "free" \| "pro" \| "desk" \| "api_dev" \| "api_pro" | The caller's plan. |
| `delayMinutes` | integer | Feed delay of the caller's plan in minutes (0 = real time). |
| `commercial` | boolean | Whether the caller's licence allows commercial use (with attribution). |
| `license` | object | What the caller may do with this response (see /terms#api-license). |
| `attribution` | object | Ready-made credit (API 1.13.0). Display licences show it next to the data (license.attributionRequired). |
| `access` | object | The history window of the caller’s plan (API 1.14.0): rows before historyFrom are not served. |
| `nextCursor` | string, nullable | Paginated lists only: pass as ?cursor= for the next page; null on the last page. |
| `nextUrl` | string (URL), nullable | Paginated lists only: the complete URL of the next page (same parameters + cursor); null on the last page. |
| `nextAfter` | integer | Forward polling (?after=) only: pass as ?after= on the next poll: the id of the newest row returned, else the id that was given. |
| `warnings` | array | Only when the request was not served exactly as asked (API 1.14.0); absent otherwise. |
| `restricted` | array | Only on endpoints the licence review touches: exchanges whose raw rows are withheld from this response (aggregates stay). Absent once their data is licensed. |

### Errors

| HTTP | Code | Meaning | Retry |
|---|---|---|---|
| 400 | `invalid_param` | A query or path parameter has the wrong type or an unknown value, the parameter itself is unknown to the endpoint, or a cursor is malformed. error.param names the parameter. Numeric values outside their range are clamped, not rejected; meta.warnings names them. Also returned when an API key is sent in the URL (?api_key=…): keys are only accepted in headers. | no |
| 401 | `unauthorized` | No key was sent, or the key is malformed (checksum mismatch), unknown, revoked or expired. | no |
| 403 | `plan_required` | The key is valid, but the requested data or feature needs a higher plan. | no |
| 403 | `scope_required` | The key is valid, but its scopes do not include this API: a key limited to the Blockmetric Node gateway (scope node) cannot call /api/v1, and a key without the node scope cannot call the node gateway. | no |
| 403 | `ip_not_allowed` | The key is valid, but it is restricted to an IP allowlist and the request came from another address. | no |
| 403 | `origin_not_allowed` | The request carried an API key and an Origin header (it came from a web page), and the key does not list that origin under its allowed browser origins. Keys belong on a server: a key in front-end code is visible to every visitor, who can use up your quota (and overage) and your licence duties travel with it. | no |
| 403 | `source_restricted` | The request asked for raw data of an exchange (single liquidations, trades, order books, tickers, funding or ratios of Binance or Bybit, or candles of a coin that only trades there) that the API does not pass on while the review of the exchange’s terms is pending. Our own figures built from it (sums over venues, totals per hour, spreads) stay available, and meta.restricted names the withheld venues on the endpoints concerned. | no |
| 403 | `https_required` | The request reached the API over plain http. The API only answers over https. | no |
| 404 | `not_found` | Unknown endpoint, unknown coin or a wallet that is not tracked. | no |
| 405 | `method_not_allowed` | The API is read-only: every endpoint answers GET (and HEAD / OPTIONS). The Allow header lists the methods. | no |
| 429 | `rate_limited` | The account used all requests of the current minute (all keys of the account share the limit). | yes |
| 429 | `daily_limit_exceeded` | The account used all requests of the current UTC day. | yes |
| 429 | `stream_limit` | GET /stream only: the account already has the maximum number of live streams of its plan open (API Pro: 2). | yes |
| 500 | `internal_error` | Something failed on our side. No details are exposed. | yes |

Causes and fixes for every code: https://blockmetric.io/developers/errors.

## Endpoints

### GET /markets: Market state of a venue

Latest market state of one venue: mark, oracle, funding (hourly and annualised), open interest, 24h volume, premium, max leverage. Largest open interest first. Licence review: raw rows of Binance and Bybit (single liquidations, prints, order books, tickers, funding and ratios per exchange, exchange candles) are not redistributed through the API while the review of their terms is pending. Asking for such a venue answers 403 source_restricted, and meta.restricted lists the withheld venues. Aggregates (sums over venues, our own figures) stay.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `venue` | query | string | no | hyperliquid \| lighter \| binance \| bybit (okx only while enabled, see /methodology#sources); default hyperliquid. Lighter (a DEX like Hyperliquid) is never withheld. Binance / Bybit: 403 source_restricted during the licence review. (one of hyperliquid, lighter, binance, bybit, okx) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,mark,fundingApr,openInterestUsd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/markets?venue=hyperliquid"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].venue` | "hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx" | Trading venue. |
| `[].coin` | string | Coin name as on Hyperliquid. |
| `[].mark` | number, nullable | Mark price. |
| `[].oracle` | number, nullable | Oracle / index price. |
| `[].fundingHourly` | number, nullable | Hourly funding rate, fraction (0.0001 = 0.01 %/h). |
| `[].fundingApr` | number, nullable | Annualised funding (hourly × 24 × 365), fraction. |
| `[].openInterestUsd` | number, nullable | Open interest (USD). |
| `[].volume24hUsd` | number, nullable | 24h volume (USD). |
| `[].premium` | number, nullable | Mark premium over the oracle, fraction. |
| `[].maxLeverage` | integer, nullable | Maximum leverage. |
| `[].updatedAt` | string (ISO 8601) | Newest data time of this item (ISO 8601 UTC). |

Example response (real data):

```json
{
  "data": [
    {
      "venue": "hyperliquid",
      "coin": "BTC",
      "mark": 80213,
      "oracle": 80233.3,
      "fundingHourly": 0.0000125,
      "fundingApr": 0.1095,
      "openInterestUsd": 3468696429.07,
      "volume24hUsd": 2288160809.64,
      "premium": -0.0002031575,
      "maxLeverage": 40,
      "updatedAt": "2026-10-27T13:11:52.327Z"
    },
    {
      "venue": "hyperliquid",
      "coin": "ETH",
      "mark": 2329.29,
      "oracle": 2330.27,
      "fundingHourly": 0.0000125,
      "fundingApr": 0.1095,
      "openInterestUsd": 2602687934.92,
      "volume24hUsd": 852734460.37,
      "premium": -0.0004162608,
      "maxLeverage": 25,
      "updatedAt": "2026-10-27T13:11:52.327Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:52.327Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/markets

### GET /funding: Cross-venue funding board

Cross-venue funding board: one row per coin with funding of every venue, APR spread between venues and the largest absolute APR of the venues shown. Sorted by Hyperliquid open interest. Licence review: raw rows of Binance and Bybit (single liquidations, prints, order books, tickers, funding and ratios per exchange, exchange candles) are not redistributed through the API while the review of their terms is pending. Asking for such a venue answers 403 source_restricted, and meta.restricted lists the withheld venues. Aggregates (sums over venues, our own figures) stay. aprSpread is then null unless at least 3 venues quote the coin and neither end of the spread is a rate shown here (otherwise it would give an exchange's own rate).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `limit` | query | integer | no | Number of items, default 500, clamped to 1–500. (range 1–500; default 500) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,aprSpread,maxAbsApr (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/funding?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].hlOpenInterestUsd` | number, nullable | Hyperliquid open interest (sort key) (USD). |
| `[].byVenue` | object | Funding per venue; venues without the coin are missing. |
| `[].byVenue.hyperliquid` | object | - |
| `[].byVenue.lighter` | object | - |
| `[].byVenue.binance` | object | - |
| `[].byVenue.bybit` | object | - |
| `[].byVenue.okx` | object | - |
| `[].aprSpread` | number, nullable | Highest minus lowest annualised funding across every venue that quotes the coin (also withheld exchanges), fraction. null with fewer than two venues, and while exchange rows are withheld also unless at least 3 venues quote the coin and neither end of the spread is a rate shown in byVenue (it would give the rate of one exchange). |
| `[].maxAbsApr` | number, nullable | Largest absolute annualised funding of any venue, fraction. |

Example response (real data):

```json
{
  "data": [
    {
      "coin": "BTC",
      "hlOpenInterestUsd": 3468696429.07,
      "byVenue": {
        "hyperliquid": {
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "openInterestUsd": 3468696429.07,
          "mark": 80213,
          "updatedAt": "2026-10-27T13:11:52.327Z"
        }
      },
      "aprSpread": 0,
      "maxAbsApr": 0.1095
    },
    {
      "coin": "ETH",
      "hlOpenInterestUsd": 2602687934.92,
      "byVenue": {
        "hyperliquid": {
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "openInterestUsd": 2602687934.92,
          "mark": 2329.29,
          "updatedAt": "2026-10-27T13:11:52.327Z"
        }
      },
      "aprSpread": 0.053655,
      "maxAbsApr": 0.1095
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:52.327Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/funding

### GET /coins: Hyperliquid coins

Hyperliquid coins with market data, largest open interest first, with the number of tracked positions and whether a liquidation map exists.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,mark,openInterestUsd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/coins"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].mark` | number, nullable | Hyperliquid mark price. |
| `[].openInterestUsd` | number, nullable | Open interest (USD). |
| `[].volume24hUsd` | number, nullable | 24h volume (USD). |
| `[].fundingApr` | number, nullable | Annualised funding, fraction. |
| `[].maxLeverage` | integer, nullable | Maximum leverage the venue allows on this market. |
| `[].trackedPositions` | integer | Tracked positions on this coin. |
| `[].hasLiqMap` | boolean | Whether a liquidation map exists. |

Example response (real data):

```json
{
  "data": [
    {
      "coin": "BTC",
      "mark": 80213,
      "openInterestUsd": 3468696429.07,
      "volume24hUsd": 2288160809.64,
      "fundingApr": 0.1095,
      "maxLeverage": 40,
      "trackedPositions": 3605,
      "hasLiqMap": true
    },
    {
      "coin": "ETH",
      "mark": 2329.29,
      "openInterestUsd": 2602687934.92,
      "volume24hUsd": 852734460.37,
      "fundingApr": 0.1095,
      "maxLeverage": 25,
      "trackedPositions": 2066,
      "hasLiqMap": true
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:52.327Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/coins

### GET /long-short: Long/short positioning

Long/short positioning per coin: Hyperliquid from the tracked positions (USD and wallet counts per side, ratio = longUsd / shortUsd) and the public account ratios of the enabled exchanges (Binance: all accounts, top accounts, top positions; Bybit; OKX) from the last 60 minutes. A switched-off exchange is left out of the row (no key); null means the exchange is on but has no ratio for the coin. Sorted by Hyperliquid open interest. Licence review: the exchanges’ published ratios are their data 1:1 and left out like a switched-off exchange (meta.restricted); rows then cover coins with a Hyperliquid market.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,hl (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/long-short?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].hl` | object, nullable | Hyperliquid from the tracked positions; null when no tracked position exists. |
| `[].hl.longUsd` | number | Tracked long notional (USD). |
| `[].hl.shortUsd` | number | Tracked short notional (USD). |
| `[].hl.longAccounts` | integer | Tracked wallets with a long position. |
| `[].hl.shortAccounts` | integer | Tracked wallets with a short position. |
| `[].hl.ratio` | number, nullable | longUsd / shortUsd. |
| `[].updatedAt` | string (ISO 8601), nullable | Newest data time of this item (ISO 8601 UTC). |
| `[].binance` | object, nullable | Binance published long/short ratios (only while Binance is switched on and licensed for the API). |
| `[].binance.accountRatio` | number, nullable | Long / short accounts. |
| `[].binance.topAccountRatio` | number, nullable | Top traders, accounts. |
| `[].binance.topPositionRatio` | number, nullable | Top traders, positions. |
| `[].bybit` | object, nullable | Bybit published long/short ratio (only while Bybit is switched on and licensed for the API). |
| `[].bybit.accountRatio` | number, nullable | Long / short accounts. |
| `[].okx` | object, nullable | OKX published long/short ratio (only while OKX is switched on and licensed for the API). |
| `[].okx.accountRatio` | number, nullable | Long / short accounts. |

Example response (real data):

```json
{
  "data": [
    {
      "coin": "BTC",
      "hl": {
        "longUsd": 1543688921.02,
        "shortUsd": 1593635392.17,
        "longAccounts": 2351,
        "shortAccounts": 1254,
        "ratio": 0.9686587839
      },
      "updatedAt": "2026-10-27T13:12:18.157Z"
    },
    {
      "coin": "ETH",
      "hl": {
        "longUsd": 1241116739.56,
        "shortUsd": 1262161538.81,
        "longAccounts": 1241,
        "shortAccounts": 825,
        "ratio": 0.9833263821
      },
      "updatedAt": "2026-10-27T13:12:18.393Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:12:18.393Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/long-short

### GET /liquidations: Liquidations feed

Market-wide liquidations (Hyperliquid liquidations of tracked wallets confirmed by their liquidation fills, with time, price and size of the fills; Lighter trades the exchange flags as liquidations; CEX force orders as reported, where licensed), newest first. `side` is the side of the liquidated position. Bots poll forward with `after` (oldest first, meta.nextAfter) instead of paging back. Stored: every single liquidation 120 days, liquidations of $10,000 or more 3 years (older windows list only those; the totals in /liquidations/summary count every liquidation). Licence review: raw rows of Binance and Bybit (single liquidations, prints, order books, tickers, funding and ratios per exchange, exchange candles) are not redistributed through the API while the review of their terms is pending. Asking for such a venue answers 403 source_restricted, and meta.restricted lists the withheld venues. Aggregates (sums over venues, our own figures) stay.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive. |
| `venue` | query | string | no | hyperliquid \| lighter \| binance \| bybit (okx only while enabled, see /methodology#sources) (optional). (one of hyperliquid, lighter, binance, bybit, okx) |
| `side` | query | string | no | long \| short = side of the liquidated position (optional). (one of long, short) |
| `minUsd` | query | number | no | Minimum notional in USD, default 0. (range 0–; default 0) |
| `sinceMinutes` | query | integer | no | Look-back window in minutes, default 60, clamped to the plan history (API Dev 365 days, API Pro 1095 days). (range 1–; default 60) |
| `from` | query | string | no | Window start (ISO 8601, inclusive); replaces sinceMinutes. Clamped to the plan history (meta.warnings says so). |
| `to` | query | string | no | Window end (ISO 8601, exclusive; default now): liquidations before it. |
| `after` | query | integer | no | Forward polling: only liquidations with an id above this one, oldest first (pass meta.nextAfter of the previous poll; without from / sinceMinutes the window is the plan history). Cannot be combined with cursor. (range 0–) |
| `limit` | query | integer | no | Number of items, default 100, clamped to 1–1000. (range 1–1000; default 100) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. ts,coin,side,price,usd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?sinceMinutes=60&limit=50"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `[].venue` | "hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx" | Trading venue. |
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].side` | "long" \| "short", nullable | Side of the liquidated position. |
| `[].price` | number, nullable | Fill price. |
| `[].qty` | number, nullable | Quantity in coins. |
| `[].usd` | number, nullable | Notional (USD). |

Example response (real data):

```json
{
  "data": [],
  "meta": {
    "updatedAt": null,
    "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"
    },
    "nextCursor": null,
    "nextUrl": null,
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/liquidations

### GET /liquidations/summary: 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. 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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive. |
| `hours` | query | integer | no | 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). (range 1–26280; default 24) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations/summary?hours=24"
```

Response `data`:

| Field | Type | 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. |

Example response (real data, lists shortened):

```json
{
  "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"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/liquidations-summary

### GET /liqmap/{coin}: 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. 404 for unknown coins. Free keys: every coin (as "liquidation levels now" on the web).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC (case-insensitive). |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liqmap/BTC"
```

Response `data`:

| Field | Type | 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. |

Example response (real data, lists shortened):

```json
{
  "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/liqmap-coin

### GET /candles/{coin}: Price candles (OHLC)

Price candles (OHLC) of a Hyperliquid coin, oldest first. Live buckets come from 30-second Hyperliquid mark samples (`price: "mark"`, no volume); history before that from trade candles (Binance perpetual for coins listed there, else Hyperliquid) with volume (`volumeUsd` = quote volume where the venue reports it, `volumeBase` in Hyperliquid units, `volumeVenue`). Gaps stay gaps; `complete: false` marks a bucket with missing samples or the one still forming. `from` is clamped to the plan history, `to` to now minus the feed delay. Licence review: candles made only of Binance trades are left out (gaps) and mixed ones lose the Binance volume; coins without a Hyperliquid market answer 403 source_restricted (meta.restricted).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC or xyz:TSLA (case-insensitive). |
| `tf` | query | string | no | Candle timeframe: 5m, 15m, 1h (default), 4h or 1d (UTC-aligned). 5m and 15m reach back 35 days (our 5-minute samples and 5-minute trade candles are kept that long, then hourly); older 5m / 15m buckets are gaps, so use 1h or coarser. (one of 5m, 15m, 1h, 4h, 1d; default 1h) |
| `from` | query | string | no | Start (ISO 8601, optional; default: `limit` candles before `to`). |
| `to` | query | string | no | End, exclusive (ISO 8601, optional; default now). |
| `limit` | query | integer | no | Number of items, default 500, clamped to 1–5000. (range 1–5000; default 500) |
| `fields` | query | string | no | Comma-separated fields of every data.candles item to return, e.g. t,open,high,low,close (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/candles/BTC?tf=1h&limit=48"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `tf` | "5m" \| "15m" \| "1h" \| "4h" \| "1d" | Bucket interval (5m, 15m, 1h, …). |
| `candles[]` | array of objects | Oldest → newest. |
| `candles[].t` | string (ISO 8601) | Bucket start (UTC). |
| `candles[].open` | number | Open price of the bucket. |
| `candles[].high` | number | High price of the bucket. |
| `candles[].low` | number | Low price of the bucket. |
| `candles[].close` | number | Close price of the bucket. |
| `candles[].volumeUsd` | number, nullable | Traded quote volume of the bucket where the venue reports it (USD). |
| `candles[].volumeBase` | number, nullable | Traded volume in base units (Hyperliquid units). |
| `candles[].volumeVenue` | "binance" \| "hyperliquid", nullable | Venue the volume was traded on. |
| `candles[].price` | "mark" \| "trades" \| "mixed" | mark = 30-second Hyperliquid mark samples, trades = trade candles of the volume venue, mixed = both within the bucket. |
| `candles[].complete` | boolean | false when samples are missing in the bucket, it is still forming, or part of its OHLC is derived (rows from before high/low/open were stored; hourly rows compacted after 35 days, whose sample count is not kept). |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "tf": "1h",
    "candles": [
      {
        "t": "2026-10-27T11:00:00.000Z",
        "open": 79979,
        "high": 80129,
        "low": 79840,
        "close": 79893,
        "volumeUsd": null,
        "volumeBase": null,
        "volumeVenue": null,
        "price": "mark",
        "complete": true
      },
      {
        "t": "2026-10-27T12:00:00.000Z",
        "open": 79893,
        "high": 80474,
        "low": 79826,
        "close": 80340,
        "volumeUsd": null,
        "volumeBase": null,
        "volumeVenue": null,
        "price": "mark",
        "complete": true
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-10-27T13:00:00.000Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/candles-coin

### GET /heatmap/{coin}: Liquidation heatmap over time

Liquidation heatmap over time from the tracked Hyperliquid positions (venue=lighter | lighter_rh: tracked Lighter / Lighter RH accounts with the liquidation price Lighter reports; venue=dydx | gmx: every open dYdX v4 / GMX v2 position read from the chain, with the liquidation price we compute from the chain state; venue=all: every enabled real layer added per column): one column per interval `tf` (times, UTC aligned), one row per price bucket (prices, ascending); cells[t][p] is the USD that would be liquidated in that bucket at that time (longCells / shortCells split by side), plus the mark per column. A column shows the levels at its start: the first stored snapshot inside it (snapshotAt), never a sum of several; the running column shows the newest snapshot (live). 1m columns (and 5m for the top 20 coins) come from a fine layer (0.1 % buckets within ±10 %, a snapshot every minute), the rest from 0.5 % buckets within ±50 % (layer, bucketPct, rangePct). freshUsdShare / ageP50Sec per column say how much of the mapped USD was re-read within the cadence and how old it is. tf=1d (Hyperliquid): every day the daily history covers shows its snapshot of every open Hyperliquid position (shortly after 00:00 UTC, the same 0.5 % buckets), the tracked wallets only the days it does not cover yet (normally today); columnSource says which per column, the price rows span the lowest to the highest column mark ± 30 %, and the window reaches as far back as the plan history. Intraday tf (Hyperliquid): every value is measured, nothing is computed between snapshots (since 1.22.0). Live columns start on 2026-11-03 14:15 UTC; before that a column shows the newest daily snapshot of all positions before its end when it is at most 24 hours older (columnSource daily_fill, never across a missing day); after it a column without a live snapshot shows the same daily snapshot until the next live column. Columns reconstructed from fills (columnSource reconstructed, dataSource reconstructed_fills, the recon* fields) are no longer returned; the values stay in the schema. data.dataSource marks every column live or daily_snapshot; columns=live keeps only the live columns. Intervals per plan: free key and keyless 15m, 1h; Pro / API Dev add 5m, 4h, 12h, 1d; Desk / API Pro add 1m. Every coin on every plan; heatmap history (also for its layers): free key and keyless the last 24 hours, Pro / API Dev 1 year, Desk / API Pro 3 years.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC (case-insensitive). |
| `tf` | query | string | no | Column interval: 1m, 5m, 15m, 1h, 4h, 12h or 1d (UTC aligned: 4h at 00/04/…, 12h at 00/12, 1d at 00:00). An interval outside the plan answers 403 plan_required. 1m only for the top 20 coins by open interest (kept 30 days); a window without 1m data answers 400. Recommended: always pass tf (tf=15m gives the same columns as the default). Without tf the API behaves as before 1.12.0 (15-minute columns, coarsened automatically for long windows) and end is not available. (one of 1m, 5m, 15m, 1h, 4h, 12h, 1d) |
| `hours` | query | integer | no | Window in hours (with tf). Default = the interval's default range (1m 6, 5m 24, 15m 24, 1h 336, 4h 720, 12h 4320, 1d 8760), clamped to the plan's heatmap history (free key and keyless the last 24 hours, Pro / API Dev 1 year, Desk / API Pro 3 years). More than the interval's column cap (1m 12 h, 5m 48 h, 15m 168 h, 1h 720 h, 4h 2160 h, 12h 8760 h, 1d 26280 h) or the heatmap history answers 400 invalid_param, never coarsened silently. (range 1–26280) |
| `end` | query | string | no | End of the window (ISO 8601, default now; needs tf, without tf 400): page back in time, e.g. 1m columns three days ago. Clamped to now and to the plan's heatmap history (meta.warnings says so). |
| `columns` | query | string | no | all (default) \| live: only the columns of the live collection (data.dataSource live); columns filled from the daily snapshot become gaps (zero cells, hasSnapshot false, mark null), like a window without a snapshot. Times and price rows stay the same. (one of all, live; default all) |
| `clusters` | query | integer | no | Add data.clusters: the N (1–20) price buckets with the most USD above and below the mark of the newest column with a snapshot (price, usd, longUsd, shortUsd, signed distance): the alert-bot view without reading cells. (range 1–20) |
| `venue` | query | string | no | hyperliquid (default: the tracked Hyperliquid positions, the answer as before) \| lighter \| lighter_rh (tracked Lighter / Lighter RH accounts with the liquidation price Lighter reports) \| dydx \| gmx (every open dYdX v4 / GMX v2 position read from the chain, with the liquidation price we compute from the chain state) \| all (every enabled DEX venue: the real per-venue layers added per column; data.venueColumns says which venue contributed a snapshot to which column, a venue without one adds nothing). Never an estimate for positions that are not public. A coin without a market on the venue answers 404; a switched-off venue 400. (one of hyperliquid, lighter, lighter_rh, dydx, gmx, all; default hyperliquid) |
| `stepMinutes` | query | integer | no | Deprecated (API 1.12.0), use tf. Without tf: column width in minutes, default 15, clamped to 5–1440, coarsened automatically for long windows (≥ 60 beyond 14 days, at most 720 columns). Below 15 needs Pro, Desk or an API plan (403 plan_required, since 1.23.0). Together with tf: 400. (range 5–1440) **Deprecated.** |
| `layer` | query | string | no | real (default, the only layer: tracked positions of the venue). est / both were removed on 2026-10-23 (API 1.9.0) together with the estimated CEX layer (real data only); they now answer 400 invalid_param. (one of real; default real) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/heatmap/BTC?tf=15m&hours=24"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `bucketSize` | number | Price step between rows (0 when there is no data). |
| `times[]` | array of string (ISO 8601) | Column times, oldest → newest. |
| `prices[]` | array of number | Lower edge of each price row, ascending. |
| `cells[]` | array of array | cells[timeIndex][priceIndex]: USD that would be liquidated in that bucket at that time (long + short). |
| `longCells[]` | array of array | Same shape, long positions (below the mark). |
| `shortCells[]` | array of array | Same shape, short positions (above the mark). |
| `mark[]` | array of number | Mark price per column (null when no snapshot exists for that slot). |
| `hasSnapshot[]` | array of boolean | Per column: true when a stored snapshot fills the slot. false = gap (collector down): its cells are 0 only for the shape and are not data. |
| `maxUsd` | number | Largest cell value (USD). |
| `updatedAt` | string (ISO 8601), nullable | Newest snapshot. |
| `tf` | string (enum) | Column interval (absent with the deprecated stepMinutes). |
| `stepMinutes` | integer | Column width in minutes. |
| `layer` | "fine" \| "wide" | fine = 0.1 % buckets within ±10 % (every minute, top 20 coins); wide = 0.5 % buckets within ±50 %. One layer per response. |
| `bucketPct` | number | Bucket width of the layer as a fraction of the mark (0.001 / 0.005). Deprecated: use bucketFraction (same value). |
| `rangePct` | number | Range of the layer around the mark as a fraction (0.1 / 0.5). Deprecated: use rangeFraction (same value). |
| `bucketFraction` | number | Bucket width of the layer as a fraction of the mark (0.001 = 0.1 %). |
| `rangeFraction` | number | Range of the layer around the mark as a fraction (0.5 = ±50 %). |
| `clusters` | object, nullable | With ?clusters=N: the largest buckets above and below the mark of the newest column with a snapshot. |
| `clusters.time` | string (ISO 8601) | Column the clusters are read from (the newest one with a snapshot). |
| `clusters.mark` | number, nullable | Mark of that column. |
| `clusters.above[]` | array of objects | Largest buckets at or above the mark, largest first (short liquidations). |
| `clusters.below[]` | array of objects | Largest buckets below the mark, largest first (long liquidations). |
| `snapshotAt[]` | array of string (ISO 8601) | Per column: exact time of the snapshot drawn (the first one inside the column; the newest one in a live column); null = gap. |
| `live` | boolean | The last column is still running and shows the newest snapshot. |
| `freshUsdShare[]` | array of number | Per column: share (0–1) of the mapped USD whose wallet was re-read within the cadence before the snapshot (fine 1 min, wide 5 min); null = unknown. |
| `ageP50Sec[]` | array of integer | Per column: USD-weighted median age of the mapped positions in seconds; null = unknown. |
| `venue` | "hyperliquid" \| "lighter" \| "lighter_rh" \| "dydx" \| "gmx" \| "all" | Venue layer of the answer (present with ?venue=lighter \| lighter_rh \| dydx \| gmx \| all; absent = Hyperliquid). |
| `venueColumns[]` | array of objects | venue=all: per venue, the columns it contributed a snapshot to (a venue without one adds nothing to that column). |
| `venueColumns[].venue` | "hyperliquid" \| "lighter" \| "lighter_rh" \| "dydx" \| "gmx" | Trading venue the row comes from. |
| `venueColumns[].present[]` | array of boolean | Per column: the venue contributed a snapshot. |
| `columnSource[]` | array of "all_positions" \| "daily_fill" \| "reconstructed" \| "tracked" | With tf on Hyperliquid: per column, where its snapshot comes from. tracked = the live layer of the tracked wallets. tf=1d: all_positions = the daily history of every open Hyperliquid position (one snapshot shortly after 00:00 UTC), used for every day it covers; tracked only for days it does not cover yet (normally today). Intraday tf (1m to 12h): reconstructed (not returned since 1.22.0) = no live snapshot was stored in the column, so it shows the levels of all positions reconstructed from fills between two daily snapshots (snapshotAt = the 15-min reconstruction step at or before the column start; see reconBaseAt, reconSinceBaseSec, reconAssumedShare, reconQuality); daily_fill = no live snapshot and no reconstruction, so it shows the newest daily snapshot of all positions before the column end, at most 24 hours older than its start (snapshotAt = that snapshot). Neither has freshness figures; clusters use the newest tracked column. The sources differ in scale (all positions vs the tracked part); null = gap. |
| `dataSource[]` | array of "live" \| "reconstructed_fills" \| "daily_snapshot" | Per column, where its data comes from: live = a snapshot of the live collection (tracked wallets; also every column of venue=lighter / all and of the deprecated stepMinutes path); reconstructed_fills (not returned since 1.22.0) = reconstructed from fills between two daily snapshots of all positions; daily_snapshot = the daily snapshot of all positions (tf=1d history or an intraday daily fill); null = gap. ?columns=live keeps only the live columns. |
| `reconBaseAt[]` | array of string (ISO 8601) | Not returned since 1.22.0 (measured values only). Reconstructed columns only (null elsewhere; absent when the window has none): time of the real daily snapshot of all positions the reconstruction was replayed from (the nearer one). |
| `reconSinceBaseSec[]` | array of integer | Not returned since 1.22.0 (measured values only). Reconstructed columns only: seconds from reconBaseAt to the reconstruction step; negative = before that snapshot (replayed back in time from the next day's snapshot). \|value\| is at most about 12 hours. |
| `reconAssumedShare[]` | array of number | Not returned since 1.22.0 (measured values only). Reconstructed columns only: share (0–1) of the mapped USD whose margin type or entry price had to be assumed (a position the fills opened without a known setting). |
| `reconQuality[]` | array of "pass" \| "warn" \| "fail" \| "unvalidated" | Not returned since 1.22.0 (measured values only). Reconstructed columns only: how the reconstruction of this coin and day scored when replayed all the way to the other daily snapshot (worst case, 24 hours): pass = long and short USD within 10 %, bucket error at most 0.25, correlation at least 0.9 and closer than carrying the snapshot forward; warn = within 30 % and correlation at least 0.8; fail = worse (deposits, withdrawals and transfers between accounts are not in the fills); unvalidated = not checked yet. |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "bucketSize": 500,
    "times": [
      "2026-10-26T13:15:00.000Z",
      "2026-10-26T13:30:00.000Z"
    ],
    "prices": [
      56000,
      56500
    ],
    "cells": [
      [
        3137522,
        1785195
      ],
      [
        952070,
        3907667
      ]
    ],
    "longCells": [
      [
        3137522,
        1785195
      ],
      [
        952070,
        3907667
      ]
    ],
    "shortCells": [
      [
        0,
        0
      ],
      [
        0,
        0
      ]
    ],
    "mark": [
      80111,
      79593
    ],
    "hasSnapshot": [
      true,
      true
    ],
    "maxUsd": 168910798,
    "updatedAt": "2026-10-27T13:10:00.000Z",
    "stepMinutes": 15,
    "layer": "wide",
    "bucketPct": 0.005,
    "rangePct": 0.5,
    "snapshotAt": [
      "2026-10-26T13:15:00.000Z",
      "2026-10-26T13:30:00.000Z"
    ],
    "live": true,
    "freshUsdShare": [
      null,
      null
    ],
    "ageP50Sec": [
      null,
      null
    ],
    "bucketFraction": 0.005,
    "rangeFraction": 0.5
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:00.000Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/heatmap-coin

### GET /heatmap/{coin}/open-interest: Open interest added per price band

Where open interest was added and removed on the exchanges (Binance, Bybit; OKX while enabled), per price band: the "open interest added at this price" layer of the heatmap. Built only from what the exchanges publish and our collector stores every minute (open interest and the exchange's own mark price, kept in 5-minute buckets for 35 days): for two consecutive 5-minute buckets of one exchange, the change of open interest in contracts, valued at the bucket's price (the middle of its high and low), goes into the price band of that price. addedUsd = the positive changes, removedUsd = the negative ones, netUsd = added minus removed, steps = 5-minute steps with a change. No leverage is assumed and no liquidation price is estimated: this is not a position map. Limits: only the net change per 5 minutes is visible (openings and closings inside one step offset each other); a new contract always has a long and a short side, so added open interest does not say who bought; a step whose price range crosses a band edge counts in the band of its middle price (spanningSteps); a gap in our collection is never bridged; Binance open interest of coins outside the top 60 is read in rotation, so a change can land a few minutes late. Licence review: venue=binance / bybit answers 403 source_restricted; venue=all (default) publishes the sum over the exchanges per band where at least two withheld exchanges contributed to it (otherwise the band keeps its steps and venues and has null amounts, withheld: true), byVenue lists only exchanges that are not withheld, and totals add up the published bands. Same coins per plan as /heatmap/{coin} (free key: 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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name as on Hyperliquid, e.g. BTC (case-insensitive). Exchange listings are matched to it (kPEPE = 1000PEPE). |
| `hours` | query | integer | no | Window in hours, default 24, clamped to 1 to 840 (35 days of 5-minute open interest) and to the plan's heatmap history (free key and keyless the last 24 hours, Pro / API Dev 1 year, Desk / API Pro 3 years; meta.warnings says so). (range 1–840; default 24) |
| `end` | query | string | no | End of the window (ISO 8601, default now), rounded up to the end of its 5-minute step (from / to say which steps were read). Clamped to now and to the readable history. |
| `venue` | query | string | no | all (default: every enabled exchange, summed per band) \| binance \| bybit \| okx (one exchange; 403 source_restricted while its licence review is pending, 400 when switched off). (one of all, binance, bybit, okx; default all) |
| `bandPct` | query | number | no | Band width in percent of the price, default 0.5 (a round step near it, like the heatmap rows), 0.1 to 5. (range 0.1–5; default 0.5) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/heatmap/BTC/open-interest?hours=24"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `venue` | "all" \| "binance" \| "bybit" \| "okx" | The venue asked for (all = every enabled exchange, summed per band). |
| `venues[]` | array of "binance" \| "bybit" \| "okx" | Exchanges read for this answer (enabled ones). |
| `from` | string (ISO 8601) | Window start. |
| `to` | string (ISO 8601) | Window end. |
| `hours` | integer | Window in hours. |
| `mark` | number, nullable | Hyperliquid mark now (the band width is a round step near bandFraction of it). |
| `bandSize` | number | Width of a price band (USD); 0 without a price. |
| `bandFraction` | number | Band width asked for, fraction of the price (0.005 = 0.5 %). |
| `stepMinutes` | integer | Length of one step: two consecutive 5-minute buckets of our collection. |
| `steps` | integer | Steps with a change of open interest in the window (all exchanges read). |
| `spanningSteps` | integer | Of those, steps whose price range crossed a band edge (counted in the band of their middle price). |
| `firstStep` | string (ISO 8601), nullable | First step with data in the window. |
| `lastStep` | string (ISO 8601), nullable | Last step with data in the window. |
| `fullResolutionDays` | integer | Days of 5-minute open interest kept (older history is hourly and not used). |
| `totals` | object | Sums over the rows of this object. |
| `totals.addedUsd` | number | Open interest added over the published bands (USD). |
| `totals.removedUsd` | number | Open interest removed over the published bands (USD). |
| `totals.netUsd` | number | addedUsd minus removedUsd (USD). |
| `totals.withheldBands` | integer | Bands without amounts (licence review: a single withheld exchange would be readable from them). |
| `bands[]` | array of objects | Price bands with a change, lowest first. |
| `bands[].priceLo` | number | Lower edge of the band (USD, inclusive). |
| `bands[].priceHi` | number | Upper edge of the band (USD, exclusive). |
| `bands[].addedUsd` | number, nullable | Open interest added while the price was in this band: the sum of the positive 5-minute changes, in contracts valued at the step price; null = withheld (USD). |
| `bands[].removedUsd` | number, nullable | Open interest removed while the price was in this band (sum of the negative changes, as a positive number); null = withheld (USD). |
| `bands[].netUsd` | number, nullable | addedUsd minus removedUsd; null = withheld (USD). |
| `bands[].steps` | integer | 5-minute steps with a change whose price was in this band. |
| `bands[].venues[]` | array of "binance" \| "bybit" \| "okx" | Exchanges with a change in this band. |
| `bands[].byVenue` | object | Per exchange (only exchanges that are not withheld by the licence review). |
| `bands[].withheld` | boolean | true: amounts left out: with the licence review pending, the sum over the exchanges of this band would be one exchange's own figure. |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "venue": "all",
    "venues": [
      "binance",
      "bybit"
    ],
    "from": "2026-11-02T20:00:00.000Z",
    "to": "2026-11-03T20:00:00.000Z",
    "hours": 24,
    "mark": 77584,
    "bandSize": 500,
    "bandFraction": 0.005,
    "stepMinutes": 5,
    "steps": 556,
    "spanningSteps": 80,
    "firstStep": "2026-11-02T20:00:00.000Z",
    "lastStep": "2026-11-03T19:55:00.000Z",
    "fullResolutionDays": 35,
    "totals": {
      "addedUsd": 852929180.26,
      "removedUsd": 726740142.79,
      "netUsd": 126189037.47,
      "withheldBands": 0
    },
    "bands": [
      {
        "priceLo": 76000,
        "priceHi": 76500,
        "addedUsd": 72099857.89,
        "removedUsd": 24668365.61,
        "netUsd": 47431492.28,
        "steps": 37,
        "venues": [
          "binance",
          "bybit"
        ]
      },
      {
        "priceLo": 76500,
        "priceHi": 77000,
        "addedUsd": 460855501.39,
        "removedUsd": 300436948.97,
        "netUsd": 160418552.42,
        "steps": 301,
        "venues": [
          "binance",
          "bybit"
        ]
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-11-03T19:55:00.000Z",
    "source": "binance,bybit",
    "sources": [
      "binance",
      "bybit"
    ],
    "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: Binance · Bybit",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-11-03T20:00:00.000Z"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/heatmap-coin-open-interest

### GET /heatmap/{coin}/wallets: Wallets with their liquidation price in a band

Tracked Hyperliquid wallets whose position in this coin has its liquidation price in a band right now: size, side, leverage, liquidation price and its signed distance from the mark (liqDistance, fraction), with a link to the wallet page (url). The same positions the live heatmap columns are built from (the newest poll of each wallet, minutes old; a long whose liquidation price is already at or above the mark, or a short at or below it, is left out as on the heatmap). Reconstructed or daily columns have no wallets: wallets are listed for now only. Ask for one band with lo and hi, the heatmap row holding a price with price, or the N largest levels above and below the mark of the current liquidation map with clusters (the default, clusters=3, when none of them is given; each with its wallets; longLevelUsd / shortLevelUsd = the USD of that level in the map). positions, longUsd and shortUsd count every tracked position in the band, wallets lists the largest (limit). Only wallets we track, not every account on Hyperliquid. Same plan rule as /liqmap/{coin}.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC (case-insensitive). |
| `lo` | query | number | no | Lower edge of the band (USD, inclusive). Needs hi; the band is at most 20 % of the price wide. (range 0–) |
| `hi` | query | number | no | Upper edge of the band (USD, exclusive). Needs lo. (range 0–) |
| `price` | query | number | no | Instead of lo / hi: the heatmap row (0.5 % bucket of the liquidation map) holding this price. (range 0–) |
| `clusters` | query | integer | no | Instead of a band: the N (1 to 10) largest levels above and below the mark of the current liquidation map, each with its wallets. Default 3 when neither lo / hi nor price is given. (range 1–10; default 3) |
| `side` | query | string | no | long \| short (optional). (one of long, short) |
| `minUsd` | query | number | no | Minimum position notional in USD, default 0. (range 0–; default 0) |
| `limit` | query | integer | no | Number of items, default 20, clamped to 1–100. (range 1–100; default 20) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/heatmap/BTC/wallets?clusters=3&limit=5"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `mark` | number, nullable | Hyperliquid mark now. |
| `bucketSize` | number, nullable | Row width of the current liquidation map (USD). |
| `mapUpdatedAt` | string (ISO 8601), nullable | Time of the current liquidation map. |
| `bands[]` | array of objects | One band (lo / hi or price), or the clusters largest levels above the mark, then below it. |
| `bands[].priceLo` | number | Lower edge of the band (USD, inclusive). |
| `bands[].priceHi` | number | Upper edge of the band (USD, exclusive). |
| `bands[].distance` | number, nullable | Signed distance from the mark to priceLo, fraction (−0.03 = 3 % below). |
| `bands[].positions` | integer | Tracked positions with their liquidation price in the band now (all of them). |
| `bands[].longUsd` | number | Notional of those long positions (USD). |
| `bands[].shortUsd` | number | Notional of those short positions (USD). |
| `bands[].updatedAt` | string (ISO 8601), nullable | Newest poll among those positions. |
| `bands[].wallets[]` | array of objects | The largest of them, largest first (limit). |
| `bands[].longLevelUsd` | number | clusters only: long liquidations of this level in the current liquidation map (USD). |
| `bands[].shortLevelUsd` | number | clusters only: short liquidations of this level in the current liquidation map (USD). |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "mark": 77584,
    "bucketSize": 500,
    "mapUpdatedAt": "2026-11-03T19:58:47.173Z",
    "bands": [
      {
        "priceLo": 92000,
        "priceHi": 92500,
        "distance": 0.1858115075,
        "longLevelUsd": 0,
        "shortLevelUsd": 114577661.94,
        "positions": 12,
        "longUsd": 0,
        "shortUsd": 114577910.44,
        "updatedAt": "2026-11-03T19:59:11.958Z",
        "wallets": [
          {
            "address": "0xfc27136e42af1732ddc9ce2605ea9bff1b959d9d",
            "label": null,
            "side": "short",
            "positionUsd": 111263508.71,
            "size": 1435.54889,
            "entryPx": 79888,
            "leverage": 25,
            "leverageType": "cross",
            "liqPx": 92384.6929626,
            "liqDistance": 0.1907699134,
            "accountValue": 23846598.75,
            "updatedAt": "2026-11-03T19:57:42.201Z",
            "url": "https://blockmetric.io/wallet/0xfc27136e42af1732ddc9ce2605ea9bff1b959d9d"
          },
          {
            "address": "0x4180847debea25583c4dc0b925c6b1c750d34bf7",
            "label": "ole",
            "side": "short",
            "positionUsd": 2715758.5,
            "size": 35,
            "entryPx": 78934.4,
            "leverage": 40,
            "leverageType": "cross",
            "liqPx": 92242.0581887,
            "liqDistance": 0.1889314574,
            "accountValue": 250400.39,
            "updatedAt": "2026-11-03T19:59:11.958Z",
            "url": "https://blockmetric.io/wallet/0x4180847debea25583c4dc0b925c6b1c750d34bf7"
          }
        ]
      },
      {
        "priceLo": 62000,
        "priceHi": 62500,
        "distance": -0.200866158,
        "longLevelUsd": 113250355.87,
        "shortLevelUsd": 0,
        "positions": 28,
        "longUsd": 111378261.78,
        "shortUsd": 0,
        "updatedAt": "2026-11-03T19:58:59.899Z",
        "wallets": [
          {
            "address": "0xefe4c06b6d310978bead596e1798a4fc1d9d194b",
            "label": null,
            "side": "long",
            "positionUsd": 70834198.81,
            "size": 912.91772,
            "entryPx": 83284.8,
            "leverage": 20,
            "leverageType": "cross",
            "liqPx": 62107.8818946,
            "liqDistance": -0.1994756407,
            "accountValue": 18386519.23,
            "updatedAt": "2026-11-03T19:58:59.899Z",
            "url": "https://blockmetric.io/wallet/0xefe4c06b6d310978bead596e1798a4fc1d9d194b"
          },
          {
            "address": "0xebe837cd345469cbc5d6e1fd3d15ee5079ac885f",
            "label": null,
            "side": "long",
            "positionUsd": 26705220.97,
            "size": 344.30805,
            "entryPx": 84266,
            "leverage": 5,
            "leverageType": "isolated",
            "liqPx": 62244.6585515,
            "liqDistance": -0.1977126914,
            "accountValue": 5541775.68,
            "updatedAt": "2026-11-03T19:58:16.650Z",
            "url": "https://blockmetric.io/wallet/0xebe837cd345469cbc5d6e1fd3d15ee5079ac885f"
          }
        ]
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-11-03T19:59:11.958Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/heatmap-coin-wallets

### GET /scoreboard: 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. 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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Optional: one coin, with the hit rates of its current clusters. |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/scoreboard?coin=BTC"
```

Response `data`:

| Field | Type | 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). |
| `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). |

Example response (real data):

```json
{
  "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/scoreboard

### GET /positions/top: Largest positions

Largest tracked Hyperliquid positions (venue=lighter: tracked Lighter accounts) with entry, leverage, liquidation price and the signed distance from the mark to the liquidation price (liqDistance, fraction).

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive. |
| `side` | query | string | no | long \| short (optional). (one of long, short) |
| `minUsd` | query | number | no | Minimum position notional in USD, default 0. (range 0–; default 0) |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `venue` | query | string | no | hyperliquid (default, the Hyperliquid answer as before) \| lighter (tracked Lighter accounts: address = the Lighter account index, venue = "lighter", liqPx as the exchange reports it). A switched-off venue answers 400. (one of hyperliquid, lighter; default hyperliquid) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. address,coin,side,positionUsd,liqPx (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/positions/top?coin=BTC&limit=10"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].address` | string | Hyperliquid address (lowercase), or with venue "lighter" the Lighter account index. |
| `[].label` | string, nullable | Wallet label (public label or leaderboard display name). |
| `[].accountValue` | number, nullable | Account value (USD). |
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].side` | "long" \| "short" | Position side (for liquidations: the side of the liquidated position). |
| `[].size` | number | Size in coins. |
| `[].entryPx` | number, nullable | Entry price. |
| `[].positionUsd` | number | Notional (USD). |
| `[].leverage` | number, nullable | Leverage of the position (notional / margin). |
| `[].leverageType` | string, nullable | cross \| isolated |
| `[].liqPx` | number, nullable | Liquidation price. |
| `[].liqDistance` | number, nullable | Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark). |
| `[].mark` | number, nullable | Hyperliquid mark price. |
| `[].marginUsed` | number, nullable | Margin used (USD). |
| `[].unrealizedPnl` | number, nullable | Unrealised PnL (USD). |
| `[].updatedAt` | string (ISO 8601) | Newest data time of this item (ISO 8601 UTC). |
| `[].venue` | "hyperliquid" \| "lighter" | Venue of the position (present for Lighter rows; absent = Hyperliquid). |

Example response (real data):

```json
{
  "data": [
    {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "label": null,
      "accountValue": 141229571.24,
      "coin": "BTC",
      "side": "short",
      "size": 2613.28915,
      "entryPx": 76343.5,
      "positionUsd": 209447285.51,
      "leverage": 5,
      "leverageType": "cross",
      "liqPx": 138286.523033,
      "liqDistance": 0.7239914108,
      "mark": 80213,
      "marginUsed": 41889457.1,
      "unrealizedPnl": -9939592.53,
      "updatedAt": "2026-10-27T13:10:10.972Z"
    },
    {
      "address": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
      "label": null,
      "accountValue": 123993441.35,
      "coin": "BTC",
      "side": "short",
      "size": 2516.09893,
      "entryPx": 78114.5,
      "positionUsd": 201675393.64,
      "leverage": 5,
      "leverageType": "cross",
      "liqPx": 126573.437539,
      "liqDistance": 0.5779666331,
      "mark": 80213,
      "marginUsed": 40335078.73,
      "unrealizedPnl": -5131480.09,
      "updatedAt": "2026-10-27T13:09:54.879Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:10.972Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/positions/top?cursor=<cursor>"
  }
}
```

Docs: https://blockmetric.io/docs/api/positions-top

### GET /whales: Whale leaderboard

Whale leaderboard of tracked Hyperliquid wallets with public labels (label + labelSource URL; otherwise the self-chosen leaderboard name), open notional, PnL, largest position with liquidation distance and the number of fill-confirmed liquidations. venue=lighter: tracked Lighter accounts (address = account index, l1Address, the self-chosen account name as label; sort size or pnl; liquidations null: not attributed per account).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `sort` | query | string | no | size (open notional, default) \| pnl (all-time PnL) \| near_liq (closest liquidation of a position ≥ $100k) \| liquidated (most fill-confirmed liquidations). (one of size, pnl, near_liq, liquidated; default size) |
| `coin` | query | string | no | Only wallets with a position in this coin (sort=liquidated: liquidations in this coin). |
| `labelled` | query | boolean | no | true = only wallets with a public label from a cited source; default false. (one of true, false; default false) |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `venue` | query | string | no | hyperliquid (default, the Hyperliquid answer as before) \| lighter (tracked Lighter accounts: address = the Lighter account index, venue = "lighter", liqPx as the exchange reports it). A switched-off venue answers 400. (one of hyperliquid, lighter; default hyperliquid) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. address,label,accountValue,positionsUsd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/whales?sort=size&limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].address` | string | Hyperliquid address (lowercase), or with venue "lighter" the Lighter account index. |
| `[].label` | string, nullable | Public label, else the self-chosen leaderboard name. |
| `[].labelSource` | string, nullable | Source URL of a public label, or "hyperliquid-leaderboard" (unverified). |
| `[].accountValue` | number, nullable | Account value (USD). |
| `[].pnlMonth` | number, nullable | 30-day PnL (USD). |
| `[].pnlAllTime` | number, nullable | All-time PnL (USD). |
| `[].positionsUsd` | number | Open notional (USD). |
| `[].positionCount` | integer | Number of open positions. |
| `[].top` | object, nullable | Largest position. |
| `[].top.coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].top.side` | "long" \| "short" | Position side (for liquidations: the side of the liquidated position). |
| `[].top.usd` | number | Notional (USD). |
| `[].top.leverage` | number, nullable | Leverage of the position (notional / margin). |
| `[].top.liqPx` | number, nullable | Liquidation price of the position. |
| `[].top.liqDistance` | number, nullable | Signed fraction. |
| `[].liquidations` | integer, nullable | Fill-confirmed liquidations in the stored history (null for Lighter accounts: liquidations are not attributed per account). |
| `[].updatedAt` | string (ISO 8601), nullable | Newest data time of this item (ISO 8601 UTC). |
| `[].venue` | "hyperliquid" \| "lighter" | Venue of the position (present for Lighter rows; absent = Hyperliquid). |
| `[].l1Address` | string, nullable | Lighter: the account’s Ethereum address. |

Example response (real data):

```json
{
  "data": [
    {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "label": "Abraxas Capital (reported)",
      "labelSource": "https://info.arkm.com/research/abraxas-capital-still-shorting-500m-of-crypto",
      "accountValue": 141229571.24,
      "pnlMonth": 122795733.29,
      "pnlAllTime": 195588125.05,
      "positionsUsd": 707092087.02,
      "positionCount": 25,
      "top": {
        "coin": "ETH",
        "side": "short",
        "usd": 247633252.94,
        "leverage": 5,
        "liqPx": 3743.37777395,
        "liqDistance": 0.607089617
      },
      "liquidations": 0,
      "updatedAt": "2026-10-27T13:10:10.972Z"
    },
    {
      "address": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
      "label": null,
      "labelSource": null,
      "accountValue": 123993441.35,
      "pnlMonth": 100514969.15,
      "pnlAllTime": 146855674.72,
      "positionsUsd": 589886257.5,
      "positionCount": 32,
      "top": {
        "coin": "BTC",
        "side": "short",
        "usd": 201675393.64,
        "leverage": 5,
        "liqPx": 126573.437539,
        "liqDistance": 0.5779666331
      },
      "liquidations": 0,
      "updatedAt": "2026-10-27T13:09:54.879Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:10.972Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/whales

### GET /whales/feed: Whale position changes

Whale position changes (open, close, increase, decrease, flip, liquidated), newest first. Use `since` as a polling cursor. Stored history: open / close / flip / liquidated 400 days, increase / decrease 90 days.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive. |
| `minUsd` | query | number | no | Minimum absolute USD change, default 0. (range 0–; default 0) |
| `since` | query | string | no | ISO 8601 time; only events after it (optional). Clamped to the plan history (free key 30 days, keyless 24 h): older events are never returned, also not via cursor. |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. ts,address,coin,kind,usdDelta (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/whales/feed?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `[].address` | string | Hyperliquid address, lowercase. |
| `[].label` | string, nullable | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].kind` | "open" \| "close" \| "increase" \| "decrease" \| "flip" \| "liquidated" | Kind of whale position change (liquidated = confirmed by the wallet’s Hyperliquid liquidation fills). |
| `[].side` | "long" \| "short", nullable | Position side (long / short); for trades and orders the side named in the description. |
| `[].sizeDelta` | number, nullable | Change in coins. |
| `[].usdDelta` | number, nullable | Change (USD). |
| `[].price` | number, nullable | Price in the quote currency of the venue (USD / USDT / USDC). |
| `[].data` | any | Kind-specific details (JSON) or null. |

Example response (real data):

```json
{
  "data": [
    {
      "id": 225062,
      "ts": "2026-10-27T13:12:18.534Z",
      "address": "0x7d0c59691fec7f3fea385cdc3126c37a41d91b28",
      "label": null,
      "coin": "HYPE",
      "kind": "increase",
      "side": "short",
      "sizeDelta": 724.16,
      "usdDelta": 56918.98,
      "price": 78.6,
      "data": {
        "prevSize": 99843.61,
        "newSize": 100567.77,
        "prevSide": "short",
        "entryPx": 77.7659,
        "liqPx": 116.084417506,
        "leverage": 7,
        "leverageType": "cross",
        "prevUnrealizedPnl": -65771.220533,
        "prevPolledAt": "2026-10-27T13:09:39.844Z",
        "polledAt": "2026-10-27T13:12:18.534Z",
        "positionUsd": 7904626.72,
        "prevPositionUsd": 7847707.75
      }
    },
    {
      "id": 225061,
      "ts": "2026-10-27T13:12:16.653Z",
      "address": "0xa63be3806dbaa5b8dfc62a4e1d93d7a530567de7",
      "label": null,
      "coin": "SUI",
      "kind": "decrease",
      "side": "short",
      "sizeDelta": -50000,
      "usdDelta": -45879.5,
      "price": 0.91759,
      "data": {
        "prevSize": 475000,
        "newSize": 425000,
        "prevSide": "short",
        "entryPx": 0.91869,
        "liqPx": 1.0340492211,
        "leverage": 10,
        "leverageType": "cross",
        "prevUnrealizedPnl": -1104.922007,
        "prevPolledAt": "2026-10-27T12:46:55.875Z",
        "polledAt": "2026-10-27T13:12:16.653Z",
        "positionUsd": 389975.75,
        "prevPositionUsd": 435855.25
      }
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:12:18.534Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/whales/feed?cursor=<cursor>"
  }
}
```

Docs: https://blockmetric.io/docs/api/whales-feed

### GET /wallets/{address}: Wallet detail

One tracked Hyperliquid wallet: stored account data, current positions (largest first), latest position events (increase / decrease kept 90 days, the other kinds 400 days) and totals. 404 when the wallet is not tracked.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `address` | path | string | yes | 0x address (40 hex characters, any case). |
| `limit` | query | integer | no | Number of position events, default 50, clamped to 1–200. (range 1–200; default 50) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `wallet` | object | - |
| `wallet.address` | string | Hyperliquid address, lowercase. |
| `wallet.label` | string, nullable | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `wallet.accountValue` | number, nullable | Account value (USD). |
| `wallet.pnlMonth` | number, nullable | 30-day PnL (leaderboard) (USD). |
| `wallet.vlmMonth` | number, nullable | 30-day volume (leaderboard) (USD). |
| `wallet.source` | string, nullable | How the wallet was found (e.g. hl_leaderboard). |
| `wallet.priority` | integer | Polling priority (1 = most often). |
| `wallet.firstSeen` | string (ISO 8601) | First time this item was observed (ISO 8601 UTC). |
| `wallet.lastPolledAt` | string (ISO 8601), nullable | Last time the wallet was read from Hyperliquid (ISO 8601 UTC), null = not yet. |
| `wallet.positionCount` | integer, nullable | Number of open positions. |
| `positions[]` | array of objects | Current positions, largest first. |
| `positions[].address` | string | Hyperliquid address (lowercase), or with venue "lighter" the Lighter account index. |
| `positions[].label` | string, nullable | Wallet label (public label or leaderboard display name). |
| `positions[].accountValue` | number, nullable | Account value (USD). |
| `positions[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `positions[].side` | "long" \| "short" | Position side (for liquidations: the side of the liquidated position). |
| `positions[].size` | number | Size in coins. |
| `positions[].entryPx` | number, nullable | Entry price. |
| `positions[].positionUsd` | number | Notional (USD). |
| `positions[].leverage` | number, nullable | Leverage of the position (notional / margin). |
| `positions[].leverageType` | string, nullable | cross \| isolated |
| `positions[].liqPx` | number, nullable | Liquidation price. |
| `positions[].liqDistance` | number, nullable | Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark). |
| `positions[].mark` | number, nullable | Hyperliquid mark price. |
| `positions[].marginUsed` | number, nullable | Margin used (USD). |
| `positions[].unrealizedPnl` | number, nullable | Unrealised PnL (USD). |
| `positions[].updatedAt` | string (ISO 8601) | Newest data time of this item (ISO 8601 UTC). |
| `positions[].venue` | "hyperliquid" \| "lighter" | Venue of the position (present for Lighter rows; absent = Hyperliquid). |
| `events[]` | array of objects | Latest position events, newest first. |
| `events[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `events[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `events[].address` | string | Hyperliquid address, lowercase. |
| `events[].label` | string, nullable | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `events[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `events[].kind` | "open" \| "close" \| "increase" \| "decrease" \| "flip" \| "liquidated" | Kind of whale position change (liquidated = confirmed by the wallet’s Hyperliquid liquidation fills). |
| `events[].side` | "long" \| "short", nullable | Position side (long / short); for trades and orders the side named in the description. |
| `events[].sizeDelta` | number, nullable | Change in coins. |
| `events[].usdDelta` | number, nullable | Change (USD). |
| `events[].price` | number, nullable | Price in the quote currency of the venue (USD / USDT / USDC). |
| `events[].data` | any | Kind-specific details (JSON) or null. |
| `totals` | object | Sums over the rows of this object. |
| `totals.positionUsd` | number | Open notional (USD). |
| `totals.longUsd` | number | Long notional (USD). |
| `totals.shortUsd` | number | Short notional (USD). |
| `totals.unrealizedPnl` | number | Unrealised PnL summed over the positions that report one (USD). |
| `totals.unrealizedPnlMissing` | integer | Positions without a reported unrealised PnL (left out of unrealizedPnl, not counted as 0). |

Example response (real data):

```json
{
  "data": {
    "wallet": {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "label": null,
      "accountValue": 141229571.24,
      "pnlMonth": 122795733.29,
      "vlmMonth": 217999124.81,
      "source": "hl_leaderboard",
      "priority": 1,
      "firstSeen": "2026-10-22T23:36:37.976Z",
      "lastPolledAt": "2026-10-27T13:10:10.972Z",
      "positionCount": 25
    },
    "positions": [
      {
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "accountValue": 141229571.24,
        "coin": "ETH",
        "side": "short",
        "size": 106412.8112,
        "entryPx": 2322.74,
        "positionUsd": 247633252.94,
        "leverage": 5,
        "leverageType": "cross",
        "liqPx": 3743.37777395,
        "liqDistance": 0.607089617,
        "mark": 2329.29,
        "marginUsed": 49526650.59,
        "unrealizedPnl": -463798.42,
        "updatedAt": "2026-10-27T13:10:10.972Z"
      },
      {
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "accountValue": 141229571.24,
        "coin": "BTC",
        "side": "short",
        "size": 2613.28915,
        "entryPx": 76343.5,
        "positionUsd": 209447285.51,
        "leverage": 5,
        "leverageType": "cross",
        "liqPx": 138286.523033,
        "liqDistance": 0.7239914108,
        "mark": 80213,
        "marginUsed": 41889457.1,
        "unrealizedPnl": -9939592.53,
        "updatedAt": "2026-10-27T13:10:10.972Z"
      }
    ],
    "events": [
      {
        "id": 223009,
        "ts": "2026-10-27T12:36:43.304Z",
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "coin": "PUMP",
        "kind": "decrease",
        "side": "short",
        "sizeDelta": -2601910,
        "usdDelta": -10972.25,
        "price": 0.004217,
        "data": {
          "prevSize": 1623693116,
          "newSize": 1621091206,
          "prevSide": "short",
          "entryPx": 0.004608,
          "liqPx": 0.0917287092,
          "leverage": 5,
          "leverageType": "cross",
          "prevUnrealizedPnl": 632546.946695,
          "prevPolledAt": "2026-10-27T12:34:08.753Z",
          "polledAt": "2026-10-27T12:36:43.304Z",
          "positionUsd": 6836141.62,
          "prevPositionUsd": 6847113.87
        }
      },
      {
        "id": 222693,
        "ts": "2026-10-27T12:31:34.296Z",
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": null,
        "coin": "PUMP",
        "kind": "decrease",
        "side": "short",
        "sizeDelta": -2851153,
        "usdDelta": -11977.69,
        "price": 0.004201,
        "data": {
          "prevSize": 1626781839,
          "newSize": 1623930686,
          "prevSide": "short",
          "entryPx": 0.004608,
          "liqPx": 0.0918533171,
          "leverage": 5,
          "leverageType": "cross",
          "prevUnrealizedPnl": 650018.048084,
          "prevPolledAt": "2026-10-27T12:29:00.988Z",
          "polledAt": "2026-10-27T12:31:34.296Z",
          "positionUsd": 6822132.81,
          "prevPositionUsd": 6834110.51
        }
      }
    ],
    "totals": {
      "positionUsd": 707092087.02,
      "longUsd": 250824.09,
      "shortUsd": 706841262.94,
      "unrealizedPnl": 3036457.49,
      "unrealizedPnlMissing": 0
    }
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:10.972Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/wallets-address

### GET /whales/stops: 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. 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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin for the bucket map and the overlay (optional; without it: per-coin table). |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/whales/stops?coin=BTC"
```

Response `data`:

| Field | Type | 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.totals` | object | Sums over the rows of this object. |
| `map.coverage` | object | Which wallets the stop map covers (the largest tracked wallets in the rotation, main dex only). |
| `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[].nearestAbove` | object, nullable | Largest buy-stop bucket above 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. |

Example response (real data):

```json
{
  "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/whales-stops

### GET /traders: Trader leaderboard

Trader leaderboard from the official Hyperliquid leaderboard (PnL, ROI and volume of day / week / month / all-time; PnL is the change of the account with its sub-accounts and spot balances, so deposits and withdrawals do not count) plus what we observed: win rate and holding time from our position polls, max drawdown and Sharpe from Hyperliquid portfolio history (top traders), style tags and cohorts. Only single trading accounts are listed (no vaults, dust or accounts without trading; ROI / Sharpe / drawdown sorts need more, `rules` says what applies). Names are self-chosen unless `labelSource` is a URL. Free keys: the top 100 of any sort with every column (`full: false`: no search, style filter or paging).

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `sort` | query | string | no | pnl_day \| pnl_week \| pnl_month (default) \| pnl_all \| roi_week \| roi_month \| roi_all \| account_value \| vlm_month \| sharpe \| drawdown (smallest first). (one of pnl_day, pnl_week, pnl_month, pnl_all, roi_week, roi_month, roi_all, account_value, vlm_month, sharpe, drawdown; default pnl_month) |
| `search` | query | string | no | Address prefix (0x…) or part of a displayed name (paid plans). |
| `style` | query | string | no | scalper \| swing \| position \| high_turnover \| high_leverage \| mostly_long \| mostly_short (paid plans). (one of scalper, swing, position, high_turnover, high_leverage, mostly_long, mostly_short) |
| `minAccountValue` | query | number | no | Minimum account value in USD (paid plans). (range 0–; default 0) |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every data.rows item to return, e.g. rank,address,pnl,roi (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/traders?sort=pnl_month&limit=25"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `rows[]` | array of objects | The rows of this view. |
| `rows[].rank` | integer | Rank in the current sort. |
| `rows[].address` | string | Hyperliquid address, lowercase. |
| `rows[].label` | string, nullable | Public label, else the self-chosen leaderboard name (unverified). |
| `rows[].labelSource` | string, nullable | Source URL of a public label, or "hyperliquid-leaderboard". |
| `rows[].accountValue` | number, nullable | Account value (USD). |
| `rows[].pnl` | object | Hyperliquid leaderboard PnL per window (USD): the account with its sub-accounts and spot balances, deposits / withdrawals not counted. |
| `rows[].roi` | object | Hyperliquid leaderboard ROI per window (fraction). |
| `rows[].vlm` | object | Traded volume per window (USD). |
| `rows[].observed` | object | From the opens and closes our position polls saw (empty for free keys). |
| `rows[].risk` | object, nullable | Risk figures from the Hyperliquid portfolio history (top traders), else null. |
| `rows[].book` | object, nullable | Open tracked positions of the wallet, else null. |
| `rows[].styles[]` | array of string (enum) | Style tags from observed behaviour (scalper, swing, position, high_turnover, high_leverage, mostly_long, mostly_short). |
| `rows[].sizeCohort` | "shrimp" \| "fish" \| "dolphin" \| "shark" \| "whale", nullable | Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M. |
| `rows[].pnlCohort` | "top" \| "profitable" \| "flat" \| "losing" \| "rekt", nullable | PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M. |
| `rows[].updatedAt` | string (ISO 8601) | Leaderboard row time. |
| `total` | integer | Rows matching the filters. |
| `updatedAt` | string (ISO 8601), nullable | Newest leaderboard run. |
| `riskUpdatedAt` | string (ISO 8601), nullable | Newest portfolio read (drawdown, Sharpe). |
| `full` | boolean | false = free key: the top 100 of the chosen sort, every column, no search, style filter or paging. |
| `rules` | string | Who the chosen sort lists. |
| `method` | string | How the figures are computed, in plain words. |

Example response (real data):

```json
{
  "data": {
    "rows": [
      {
        "rank": 1,
        "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "label": "Abraxas Capital (reported)",
        "labelSource": "https://info.arkm.com/research/abraxas-capital-still-shorting-500m-of-crypto",
        "accountValue": 218661360.67,
        "pnl": {
          "day": -1465730.63325,
          "week": 44257018.0382,
          "month": 112305737.722,
          "allTime": 184126724.078
        },
        "roi": {
          "day": -0.0066585654,
          "week": 0.269263319,
          "month": 0.6463733379,
          "allTime": 0.4963734104
        },
        "vlm": {
          "day": 8913480.21,
          "week": 52370497.51,
          "month": 213644821.23,
          "allTime": 5855538273.66
        },
        "observed": {
          "closes": 1,
          "wins": 1,
          "winRate": null,
          "avgHoldMin": null,
          "holds": 0,
          "since": "2026-10-23T00:27:13.150Z"
        },
        "risk": {
          "maxDrawdownUsd": 45751143.2,
          "maxDrawdownPct": 0.1648435951,
          "sharpe": 4.5903042327,
          "fetchedAt": "2026-10-28T20:24:09.857Z",
          "maxDrawdown": 0.1648435951
        },
        "book": {
          "positionsUsd": 720066402.26,
          "positions": 26,
          "longShare": 0.0010455763,
          "avgLeverage": 4.9254768902
        },
        "styles": [
          "mostly short"
        ],
        "sizeCohort": "whale",
        "pnlCohort": "top",
        "updatedAt": "2026-10-28T20:25:32.910Z"
      },
      {
        "rank": 2,
        "address": "0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36",
        "label": null,
        "labelSource": null,
        "accountValue": 203523548.9,
        "pnl": {
          "day": -2114654.47643,
          "week": 34009183.7954,
          "month": 86744777.0968,
          "allTime": 137348648.242
        },
        "roi": {
          "day": -0.0144410549,
          "week": 0.2243557408,
          "month": 0.5661464986,
          "allTime": 0.8240901682
        },
        "vlm": {
          "day": 1924151.4,
          "week": 31476927.24,
          "month": 436329314.43,
          "allTime": 5929320806.8
        },
        "observed": {
          "closes": 0,
          "wins": 0,
          "winRate": null,
          "avgHoldMin": null,
          "holds": 0,
          "since": "2026-10-23T00:27:14.641Z"
        },
        "risk": {
          "maxDrawdownUsd": 36768839.21,
          "maxDrawdownPct": 0.140612079,
          "sharpe": 3.7726687757,
          "fetchedAt": "2026-10-28T20:24:52.214Z",
          "maxDrawdown": 0.140612079
        },
        "book": {
          "positionsUsd": 599438215.1,
          "positions": 33,
          "longShare": 0.0011046405,
          "avgLeverage": 4.568620596
        },
        "styles": [
          "mostly short"
        ],
        "sizeCohort": "whale",
        "pnlCohort": "top",
        "updatedAt": "2026-10-28T20:25:32.910Z"
      }
    ],
    "total": 15492,
    "updatedAt": "2026-10-28T20:25:32.910Z",
    "riskUpdatedAt": "2026-10-28T22:43:43.035Z",
    "full": true,
    "rules": "Listed: single accounts only (no vaults, no HLP), account value $100+, traded in the last 30 days, 30-day PnL at most 20× the 30-day volume.",
    "method": "Leaderboard numbers (PnL, ROI, volume, account value) are copied from the official Hyperliquid leaderboard (read every 6 h). Hyperliquid counts an account together with its sub-accounts and its spot balances: PnL is the change of that account in the window without deposits, withdrawals and transfers, so price changes of tokens held count too. ROI is Hyperliquid's own figure for the window. Names are self-chosen by the account owner (unverified) unless a public label with a source is shown. Win rate = closes in profit ÷ closes (in profit: the unrealised PnL at our last poll before the close was above 0; liquidations count as losses), from the opens and closes our position polls saw since we track the wallet, shown from 10 closes; average holding time from 3 positions we saw open and close. Max drawdown and Sharpe come from Hyperliquid's 30-day portfolio history of the address (about one point every 16 h): drawdown = largest fall of the cumulative PnL from an earlier high ÷ account value at that high; Sharpe = mean ÷ sample standard deviation of the returns r = PnL change ÷ account value at the start of each interval, × √(intervals per year), no risk-free rate. That history covers one address without its sub-accounts, so both are shown only where its 30-day PnL is within 25 % of the leaderboard PnL."
  },
  "meta": {
    "updatedAt": "2026-10-28T20:25:32.910Z",
    "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-28T23:36:00.000Z"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/traders?cursor=<cursor>"
  }
}
```

Docs: https://blockmetric.io/docs/api/traders

### GET /cohorts: Cohort positioning

Positioning of tracked Hyperliquid wallets by cohort: size (shrimp < $10K, fish, dolphin, shark, whale ≥ $10M account value) and all-time PnL (top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M): long / short notional, wallets and long share now, its change over 15m / 1h / 4h / 24h / 3d / 7d (from 5-min snapshots, capped at the plan history), recent position changes with cohorts and the net flow of the last hour. Coverage is the wallets this service polls (large wallets far better than small ones).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Coin, or ALL (default) for every position. |
| `dim` | query | string | no | size \| pnl. With `cohort`: only changes of that cohort. (one of size, pnl) |
| `cohort` | query | string | no | shrimp \| fish \| dolphin \| shark \| whale \| top \| profitable \| flat \| losing \| rekt (needs dim). (one of shrimp, fish, dolphin, shark, whale, top, profitable, flat, losing, rekt) |
| `limit` | query | integer | no | Number of items, default 30, clamped to 1–200. (range 1–200; default 30) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/cohorts?coin=BTC"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin or ALL. |
| `snapshotAt` | string (ISO 8601), nullable | Newest 5-min snapshot. |
| `rows[]` | array of objects | The rows of this view. |
| `rows[].dim` | "size" \| "pnl" | Cohort dimension: size (account value) or pnl (all-time PnL). |
| `rows[].cohort` | string | Cohort key within its dimension. |
| `rows[].label` | string | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `rows[].longUsd` | number | Long notional (USD). |
| `rows[].shortUsd` | number | Short notional (USD). |
| `rows[].longWallets` | integer | Wallets on the long side. |
| `rows[].shortWallets` | integer | Wallets on the short side. |
| `rows[].longShare` | number, nullable | longUsd / (longUsd + shortUsd). |
| `rows[].change` | object | Change of longShare against the snapshot that long ago (fraction points); windows beyond the plan history are missing. |
| `since` | string (ISO 8601), nullable | Oldest snapshot. |
| `changes[]` | array of objects | Recent position changes ≥ $50k with cohorts (delayed for free keys). |
| `changes[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `changes[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `changes[].address` | string | Hyperliquid address, lowercase. |
| `changes[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `changes[].kind` | "open" \| "close" \| "increase" \| "decrease" \| "flip" \| "liquidated" | Kind of the item (enum of this field). |
| `changes[].side` | "long" \| "short", nullable | Position side (for liquidations: the side of the liquidated position). |
| `changes[].usdDelta` | number | Signed USD change. |
| `changes[].price` | number, nullable | Price in the quote currency of the venue (USD / USDT / USDC). |
| `changes[].sizeCohort` | "shrimp" \| "fish" \| "dolphin" \| "shark" \| "whale", nullable | Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M. |
| `changes[].pnlCohort` | "top" \| "profitable" \| "flat" \| "losing" \| "rekt", nullable | PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M. |
| `netFlow1h[]` | array of objects | Net notional added per cohort and side in the last hour. |
| `netFlow1h[].dim` | "size" \| "pnl" | Cohort dimension: size (account value) or pnl (all-time PnL). |
| `netFlow1h[].cohort` | string | Cohort key within its dimension. |
| `netFlow1h[].longUsd` | number | Long notional in USD. |
| `netFlow1h[].shortUsd` | number | Short notional in USD. |
| `netFlow1h[].events` | integer | Events of this view (newest first) or their count. |
| `maxMinutes` | integer | Longest trend window of the plan. |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "snapshotAt": "2026-10-27T13:10:00.000Z",
    "rows": [
      {
        "dim": "size",
        "cohort": "whale",
        "label": "Whale (≥ $10M)",
        "longUsd": 311625613.68,
        "shortUsd": 868589539.66,
        "longWallets": 7,
        "shortWallets": 17,
        "longShare": 0.2640413596,
        "change": {
          "15m": 0.0017261481,
          "1h": 0.0073477515,
          "4h": 0.0049861231,
          "24h": 0.0456011833,
          "3d": 0.0700297538,
          "7d": null
        }
      },
      {
        "dim": "size",
        "cohort": "shark",
        "label": "Shark ($1M–10M)",
        "longUsd": 585266663.15,
        "shortUsd": 347128405,
        "longWallets": 76,
        "shortWallets": 84,
        "longShare": 0.6277024441,
        "change": {
          "15m": -0.0029585558,
          "1h": 0.0166798925,
          "4h": 0.0181038648,
          "24h": -0.0044729906,
          "3d": -0.0514425533,
          "7d": null
        }
      }
    ],
    "since": "2026-10-23T05:50:00.000Z",
    "changes": [
      {
        "id": 225031,
        "ts": "2026-10-27T13:11:48.816Z",
        "address": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
        "coin": "BTC",
        "kind": "increase",
        "side": "long",
        "usdDelta": 194429.59,
        "price": 80196,
        "sizeCohort": "whale",
        "pnlCohort": "top"
      },
      {
        "id": 224982,
        "ts": "2026-10-27T13:11:18.226Z",
        "address": "0x8730154f2c794a59cd6adb0d8328a9770c13b616",
        "coin": "BTC",
        "kind": "close",
        "side": "long",
        "usdDelta": -160392,
        "price": 80196,
        "sizeCohort": "shrimp",
        "pnlCohort": "flat"
      }
    ],
    "netFlow1h": [
      {
        "dim": "size",
        "cohort": "shark",
        "longUsd": 32902179.05,
        "shortUsd": -2872109.46,
        "events": 213
      },
      {
        "dim": "pnl",
        "cohort": "top",
        "longUsd": 29028790.11,
        "shortUsd": 1575474.44,
        "events": 110
      }
    ],
    "maxMinutes": 525600
  },
  "meta": {
    "updatedAt": "2026-10-27T13:10:00.000Z",
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/cohorts

### GET /smart-money: Smart-money convergence

Smart-money convergence: events when at least K (default 3) of the top all-time-PnL Hyperliquid wallets (without vaults, market makers by fill counts and turnover, and delta-neutral books) open or add the same side of a coin within the window (default 60 min), plus the current positioning of these wallets and the filter statistics. Events are delayed for free keys (meta.delayMinutes).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `limit` | query | integer | no | Number of items, default 30, clamped to 1–200. (range 1–200; default 30) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/smart-money?limit=10"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `events[]` | array of objects | Events of this view (newest first) or their count. |
| `events[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `events[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `events[].coin` | string, nullable | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `events[].severity` | integer | 1 info, 2 notable, 3 major, 4 critical. |
| `events[].title` | string | One-line factual title in our own words. |
| `events[].side` | "long" \| "short", nullable | Position side (for liquidations: the side of the liquidated position). |
| `events[].count` | integer, nullable | Wallets that converged. |
| `events[].usd` | number, nullable | Notional in USD. |
| `events[].wallets[]` | array of objects | Number of distinct wallets. |
| `positioning[]` | array of objects | Open tracked positions of the smart wallets. |
| `positioning[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `positioning[].longUsd` | number | Long notional in USD. |
| `positioning[].shortUsd` | number | Short notional in USD. |
| `positioning[].longWallets` | integer | Wallets on the long side. |
| `positioning[].shortWallets` | integer | Wallets on the short side. |
| `positioning[].updatedAt` | string (ISO 8601), nullable | Newest poll of these positions. |
| `wallets` | integer | Smart wallets after the filters. |
| `candidates` | integer | Leaderboard wallets checked from the top of the lists (smart wallets plus excluded ones). |
| `excluded` | object | Excluded wallets per reason. |
| `excluded.vault` | integer | Hyperliquid vaults (including HLP). |
| `excluded.many_positions` | integer | Deprecated: use manyPositions (same value). |
| `excluded.resting_orders` | integer | Deprecated: use restingOrders (same value). |
| `excluded.high_fills` | integer | Deprecated: use highFills (same value). |
| `excluded.turnover` | integer | Wallets whose 30-day volume is a large multiple of the account value (market making / HFT). |
| `excluded.hedged` | integer | Delta-neutral books (long and short notional nearly equal). |
| `excluded.manyPositions` | integer | Wallets with many open positions (market makers, multi-asset algos). |
| `excluded.restingOrders` | integer | Wallets with many resting limit orders (a quoted book). |
| `excluded.highFills` | integer | Wallets with very many fills per hour (market making). |
| `excluded.notTrading` | integer | All-time PnL above 20 × the all-time volume (token holdings, airdrops). |
| `delayMinutes` | integer | Minutes the events are delayed for the caller’s plan (0 = real time). |
| `settings` | object | Detector settings in force. |
| `settings.k` | integer | Wallets needed for a convergence event. |
| `settings.windowMin` | number | Window of a convergence in minutes. |
| `settings.minUsd` | number | Minimum position change per wallet in USD. |
| `settings.top` | integer | All-time PnL list size. |
| `settings.monthTop` | integer | 30-day PnL list size (0 = off). |
| `settings.monthMinAccountUsd` | number | Lowest account value of the 30-day list (USD). |
| `settings.monthMinRoi` | number | Lowest 30-day ROI as a fraction (0.05 = 5 %). |
| `settings.roiTop` | integer | All-time ROI list size (0 = off). |
| `settings.roiMinAccountUsd` | number | Lowest account value of the ROI list (USD). |
| `settings.roiMinPnlUsd` | number | Lowest all-time PnL of the ROI list (USD). |
| `settings.maxWallets` | integer | Most smart wallets in all. |
| `method` | string | How the figures are computed, in plain words. |
| `lists` | object | Wallets per list after the filters (a wallet on two lists counts on both). |
| `lists.allTime` | object | - |
| `lists.month` | object | - |
| `lists.roi` | object | - |
| `leaderboardAt` | string (ISO 8601), nullable | Newest Hyperliquid leaderboard run the set is built from. |

Example response (real data):

```json
{
  "data": {
    "events": [],
    "positioning": [
      {
        "coin": "BTC",
        "longUsd": 147457920.25,
        "shortUsd": 112147433.25,
        "longWallets": 8,
        "shortWallets": 12,
        "updatedAt": "2026-10-27T13:11:20.471Z"
      },
      {
        "coin": "HYPE",
        "longUsd": 196677230.4,
        "shortUsd": 56889464.66,
        "longWallets": 9,
        "shortWallets": 14,
        "updatedAt": "2026-10-27T13:11:30.881Z"
      }
    ],
    "wallets": 418,
    "candidates": 500,
    "excluded": {
      "many_positions": 26,
      "vault": 5,
      "turnover": 25,
      "high_fills": 14,
      "resting_orders": 7,
      "hedged": 5,
      "manyPositions": 26,
      "restingOrders": 7,
      "highFills": 14
    },
    "delayMinutes": 0,
    "settings": {
      "k": 3,
      "windowMin": 60,
      "minUsd": 100000,
      "top": 500
    },
    "method": "Smart money = the 500 wallets with the highest all-time PnL on the Hyperliquid leaderboard, without vaults, market makers (20+ open positions, 50+ resting limit orders, 200+ fills in an hour on our trade stream, or 30-day volume ≥ 50 × account value) and delta-neutral books. A convergence event fires when ≥ 3 of them open or add the same side of a coin within 60 min (≥ $100K each) and at most half as many add the other side."
  },
  "meta": {
    "updatedAt": null,
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/smart-money

### GET /orderbook/{coin}: Order book liquidity and walls

Order book liquidity of one coin: resting USD per price bucket for every covered venue (Hyperliquid l2Book in a fine layer ≈ ±2 % and a coarse layer ≈ ±10–25 %, Binance / Bybit local books within ±5 %), depth within 1 / 2 / 5 % and the bid/ask imbalance, plus walls (large resting liquidity relative to the buckets around it) that are active or ended in the last hour. Status pulled = removed before the price touched it, filled = the price traded into it. Walls cannot be attributed to wallets and a pulled wall is not proof of spoofing. With `hours` also the book heatmap over time (paid plans). Free keys: BTC, ETH and HYPE, current book only. Distances are fractions (walls[].distance, depth[].band; the older …Pct names hold the same fractions). Coins without a Hyperliquid market answer 404. Licence review: Binance / Bybit books and walls are withheld (meta.restricted); venue=binance|bybit answers 403 source_restricted.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC (case-insensitive). |
| `venue` | query | string | no | hyperliquid \| binance \| bybit (optional; default every covered venue the API serves). (one of hyperliquid, binance, bybit) |
| `hours` | query | integer | no | Add the book heatmap over the last N hours (Pro / API Dev up to 168, Desk / API Pro up to 720); 0 or absent = current book only. Free keys: 403. (range 0–720; default 0) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/orderbook/BTC"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `mid` | number, nullable | Mid price between the best bid and ask. |
| `updatedAt` | string (ISO 8601), nullable | Newest snapshot. |
| `venues[]` | array of objects | Venues covered by this view. |
| `venues[].venue` | "hyperliquid" \| "binance" \| "bybit" | Venue of the order-flow data. |
| `venues[].layer` | "fine" \| "coarse" \| "book" | fine / coarse = Hyperliquid l2Book with 3 / 2 significant figures (the coarse layer leaves out the fine range); book = local CEX order book. |
| `venues[].step` | number | Bucket size (price). |
| `venues[].mid` | number | Mid price (latest trade of the venue, else the book). |
| `venues[].ts` | string (ISO 8601) | Snapshot time. |
| `venues[].lo` | number | Lowest price covered. |
| `venues[].hi` | number | Highest price covered. |
| `venues[].bids[]` | array of objects | Bid buckets, from the price downwards. |
| `venues[].asks[]` | array of objects | Ask buckets, from the price upwards. |
| `venues[].bidUsd` | number | All bids of the snapshot (USD). |
| `venues[].askUsd` | number | All asks of the snapshot (USD). |
| `venues[].bid1pct` | number | Bids within 1 % of the mid (USD). |
| `venues[].ask1pct` | number | Asks within 1 % of the mid (USD). |
| `depth[]` | array of objects | Resting liquidity within bands around the mid (1 / 2 / 5 %). |
| `depth[].pct` | number | Band around the mid (fraction, 0.01 = 1 %). Deprecated: use band (same value). |
| `depth[].band` | number | Band around the mid, fraction (0.01 = 1 %). |
| `depth[].bidUsd` | number | Bids in the band (USD). |
| `depth[].askUsd` | number | Asks in the band (USD). |
| `depth[].imbalance` | number, nullable | (bids - asks) / (bids + asks). |
| `walls[]` | array of objects | Active walls and walls that ended in the last hour, active first, largest first. |
| `walls[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `walls[].venue` | "hyperliquid" \| "binance" \| "bybit" | Venue of the order-flow data. |
| `walls[].layer` | "fine" \| "coarse" \| "book" | Storage layer the data was read from (enum of this field). |
| `walls[].side` | "bid" \| "ask" | Position side (long / short); for trades and orders the side named in the description. |
| `walls[].px` | number | Lower edge of the bucket. |
| `walls[].top` | number | Upper edge of the bucket. |
| `walls[].usd` | number | Size at the last sighting (USD). |
| `walls[].maxUsd` | number | Largest size seen (USD). |
| `walls[].firstUsd` | number | Size when first seen (USD). |
| `walls[].firstSeen` | string (ISO 8601) | First time this item was observed (ISO 8601 UTC). |
| `walls[].lastSeen` | string (ISO 8601) | Last time this item was observed (ISO 8601 UTC). |
| `walls[].endedAt` | string (ISO 8601), nullable | When it ended (ISO 8601 UTC); null while active. |
| `walls[].status` | "active" \| "pulled" \| "filled" \| "gone" | pulled = removed before the price traded into it (not proof of spoofing); filled = the price traded into it while it shrank (consumed or cancelled at the touch); gone = left the observed range. |
| `walls[].distancePct` | number | Distance from the price when first seen (fraction, 0.01 = 1 %). Deprecated: use distance (same value). |
| `walls[].minDistancePct` | number | Closest distance to the price (fraction). Deprecated: use minDistance (same value). |
| `walls[].distance` | number | Distance from the price when first seen, fraction (0.01 = 1 %). |
| `walls[].minDistance` | number | Closest distance to the price, fraction. |
| `walls[].touchedAt` | string (ISO 8601), nullable | First time the price traded into the bucket. |
| `walls[].lifetimeSec` | integer | Seconds from first sighting to the end (or the last sighting). |
| `walls[].history[]` | array of array | [secondsSinceFirstSeen, usd] at size changes of 20 % or more. |
| `heatmap` | object, nullable | Order book heatmap over time (with ?hours=), else null. |
| `heatmap.coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `heatmap.venues[]` | array of "hyperliquid" \| "binance" \| "bybit" | Venues covered by this view. |
| `heatmap.times[]` | array of string (ISO 8601) | Column start times, oldest to newest. |
| `heatmap.colMs` | integer | Column width in milliseconds. |
| `heatmap.prices[]` | array of number | Lower edge of each price row, ascending. |
| `heatmap.rowStep` | number | Price step between rows. |
| `heatmap.bid[]` | array of array | bid[timeIndex][priceIndex]: resting bids in USD (rounded to $1,000). |
| `heatmap.ask[]` | array of array | Same shape, resting asks. |
| `heatmap.mid[]` | array of number | Mid price per column (null without a snapshot). |
| `heatmap.candles` | object | OHLC of taker trades per column. |
| `heatmap.maxUsd` | number | Largest cell (USD). |
| `heatmap.coarse[]` | array of objects | Coarse layers whose buckets can be wider than a row (each drawn whole in the row of its centre). |
| `heatmap.updatedAt` | string (ISO 8601), nullable | Newest data time of this item (ISO 8601 UTC). |

Example response (real data):

```json
{
  "data": {
    "coin": "BTC",
    "mid": 80214,
    "updatedAt": "2026-10-27T13:11:30.000Z",
    "venues": [
      {
        "venue": "hyperliquid",
        "layer": "fine",
        "step": 100,
        "mid": 80214,
        "ts": "2026-10-27T13:11:30.000Z",
        "lo": 78300,
        "hi": 82200,
        "bids": [
          {
            "px": 80200,
            "usd": 2980000
          },
          {
            "px": 80100,
            "usd": 32300000
          }
        ],
        "asks": [
          {
            "px": 80200,
            "usd": 26500000
          },
          {
            "px": 80300,
            "usd": 23400000
          }
        ],
        "bidUsd": 209248635,
        "askUsd": 173346849,
        "bid1pct": 119209022,
        "ask1pct": 127069252
      },
      {
        "venue": "hyperliquid",
        "layer": "coarse",
        "step": 1000,
        "mid": 80214,
        "ts": "2026-10-27T13:11:30.000Z",
        "lo": 61000,
        "hi": 100000,
        "bids": [
          {
            "px": 77000,
            "usd": 35100000
          },
          {
            "px": 76000,
            "usd": 35400000
          }
        ],
        "asks": [
          {
            "px": 83000,
            "usd": 18300000
          },
          {
            "px": 84000,
            "usd": 23500000
          }
        ],
        "bidUsd": 254383813,
        "askUsd": 101123260,
        "bid1pct": 0,
        "ask1pct": 0
      }
    ],
    "depth": [
      {
        "pct": 0.01,
        "bidUsd": 116200000,
        "askUsd": 127150000,
        "imbalance": -0.045,
        "band": 0.01
      },
      {
        "pct": 0.02,
        "bidUsd": 190380000,
        "askUsd": 163460000,
        "imbalance": 0.076,
        "band": 0.02
      }
    ],
    "walls": [
      {
        "id": 19798,
        "venue": "hyperliquid",
        "layer": "fine",
        "side": "ask",
        "px": 80300,
        "top": 80400,
        "usd": 32898183,
        "maxUsd": 54462630,
        "firstUsd": 53829356,
        "firstSeen": "2026-10-27T12:44:06.530Z",
        "lastSeen": "2026-10-27T12:48:42.274Z",
        "endedAt": "2026-10-27T12:48:47.290Z",
        "status": "filled",
        "distancePct": 0.00006,
        "minDistancePct": 0,
        "touchedAt": "2026-10-27T12:44:26.574Z",
        "lifetimeSec": 281,
        "history": [
          [
            0,
            53829356
          ],
          [
            30,
            37145198
          ]
        ],
        "distance": 0.00006,
        "minDistance": 0
      },
      {
        "id": 19870,
        "venue": "hyperliquid",
        "layer": "fine",
        "side": "ask",
        "px": 80300,
        "top": 80400,
        "usd": 21768932,
        "maxUsd": 47131362,
        "firstUsd": 43208804,
        "firstSeen": "2026-10-27T13:03:09.590Z",
        "lastSeen": "2026-10-27T13:06:50.184Z",
        "endedAt": "2026-10-27T13:06:55.191Z",
        "status": "pulled",
        "distancePct": 0.00016,
        "minDistancePct": 0.00016,
        "touchedAt": null,
        "lifetimeSec": 226,
        "history": [
          [
            0,
            43208804
          ],
          [
            40,
            33706274
          ]
        ],
        "distance": 0.00016,
        "minDistance": 0.00016
      }
    ],
    "heatmap": null
  },
  "meta": {
    "updatedAt": "2026-10-27T13:11:30.000Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/orderbook-coin

### GET /flow/{coin}: Taker flow (CVD) and volume profile

Taker flow of one coin: buy / sell volume of the aggressor per bar, delta and cumulative volume delta (CVD), summed over the perpetual venues, per venue (Binance spot separately where collected), by print size (under $10k, $10k–100k, $100k–1M, $1M and more; a print = the fills of one taker order) and for tracked Hyperliquid whales (USD they bought minus sold, either side of the trade), plus the volume profile (taker volume by price, point of control, 70 % value area) of the window. Free keys: BTC, ETH and HYPE, last 24 hours. Coins without a Hyperliquid market answer 404. Licence review: byVenue shows Hyperliquid only; total, bySize and the profile still sum every venue, in bars of at least 5 minutes (venue=hyperliquid keeps 1-minute bars); venue=binance|bybit answers 403 source_restricted.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | path | string | yes | Coin name, e.g. BTC (case-insensitive). |
| `venue` | query | string | no | hyperliquid \| binance \| bybit (optional). (one of hyperliquid, binance, bybit) |
| `hours` | query | integer | no | Window in hours, default 24 (free key 1), clamped to the plan history (Pro / API Dev 168, Desk / API Pro 9600). (range 1–9600; default 24) |
| `stepMinutes` | query | integer | no | Bar size 1 \| 5 \| 15 \| 60 \| 240 \| 1440 minutes (default: ≤ 360 bars; windows older than 8 days use hourly bars). At most 1,440 bars per call: a finer size is coarsened to the next one that fits (e.g. stepMinutes=1 over 48 hours → 5-minute bars); the answer names the size used in stepMinutes. (one of 1, 5, 15, 60, 240, 1440) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/flow/BTC?hours=24"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `stepMinutes` | integer | Bar / column width in minutes. |
| `from` | string (ISO 8601) | Start of the window (ISO 8601 UTC) or the sending side of a movement. |
| `to` | string (ISO 8601) | End of the window (ISO 8601 UTC) or the receiving side of a movement. |
| `total[]` | array of objects | Perpetual venues summed. Can have gaps: bars without collected data are left out (never sent as 0). |
| `total[].t` | string (ISO 8601) | Bar start. |
| `total[].buyUsd` | number | Taker buys (USD). |
| `total[].sellUsd` | number | Taker sells (USD). |
| `total[].delta` | number | Buys minus sells (USD). |
| `total[].cvd` | number | Cumulative delta since the window start (USD). |
| `byVenue[]` | array of objects | Split per venue. |
| `byVenue[].venue` | "hyperliquid" \| "binance" \| "bybit" | Venue of the order-flow data. |
| `byVenue[].market` | "perp" \| "spot" | perp = perpetual futures, spot = spot market. |
| `byVenue[].points[]` | array of objects | Bars of the series, oldest first. |
| `byVenue[].buyUsd` | number | Taker buys (USD). |
| `byVenue[].sellUsd` | number | Taker sells (USD). |
| `bySize[]` | array of objects | Perpetual venues summed, per print size. |
| `bySize[].bucket` | "lt10k" \| "10k_100k" \| "100k_1m" \| "gt1m" | Print size: lt10k, 10k_100k, 100k_1m, gt1m. |
| `bySize[].label` | string | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `bySize[].points[]` | array of objects | Bars of the series, oldest first. Can have gaps like total. |
| `bySize[].buyUsd` | number | Taker buys (USD). |
| `bySize[].sellUsd` | number | Taker sells (USD). |
| `whales` | object, nullable | Tracked Hyperliquid whales (either side of the trade). |
| `whales.points[]` | array of objects | Bars of the series, oldest first. |
| `whales.buyUsd` | number | Bought by tracked whales (USD). |
| `whales.sellUsd` | number | Sold by tracked whales (USD). |
| `totals` | object | Sums over the rows of this object. |
| `totals.buyUsd` | number | Taker buys (USD). |
| `totals.sellUsd` | number | Taker sells (USD). |
| `totals.delta` | number | Buys minus sells (USD). |
| `totals.trades` | integer | Prints. |
| `updatedAt` | string (ISO 8601), nullable | Newest data time of this item (ISO 8601 UTC). |
| `profile` | object | - |
| `profile.coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `profile.from` | string (ISO 8601) | Start of the window (ISO 8601 UTC) or the sending side of a movement. |
| `profile.to` | string (ISO 8601) | End of the window (ISO 8601 UTC) or the receiving side of a movement. |
| `profile.step` | number | Price step of the levels. |
| `profile.levels[]` | array of objects | Price levels, ascending. |
| `profile.totalUsd` | number | Volume (USD). |
| `profile.poc` | number, nullable | Point of control (level with the most volume). |
| `profile.valueArea` | object, nullable | Smallest range around the POC with 70 % of the volume. |
| `profile.venues[]` | array of "hyperliquid" \| "binance" \| "bybit" | Venues covered by this view. |

Example response (real data, lists shortened):

```json
{
  "data": {
    "coin": "BTC",
    "stepMinutes": 5,
    "from": "2026-10-27T12:10:00.000Z",
    "to": "2026-10-27T13:13:53.000Z",
    "total": [
      {
        "t": "2026-10-27T12:10:00.000Z",
        "buyUsd": 8807814,
        "sellUsd": 3490221,
        "delta": 5317593,
        "cvd": 5317593
      },
      {
        "t": "2026-10-27T12:15:00.000Z",
        "buyUsd": 42452634,
        "sellUsd": 11270515,
        "delta": 31182119,
        "cvd": 36499712
      }
    ],
    "byVenue": [
      {
        "venue": "hyperliquid",
        "market": "perp",
        "points": [
          {
            "t": "2026-10-27T12:10:00.000Z",
            "buyUsd": 3179356,
            "sellUsd": 973729,
            "delta": 2205627,
            "cvd": 2205627
          },
          {
            "t": "2026-10-27T12:15:00.000Z",
            "buyUsd": 11418801,
            "sellUsd": 802719,
            "delta": 10616083,
            "cvd": 12821710
          }
        ],
        "buyUsd": 74715068,
        "sellUsd": 74758104
      }
    ],
    "bySize": [
      {
        "bucket": "lt10k",
        "label": "under $10k",
        "points": [
          {
            "t": "2026-10-27T12:10:00.000Z",
            "delta": 527521,
            "cvd": 527521
          },
          {
            "t": "2026-10-27T12:15:00.000Z",
            "delta": 1823841,
            "cvd": 2351362
          }
        ],
        "buyUsd": 36401406,
        "sellUsd": 42947433
      },
      {
        "bucket": "10k_100k",
        "label": "$10k–100k",
        "points": [
          {
            "t": "2026-10-27T12:10:00.000Z",
            "delta": 491300,
            "cvd": 491300
          },
          {
            "t": "2026-10-27T12:15:00.000Z",
            "delta": 5835707,
            "cvd": 6327008
          }
        ],
        "buyUsd": 126480550,
        "sellUsd": 124510402
      }
    ],
    "whales": {
      "points": [
        {
          "t": "2026-10-27T12:10:00.000Z",
          "buyUsd": 2785171,
          "sellUsd": 3707111,
          "delta": -921940,
          "cvd": -921940
        },
        {
          "t": "2026-10-27T12:15:00.000Z",
          "buyUsd": 7444496,
          "sellUsd": 8987568,
          "delta": -1543072,
          "cvd": -2465012
        }
      ],
      "buyUsd": 98106310,
      "sellUsd": 59848803
    },
    "totals": {
      "buyUsd": 635091915,
      "sellUsd": 474350621,
      "delta": 160741294,
      "trades": 75575
    },
    "updatedAt": "2026-10-27T13:12:00.000Z",
    "profile": {
      "coin": "BTC",
      "from": "2026-10-27T12:13:53.000Z",
      "to": "2026-10-27T13:13:54.000Z",
      "step": 50,
      "levels": [
        {
          "px": 79850,
          "buyUsd": 1662982,
          "sellUsd": 536582
        },
        {
          "px": 79900,
          "buyUsd": 15664109,
          "sellUsd": 2782483
        }
      ],
      "totalUsd": 1101659798,
      "poc": 80200,
      "valueArea": {
        "lo": 80150,
        "hi": 80400
      },
      "venues": [
        "hyperliquid",
        "binance"
      ]
    }
  },
  "meta": {
    "updatedAt": "2026-10-27T13:12:00.000Z",
    "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"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/flow-coin

### GET /tape: Large-trade tape

Large-trade tape: taker prints at or above the tape threshold ($250k for BTC / ETH, $50k otherwise; one print = the fills of one taker order at one timestamp), newest first in order of arrival (id; an exchange print can arrive after a later Hyperliquid one), with the Hyperliquid taker address (public on-chain state) and whether it is a tracked whale. Bots poll forward with `after`. Free keys: BTC, ETH and HYPE, last 24 hours. Licence review: raw rows of Binance and Bybit (single liquidations, prints, order books, tickers, funding and ratios per exchange, exchange candles) are not redistributed through the API while the review of their terms is pending. Asking for such a venue answers 403 source_restricted, and meta.restricted lists the withheld venues. Aggregates (sums over venues, our own figures) stay.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional; free keys: BTC, ETH or HYPE, default all three). |
| `venue` | query | string | no | hyperliquid \| binance \| bybit (optional). (one of hyperliquid, binance, bybit) |
| `side` | query | string | no | buy \| sell = side of the taker (optional). (one of buy, sell) |
| `minUsd` | query | number | no | Minimum print size in USD on top of the tape threshold, default 0. (range 0–; default 0) |
| `sinceMinutes` | query | integer | no | Look-back window in minutes, default 60, clamped to the plan history (free key 60). (range 1–; default 60) |
| `from` | query | string | no | Window start (ISO 8601, inclusive); replaces sinceMinutes. Clamped to the plan history (meta.warnings says so). |
| `to` | query | string | no | Window end (ISO 8601, exclusive; default now): prints before it. |
| `after` | query | integer | no | Forward polling: only prints with an id above this one, oldest first (pass meta.nextAfter of the previous poll; without from / sinceMinutes the window is the plan history). Cannot be combined with cursor. (range 0–) |
| `limit` | query | integer | no | Number of items, default 100, clamped to 1–1000. (range 1–1000; default 100) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. ts,coin,side,px,usd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/tape?limit=50"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].venue` | "hyperliquid" \| "binance" \| "bybit" | Venue of the order-flow data. |
| `[].market` | "perp" \| "spot" | perp = perpetual futures, spot = spot market. |
| `[].side` | "buy" \| "sell" | Side of the taker. |
| `[].px` | number | Volume-weighted price of the print. |
| `[].usd` | number | Print size (USD). |
| `[].fills` | integer | Trades merged into the print. |
| `[].taker` | string, nullable | Hyperliquid address, lowercase. |
| `[].whale` | boolean | The taker is a tracked Hyperliquid whale. |

Example response (real data):

```json
{
  "data": [
    {
      "id": 143463,
      "ts": "2026-10-27T13:10:19.039Z",
      "coin": "BTC",
      "venue": "hyperliquid",
      "market": "perp",
      "side": "buy",
      "px": 80140.095,
      "usd": 801104,
      "fills": 57,
      "taker": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
      "whale": true
    },
    {
      "id": 143459,
      "ts": "2026-10-27T13:10:11.416Z",
      "coin": "BTC",
      "venue": "hyperliquid",
      "market": "perp",
      "side": "buy",
      "px": 80148,
      "usd": 1077619,
      "fills": 45,
      "taker": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
      "whale": true
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:19.039Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/tape?cursor=<cursor>",
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/tape

### GET /screener: Screener (every coin)

Screener: one row per Hyperliquid coin with price change 1h / 24h (Hyperliquid mark), open interest of the enabled venues and its change 1h / 24h, current and predicted Hyperliquid funding (annualised), tracked Hyperliquid long/short and Binance top-trader ratio, liquidations of the last 24 h, the nearest big liquidation cluster (signed distance, USD, side), RSI(14) of 1h and 4h candles and 24 h realised volatility (annualised; computed for the 80 largest coins by open interest, else null). Licence review: lsBinanceTop is null and coins without a Hyperliquid market are left out (meta.restricted); open interest summed over venues stays, except where exactly one withheld exchange is in the sum (then oiUsd is null: the total minus Hyperliquid would be that exchange’s value).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `sort` | query | string | no | oi (default) \| change1h \| change24h \| oiChange1h \| oiChange24h \| funding \| fundingPred \| ls \| liq24h \| cluster \| rsi1h \| rsi4h \| vol \| coin; missing values sort last. (one of oi, change1h, change24h, oiChange1h, oiChange24h, funding, fundingPred, ls, liq24h, cluster, rsi1h, rsi4h, vol, coin; default oi) |
| `dir` | query | string | no | desc (default) \| asc. (one of asc, desc; default desc) |
| `minOiUsd` | query | number | no | Minimum open interest in USD, default 0. (range 0–; default 0) |
| `limit` | query | integer | no | Number of items, default 100, clamped to 1–500. (range 1–500; default 100) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,mark,change24h,oiUsd,fundingApr,rsi1h (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/screener?sort=oi&limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].mark` | number, nullable | Hyperliquid mark; for a coin without a Hyperliquid market the mark of the enabled exchange with the largest open interest. |
| `[].change1h` | number, nullable | Price change in 1 h, fraction. |
| `[].change24h` | number, nullable | Price change in 24 h, fraction. |
| `[].oiUsd` | number, nullable | Open interest of the enabled venues (USD). |
| `[].oiChange1h` | number, nullable | Open interest change in 1 h (venues with a value at both times), fraction. |
| `[].oiChange24h` | number, nullable | Open interest change in 24 h, fraction. |
| `[].volume24hUsd` | number, nullable | Hyperliquid 24 h volume (coins without a Hyperliquid market: summed over the exchanges that report one) (USD). |
| `[].fundingApr` | number, nullable | Hyperliquid funding now, annualised fraction (null for a coin without a Hyperliquid market). |
| `[].fundingPredApr` | number, nullable | Predicted next Hyperliquid funding, annualised fraction. |
| `[].lsHl` | number, nullable | Tracked Hyperliquid long USD / short USD. |
| `[].lsBinanceTop` | number, nullable | Binance top traders long/short (positions); null when Binance is switched off. |
| `[].liq24hUsd` | number, nullable | Liquidations in 24 h (CEX as reported, Hyperliquid confirmed by fills) (USD). |
| `[].liq24hLongUsd` | number, nullable | Long liquidations in 24 h (USD). |
| `[].liq24hShortUsd` | number, nullable | Short liquidations in 24 h (USD). |
| `[].clusterDistance` | number, nullable | Signed distance mark → nearest big liquidation cluster, fraction (−0.03 = 3 % below). |
| `[].clusterUsd` | number, nullable | USD in that cluster (USD). |
| `[].clusterSide` | "long" \| "short", nullable | Dominant side of the cluster. |
| `[].rsi1h` | number, nullable | RSI(14) of 1h candles, 0–100. |
| `[].rsi4h` | number, nullable | RSI(14) of 4h candles, 0–100. |
| `[].vol24h` | number, nullable | 24 h realised volatility of 1h closes, annualised fraction. |
| `[].maxLeverage` | integer, nullable | Maximum leverage the venue allows on this market. |

Example response (real data, lists shortened):

```json
{
  "data": [
    {
      "coin": "BTC",
      "mark": 80213,
      "change1h": 0.0040556272,
      "change24h": 0.000688641654337,
      "oiUsd": 16446120328.18,
      "oiChange1h": 0.0045461206,
      "oiChange24h": 0.0368906985,
      "volume24hUsd": 2288160809.64,
      "fundingApr": 0.1095,
      "fundingPredApr": 0.1095,
      "lsHl": 0.9684562624,
      "lsBinanceTop": null,
      "liq24hUsd": 20272992.33,
      "liq24hLongUsd": 10729795.17,
      "liq24hShortUsd": 9543197.16,
      "clusterDistance": -0.1179733958,
      "clusterUsd": 111932021.19,
      "clusterSide": "long",
      "rsi1h": 57.1619899374,
      "rsi4h": 32.6956309664,
      "vol24h": 0.3393247089,
      "maxLeverage": 40
    },
    {
      "coin": "ETH",
      "mark": 2329.29,
      "change1h": 0.0067381251,
      "change24h": 0.0047405426,
      "oiUsd": 9985278064.77,
      "oiChange1h": 0.006078191,
      "oiChange24h": 0.0244856051,
      "volume24hUsd": 852734460.37,
      "fundingApr": 0.1095,
      "fundingPredApr": 0.1095,
      "lsHl": 0.9831029407,
      "lsBinanceTop": null,
      "liq24hUsd": 14616024.28,
      "liq24hLongUsd": 5920035.9,
      "liq24hShortUsd": 8695988.38,
      "clusterDistance": -0.0662390686,
      "clusterUsd": 106766633.66,
      "clusterSide": "long",
      "rsi1h": 59.0517061828,
      "rsi4h": 33.6493956044,
      "vol24h": 0.4253224428,
      "maxLeverage": 25
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:52.327Z",
    "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"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/screener

### GET /funding/predicted: Predicted next funding

Predicted next funding per coin for Hyperliquid, Binance and Bybit (from Hyperliquid predictedFundings, refreshed every 5 minutes): hourly rate, annualised rate, funding interval and next funding time per venue. Disabled venues are left out, and so are Binance / Bybit during the licence review (meta.restricted). Sorted by Hyperliquid open interest.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `limit` | query | integer | no | Number of items, default 300, clamped to 1–500. (range 1–500; default 300) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,byVenue (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/funding/predicted?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].byVenue` | object | Per venue (hyperliquid, binance, bybit; switched-off venues are missing). |
| `[].byVenue.hyperliquid` | object | - |
| `[].byVenue.binance` | object | - |
| `[].byVenue.bybit` | object | - |
| `[].updatedAt` | string (ISO 8601) | Newest data time of this item (ISO 8601 UTC). |

Example response (real data):

```json
{
  "data": [
    {
      "coin": "BTC",
      "byVenue": {
        "hyperliquid": {
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "intervalHours": 1,
          "nextFundingTime": "2026-10-27T13:00:00.000Z"
        }
      },
      "updatedAt": "2026-10-27T13:12:11.002Z"
    },
    {
      "coin": "ETH",
      "byVenue": {
        "hyperliquid": {
          "fundingHourly": 0.0000125,
          "fundingApr": 0.1095,
          "intervalHours": 1,
          "nextFundingTime": "2026-10-27T13:00:00.000Z"
        }
      },
      "updatedAt": "2026-10-27T13:12:11.002Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:12:11.002Z",
    "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"
    },
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/funding-predicted

### GET /funding/spreads: Cross-venue funding spreads

Cross-venue funding spread per coin: the venue with the highest and the lowest annualised funding (current rates or predicted next rates), the spread per year and per day and the smaller open interest of the two legs. A difference between published rates, not an executable return (fees, price moves, funding times). Licence review: a spread involving Binance / Bybit is listed only when at least 3 venues quote the coin and both ends are exchanges whose rates are withheld (a published rate at one end plus the spread would give the other exchange’s rate); such legs keep their venue, their own fundingApr and openInterestUsd are null (meta.restricted).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `coin` | query | string | no | Only this coin (optional). |
| `basis` | query | string | no | current (default) \| predicted. (one of current, predicted; default current) |
| `minOiUsd` | query | number | no | Minimum open interest of the thinner leg in USD, default 0. (range 0–; default 0) |
| `limit` | query | integer | no | Number of items, default 100, clamped to 1–500. (range 1–500; default 100) |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. coin,high,low,spreadApr (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/funding/spreads?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].coin` | string | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].basis` | "current" \| "predicted" | current = published rates now, predicted = predicted next rates. |
| `[].high` | object | - |
| `[].high.venue` | "hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx" | Trading venue. |
| `[].high.fundingApr` | number, nullable | Annualised funding, fraction; null for an exchange whose raw rates are withheld during the licence review (meta.restricted). |
| `[].high.intervalHours` | number, nullable | Funding interval in hours (null when unknown). |
| `[].high.openInterestUsd` | number, nullable | Open interest on this venue; null when unknown or withheld (USD). |
| `[].low` | object | - |
| `[].low.venue` | "hyperliquid" \| "lighter" \| "binance" \| "bybit" \| "okx" | Trading venue. |
| `[].low.fundingApr` | number, nullable | Annualised funding, fraction; null for an exchange whose raw rates are withheld during the licence review (meta.restricted). |
| `[].low.intervalHours` | number, nullable | Funding interval in hours (null when unknown). |
| `[].low.openInterestUsd` | number, nullable | Open interest on this venue; null when unknown or withheld (USD). |
| `[].spreadApr` | number | high − low, annualised fraction. |
| `[].spreadDaily` | number | Spread per day (spreadApr / 365), fraction. |
| `[].minOpenInterestUsd` | number, nullable | Smaller open interest of the two legs; null when a leg is withheld (USD). |
| `[].venues` | integer | Venues with a rate for this coin. |
| `[].updatedAt` | string (ISO 8601) | Newest data time of this item (ISO 8601 UTC). |

Example response (real data, lists shortened):

```json
{
  "data": [
    {
      "coin": "BTW",
      "basis": "current",
      "high": {
        "venue": "bybit",
        "fundingApr": null,
        "intervalHours": null,
        "openInterestUsd": null
      },
      "low": {
        "venue": "binance",
        "fundingApr": null,
        "intervalHours": null,
        "openInterestUsd": null
      },
      "spreadApr": 0.6816156,
      "spreadDaily": 0.00186744,
      "minOpenInterestUsd": null,
      "venues": 2,
      "updatedAt": "2026-10-27T13:11:50.718Z"
    },
    {
      "coin": "JCT",
      "basis": "current",
      "high": {
        "venue": "binance",
        "fundingApr": null,
        "intervalHours": null,
        "openInterestUsd": null
      },
      "low": {
        "venue": "bybit",
        "fundingApr": null,
        "intervalHours": null,
        "openInterestUsd": null
      },
      "spreadApr": 0.3818703,
      "spreadDaily": 0.00104622,
      "minOpenInterestUsd": null,
      "venues": 2,
      "updatedAt": "2026-10-27T13:11:50.718Z"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:50.718Z",
    "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"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/funding-spreads

### GET /sentiment: Blockmetric Sentiment index

Blockmetric Sentiment: our own 0–100 market sentiment index (0 extreme fear, 100 extreme greed) from data we collect: BTC price momentum and volatility, funding of BTC and ETH perpetuals on Binance and Bybit, BTC open interest change, the Binance long/short account ratio, the liquidation imbalance and the positioning of tracked Hyperliquid whales. Every input is ranked against its own daily values of the previous 365 days and weighted (method, /methodology#sentiment); an input without enough history or data is left out and the others are renormalised (status collecting, missing or off). Returns the current value (recomputed every 15 minutes; daily = true when it is the latest 00:00 UTC value) with the score and points of every input, and the daily history at 00:00 UTC. Inputs leave only as scores, never as raw values.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `days` | query | integer | no | Days of daily history, default 90, clamped to 1–1095 and to the plan history (free key 30 days, keyless 24 h). (range 1–1095; default 90) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/sentiment?days=30"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `name` | string | Always "Blockmetric Sentiment". |
| `current` | object, nullable | Current value with its breakdown; null while less than method.minWeight of the weight has enough history. |
| `current.at` | string (ISO 8601) | Time of the value. |
| `current.score` | number | 0–100. |
| `current.label` | "Extreme fear" \| "Fear" \| "Neutral" \| "Greed" \| "Extreme greed" | - |
| `current.daily` | boolean | true: no fresh intraday value, this is the latest daily value at 00:00 UTC. |
| `current.weightUsed` | integer | Sum of the weights of the inputs that counted (of 100; at least method.minWeight). |
| `current.components[]` | array of objects | Affected parts of the service. |
| `history[]` | array of objects | Daily values at 00:00 UTC, oldest first; days without a score are left out. |
| `history[].day` | string | UTC date of the 00:00 value (YYYY-MM-DD). |
| `history[].at` | string (ISO 8601) | 00:00 UTC of that day. |
| `history[].score` | number | 0–100. |
| `history[].label` | "Extreme fear" \| "Fear" \| "Neutral" \| "Greed" \| "Extreme greed" | - |
| `history[].weightUsed` | integer | Sum of the weights of the inputs that counted (of 100). |
| `firstDay` | string, nullable | First day with a score. |
| `method` | object | The fixed rules of the index (/methodology#sentiment). |
| `method.lookbackDays` | integer | Days of daily values every input is ranked against. |
| `method.minSamples` | integer | Earlier daily values an input needs before it counts. |
| `method.minWeight` | integer | Minimum weight (of 100) of the counted inputs for a value. |
| `method.bands[]` | array of objects | Label bands on the rounded score. |

Example response (real data, lists shortened):

```json
{
  "data": {
    "name": "Blockmetric Sentiment",
    "current": {
      "at": "2026-10-28T00:23:56.224Z",
      "score": 72.6,
      "label": "Greed",
      "daily": false,
      "weightUsed": 85,
      "components": [
        {
          "id": "momentum",
          "name": "Price momentum",
          "weight": 25,
          "status": "ok",
          "samples": 365,
          "score": 46.6,
          "points": 13.7
        },
        {
          "id": "volatility",
          "name": "Volatility",
          "weight": 15,
          "status": "ok",
          "samples": 365,
          "score": 97.3,
          "points": 17.2
        }
      ]
    },
    "history": [
      {
        "day": "2026-10-26",
        "at": "2026-10-26T00:00:00.000Z",
        "score": 72.8,
        "label": "Greed",
        "weightUsed": 85
      },
      {
        "day": "2026-10-27",
        "at": "2026-10-27T00:00:00.000Z",
        "score": 73.1,
        "label": "Greed",
        "weightUsed": 85
      }
    ],
    "firstDay": "2025-10-15",
    "method": {
      "lookbackDays": 365,
      "minSamples": 21,
      "minWeight": 50,
      "bands": [
        {
          "from": 0,
          "to": 24,
          "label": "Extreme fear"
        },
        {
          "from": 25,
          "to": 44,
          "label": "Fear"
        }
      ]
    }
  },
  "meta": {
    "updatedAt": "2026-10-28T00:23:56.224Z",
    "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-28T00:24:00.000Z"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/sentiment

### GET /radar/events: Risk radar events

Risk radar events (whale moves, big liquidations, cascades, funding extremes, OI spikes, hacks, depegs, TVL drops, CEX outflows), newest first. Licence review: single liquidation orders reported by Binance / Bybit (big_liquidation, the record "largest single liquidation") are not published (also not in the stream and webhooks; a page can then hold fewer than limit items, so keep paging with meta.nextCursor); their funding / open-interest events keep venue and direction without the exchange’s figures; cascades and market-wide extremes leave out per-exchange amounts and keep their totals only where the total does not give one exchange’s amount.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `kinds` | query | string | no | Comma-separated: whale_open, whale_close, whale_liquidated, big_liquidation, liq_cascade, funding_extreme, funding_flip, oi_spike, hack, depeg, tvl_drop, cex_outflow, hl_market_change, hl_manipulation, hl_adl, oracle_deviation, vault_drawdown, liq_extreme, protocol_outflow, incident, big_transfer, stablecoin_mint, stablecoin_burn, dex_whale_trade, risk_wallet_move, risk_wallet_listed (optional). |
| `minSeverity` | query | integer | no | 1 info, 2 notable, 3 major, 4 critical; default 1. (range 1–4; default 1) |
| `coin` | query | string | no | Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive. |
| `since` | query | string | no | ISO 8601 time; only events after it (optional, a polling cursor). Clamped to the plan history (free key 30 days, keyless 24 h; meta.warnings says so). |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. id,ts,kind,severity,coin,title (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/radar/events?minSeverity=2&limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | integer | Stable id of the item; on paginated feeds the order key together with ts. |
| `[].ts` | string (ISO 8601) | Time of the event (ISO 8601 UTC). |
| `[].kind` | string (enum) | Risk radar event kind. |
| `[].severity` | "1" \| "2" \| "3" \| "4" | 1 info, 2 notable, 3 major, 4 critical. |
| `[].coin` | string, nullable | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].title` | string | One-line factual title in our own words. |
| `[].body` | string, nullable | Details in our own words, or null. |
| `[].data` | any | Kind-specific details (JSON) or null. |
| `[].source` | string, nullable | Data source (radar, defillama, …). |

Example response (real data):

```json
{
  "data": [
    {
      "id": 5468,
      "ts": "2026-10-27T13:11:00.282Z",
      "kind": "funding_extreme",
      "severity": 1,
      "coin": "xyz:PURRDAT",
      "title": "xyz:PURRDAT funding at +128% APR on Hyperliquid",
      "body": "Hourly rate +0.0146% (longs pay shorts) · open interest $11.6M · mark $9.2451.",
      "data": {
        "venue": "hyperliquid",
        "fundingApr": 1.28301588,
        "fundingHourly": 0.000146463,
        "openInterestUsd": 11556929.71,
        "mark": 9.2451
      },
      "source": "hyperliquid"
    },
    {
      "id": 5467,
      "ts": "2026-10-27T13:10:12.766Z",
      "kind": "whale_close",
      "severity": 1,
      "coin": "BTC",
      "title": "Whale reduced BTC short by $1.1M on Hyperliquid (now $8M)",
      "body": "0x01e2…e977 · size 100.00 BTC · mark $80,154 · entry $80,324 · liq. price $97,456 · 5x cross. Change seen between polls at 13:02 UTC and 13:10 UTC.",
      "data": {
        "venue": "hyperliquid",
        "address": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
        "label": null,
        "accountValue": 1602940,
        "action": "decrease",
        "side": "short",
        "prevSide": "short",
        "usd": 1078098.55,
        "usdDelta": -1078098.55,
        "sizeDelta": -13.45034,
        "size": 100,
        "prevSize": 113.45034,
        "positionUsd": 8015400,
        "prevPositionUsd": 9093498.55,
        "price": 80154,
        "entryPx": 80324.3,
        "liqPx": 97456.3192644,
        "leverage": 5,
        "leverageType": "cross",
        "pnlUsd": null,
        "pnlBasis": null,
        "prevPolledAt": "2026-10-27T13:02:51.706Z",
        "polledAt": "2026-10-27T13:10:12.766Z",
        "markMin": null,
        "markMax": null,
        "positionEventId": 224941
      },
      "source": "hyperliquid"
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:11:00.282Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/radar/events?cursor=<cursor>",
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/radar-events

### GET /security/incidents: Security incidents

Security view, newest first: detector events (Hyperliquid manipulation patterns, possible ADL, oracle / mark deviations, HLP vault drawdowns, market-wide liquidation surges, stablecoin depegs from Chainlink feeds read on-chain, outflows from bridge and lending contracts listed in the protocols’ own docs) and curated incidents (our own factual summary, amount with its primary source, status, post-mortem and transaction links). Pattern detectors are matches, not confirmed attacks. Paginated over the newest 500 items.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `origin` | query | string | no | all (default) \| detector \| curated. (one of all, detector, curated; default all) |
| `type` | query | string | no | Incident type (exploit, hack, rug_pull, oracle_manipulation, market_manipulation, bridge, key_compromise, governance_attack, phishing, depeg, other) or detector type (tvl_drop, outflow, adl, oracle_deviation, vault_drawdown, liquidation_surge) (optional). (one of adl, bridge, depeg, exploit, governance_attack, hack, key_compromise, liquidation_surge, market_manipulation, oracle_deviation, oracle_manipulation, other, outflow, phishing, rug_pull, tvl_drop, vault_drawdown) |
| `chain` | query | string | no | ethereum \| arbitrum \| base \| optimism \| polygon \| bnb \| avalanche \| solana \| bitcoin \| tron \| hyperliquid \| sui \| aptos \| ronin \| harmony \| fantom \| starknet \| blast \| linea \| zksync \| mantle \| sonic \| ton \| xrp \| other (optional). (one of ethereum, arbitrum, base, optimism, polygon, bnb, avalanche, solana, bitcoin, tron, hyperliquid, sui, aptos, ronin, harmony, fantom, starknet, blast, linea, zksync, mantle, sonic, ton, xrp, other) |
| `minSeverity` | query | integer | no | 1 info, 2 notable, 3 major, 4 critical; default 1. (range 1–4; default 1) |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. id,date,title,amountUsd (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/security/incidents?limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | string | "evt_<radar event id>" (detector) or "inc_<incident id>" (curated). |
| `[].origin` | "detector" \| "curated" | detector = found by our detectors in market data; curated = an incident written up by us with primary sources. |
| `[].ts` | string (ISO 8601) | Event time (detector) or publication time (curated). |
| `[].date` | string | UTC day of the incident (YYYY-MM-DD). |
| `[].kind` | string | Radar event kind ("incident" for curated items). |
| `[].type` | string | Incident type (exploit, oracle_manipulation, …) or detector type (depeg, outflow, adl, …). |
| `[].severity` | "1" \| "2" \| "3" \| "4" | 1 info, 2 notable, 3 major, 4 critical. |
| `[].title` | string | One-line factual title in our own words. |
| `[].summary` | string, nullable | Our own factual text. |
| `[].chains[]` | array of string | Chains involved. |
| `[].coin` | string, nullable | Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA). |
| `[].amountUsd` | number, nullable | Reported loss / flow (USD). |
| `[].status` | string, nullable | Curated: unknown \| ongoing \| funds_frozen \| partially_recovered \| recovered \| not_recovered \| resolved. |
| `[].url` | string | Evidence page on the website. |
| `[].links[]` | array of objects | Curated: primary-source links (post-mortem, announcement, tx, address, governance) and coverage links. |
| `[].links[].kind` | string | Kind of the item (enum of this field). |
| `[].links[].url` | string | Link (absolute URL). |
| `[].links[].label` | string | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `[].data` | any | Detector: the evidence numbers of the event (JSON). Curated: recoveredUsd, amountSource, txs. |

Example response (real data, lists shortened):

```json
{
  "data": [
    {
      "id": "evt_5146",
      "origin": "detector",
      "ts": "2026-10-27T06:37:54.627Z",
      "date": "2026-10-27",
      "kind": "oracle_deviation",
      "type": "oracle_deviation",
      "severity": 1,
      "title": "xyz:UNITREE mark price −2.5% from its oracle on Hyperliquid",
      "summary": "Mark $94.732 vs oracle $97.203 on 2 consecutive checks · open interest $28M. A wide mark/oracle gap moves liquidation prices and funding.",
      "chains": [
        "hyperliquid"
      ],
      "coin": "xyz:UNITREE",
      "amountUsd": null,
      "status": null,
      "url": "https://blockmetric.io/radar/5146",
      "links": [],
      "data": {
        "venue": "hyperliquid",
        "check": "mark_vs_oracle",
        "mark": 94.732,
        "oracle": 97.203,
        "deviation": -0.0254210261,
        "change": -0.0254210261,
        "openInterestUsd": 27977203.45
      }
    },
    {
      "id": "evt_5127",
      "origin": "detector",
      "ts": "2026-10-27T05:48:11.489Z",
      "date": "2026-10-27",
      "kind": "protocol_outflow",
      "type": "outflow",
      "severity": 1,
      "title": "Net outflow of $24.1M (−14%) from Aave v3 (Ethereum) aEthUSDC in 80 min",
      "summary": "USDC −$24.1M at 0x98c23e9d8f34fefb1b7bd6a91b7ff122f4e16f5c (ethereum), $177M before. Large withdrawals, rebalancing or a migration look the same as an exploit; not verified. The aToken holds the available (not borrowed) liquidity; borrows lower it as much as withdrawals do.",
      "chains": [
        "ethereum"
      ],
      "coin": null,
      "amountUsd": 24095140.25,
      "status": null,
      "url": "https://blockmetric.io/radar/5127",
      "links": [],
      "data": {
        "name": "Aave v3 (Ethereum) aEthUSDC",
        "protocol": "Aave v3 (Ethereum)",
        "contractId": "aave-v3-ausdc",
        "contract": "0x98c23e9d8f34fefb1b7bd6a91b7ff122f4e16f5c",
        "chain": "ethereum",
        "usd": 24095140.25,
        "change": -0.1361881816,
        "prevUsd": 176925339.41,
        "byAsset": {
          "USDC": {
            "before": 176990826.019,
            "after": 152886767.271,
            "usd": -24095140.25
          }
        },
        "windowMinutes": 80,
        "sinceTs": "2026-10-27T04:28:05.859Z",
        "fromBlock": 26281648,
        "toBlock": 26282048,
        "sourceUrl": "https://github.com/bgd-labs/aave-address-book/blob/main/src/AaveV3Ethereum.sol",
        "transfers": [
          {
            "hash": "0xea72f1cdf7eef0ef8a74201a46fd24f0bb9414e766dce1f46f0f65afc3f47268",
            "to": "0xaf9ff2179b3fb87e5d7d07302727dc3bbd5e3bd5",
            "asset": "USDC",
            "amount": 24745927.9355,
            "usd": 24736771.94,
            "block": 26281883
          },
          {
            "hash": "0x4d321dd1ded9ea22001ce1467efc674db7413019a2be1d2eaf1cd3ac5bdceec6",
            "to": "0xd2011d314acaa68e5401e7f5aec3be6d2c574dcf",
            "asset": "USDC",
            "amount": 881504.745416,
            "usd": 881178.59,
            "block": 26281934
          }
        ]
      }
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T06:37:54.627Z",
    "source": "hyperliquid,binance,bybit,publicnode,chainlink_onchain,protocol_registry",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/security/incidents?cursor=<cursor>",
    "restricted": [
      "binance",
      "bybit"
    ]
  }
}
```

Docs: https://blockmetric.io/docs/api/security-incidents

### GET /security/wallets: Listed wallets (OFAC, FBI, post-mortems)

Listed wallets: addresses that an official source lists, with the source’s own category, wording, date and a link to the listing. Sources: the OFAC SDN list (every digital currency address, re-read daily; an address OFAC removes is delisted automatically and no longer returned), FBI / IC3 public service announcements that list addresses, and addresses an official incident post-mortem names (reviewed before they are published). `listing` reads "Listed as <category> by <source>, <date>"; for OFAC the date is the first SDN list in which we saw the address. No person is named and no counterparty is labelled. `tracked` = we follow its on-chain movements (EVM addresses on Ethereum, Arbitrum and Base, Bitcoin); other networks are listed only. Newest activity first, then newest listing. Paginated.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `category` | query | string | no | sanctioned \| stolen_funds \| exploit \| drainer \| phishing \| other (optional). (one of sanctioned, stolen_funds, exploit, drainer, phishing, other) |
| `network` | query | string | no | Address family: evm, bitcoin, tron, litecoin, monero … (optional). (one of evm, bitcoin, tron, litecoin, monero, bitcoin_cash, dash, zcash, solana, ripple, dogecoin, bitcoin_gold, bitcoin_sv, verge, ethereum_classic, bnb_beacon, other) |
| `source` | query | string | no | ofac_sdn \| fbi_ic3 \| incident (optional). (one of ofac_sdn, fbi_ic3, incident) |
| `q` | query | string | no | Address or part of one (optional). |
| `movedDays` | query | integer | no | Only addresses with a tracked movement in the last N days (1–400, optional). (range 1–400) |
| `limit` | query | integer | no | Number of items, default 100, clamped to 1–500. (range 1–500; default 100) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. address,network,category,source (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/security/wallets"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].address` | string | The address as listed (EVM and bech32 lower case, other formats as the source publishes them). |
| `[].network` | string | Address family: evm (one key on every EVM chain), bitcoin, tron, litecoin, monero … |
| `[].tracked` | boolean | We follow its on-chain movements (EVM on Ethereum, Arbitrum, Base; Bitcoin). |
| `[].category` | "sanctioned" \| "stolen_funds" \| "exploit" \| "drainer" \| "phishing" \| "other" | The source’s classification. |
| `[].source` | "ofac_sdn" \| "fbi_ic3" \| "incident" | ofac_sdn \| fbi_ic3 \| incident. |
| `[].sourceLabel` | string | How the source is named. |
| `[].sourceUrl` | string | Link to the listing at the source. |
| `[].sourceDate` | string, nullable | Date of the listing (YYYY-MM-DD). |
| `[].listing` | string | "Listed as <category> by <source>, <date>". |
| `[].detail` | string, nullable | The source’s own wording. Never a name. |
| `[].assets` | string, nullable | OFAC: currency tickers of the address fields. |
| `[].incidentId` | integer, nullable | Curated incident of the listing. |
| `[].firstSeen` | string (ISO 8601) | When we first imported the listing. |
| `[].lastMoveTs` | string (ISO 8601), nullable | Newest tracked movement of the address. |
| `[].movements` | integer | Tracked movements of the address. |
| `[].balanceUsd` | number, nullable | Last known balance on the scanned EVM chains at our prices, null when not read or not priced (USD). |
| `[].balanceAt` | string (ISO 8601), nullable | When the balance was read. |

Example response (real data):

```json
{
  "data": [
    {
      "address": "0xe4c9a7f68b1eba4508f54f07f7378847318dd1a3",
      "network": "evm",
      "tracked": true,
      "category": "sanctioned",
      "source": "ofac_sdn",
      "sourceLabel": "OFAC SDN list",
      "sourceUrl": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=58887",
      "sourceDate": "2026-10-28",
      "listing": "Listed as sanctioned by OFAC SDN list (on the list as of 2026-10-28)",
      "detail": "Program DPRK2",
      "assets": "ETH",
      "incidentId": null,
      "firstSeen": "2026-11-03T10:36:54.671Z",
      "lastMoveTs": null,
      "movements": 0,
      "balanceUsd": null,
      "balanceAt": null
    },
    {
      "address": "0x761edd5e4546229a0bd35ae99b4d3d01cf4a3510",
      "network": "evm",
      "tracked": true,
      "category": "sanctioned",
      "source": "ofac_sdn",
      "sourceLabel": "OFAC SDN list",
      "sourceUrl": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=58886",
      "sourceDate": "2026-10-28",
      "listing": "Listed as sanctioned by OFAC SDN list (on the list as of 2026-10-28)",
      "detail": "Program DPRK2",
      "assets": "ETH",
      "incidentId": null,
      "firstSeen": "2026-11-03T10:36:54.671Z",
      "lastMoveTs": null,
      "movements": 0,
      "balanceUsd": null,
      "balanceAt": null
    }
  ],
  "meta": {
    "updatedAt": "2026-11-03T10:36:54.671Z",
    "source": "ofac_sdn",
    "sources": [
      "ofac_sdn"
    ],
    "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: OFAC SDN list (U.S. Treasury)",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-11-03T10:47:00.000Z"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/security/wallets?cursor=<cursor>"
  }
}
```

Docs: https://blockmetric.io/docs/api/security-wallets

### GET /security/wallets/{address}: Listed wallet detail

One listed wallet: every active listing of the address (category, source, wording, date, link), its last known balances on the scanned EVM chains (native ETH and the curated tokens, at our own prices) and its tracked movements, newest first (every token on Ethereum, Arbitrum and Base, native ETH on Ethereum, Bitcoin; within the plan history). A token outside our curated list is marked unverifiedToken and never priced. The other side of a movement keeps only its own sourced label (exchange proof of reserves, protocol docs) or none. 404 when the address has no active listing.

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `address` | path | string | yes | The address as the source lists it (EVM 0x + 40 hex in any case, Bitcoin, Tron …). |
| `limit` | query | integer | no | Number of movements, default 25, clamped to 1–100. (range 1–100; default 25) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/security/wallets/0x51e9d833ecae4e8d9d8be17300aee6d3398c135d"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `address` | string | The address as listed. |
| `network` | string | Address family (evm, bitcoin, tron …). |
| `tracked` | boolean | We follow its on-chain movements. |
| `listings[]` | array of objects | Every active listing of the address, oldest first. |
| `listings[].category` | "sanctioned" \| "stolen_funds" \| "exploit" \| "drainer" \| "phishing" \| "other" | The source’s classification: sanctioned (OFAC), stolen_funds, exploit, drainer, phishing, other. |
| `listings[].source` | "ofac_sdn" \| "fbi_ic3" \| "incident" | ofac_sdn (OFAC SDN list), fbi_ic3 (FBI / IC3 announcement) or incident (official post-mortem). |
| `listings[].sourceLabel` | string | How the source is named, e.g. "OFAC SDN list", "FBI (IC3 PSA I-022625-PSA)". |
| `listings[].sourceUrl` | string | Link to the listing at the source. |
| `listings[].sourceDate` | string, nullable | Date of the listing (YYYY-MM-DD): the publication for FBI and post-mortems, the first SDN list that contained the address for OFAC. |
| `listings[].listing` | string | The one claim, in the source’s terms: "Listed as <category> by <source>, <date>". |
| `listings[].detail` | string, nullable | The source’s own wording (FBI quote, OFAC sanctions programs, role in the post-mortem). Never a name. |
| `listings[].assets` | string, nullable | OFAC: the currency tickers of the address fields, e.g. "ETH, USDT". |
| `listings[].incidentId` | integer, nullable | Curated incident the listing belongs to (/security/incidents/<id>). |
| `listings[].firstSeen` | string (ISO 8601) | When we first imported the listing. |
| `balances[]` | array of objects | Last known balances per scanned EVM chain and the Hyperliquid account of the same key. |
| `balances[].chain` | string | ethereum \| arbitrum \| base \| hyperliquid. |
| `balances[].checkedAt` | string (ISO 8601) | When the balances were read. |
| `balances[].balances` | object | Units per asset (native ETH and the curated tokens with a balance; on hyperliquid the account value in USD as accountValue). |
| `balances[].usd` | number, nullable | Their value at our prices (USD). |
| `movements[]` | array of objects | Tracked movements, newest first, within the plan history. |
| `movements[].id` | integer | Movement id. |
| `movements[].ts` | string (ISO 8601) | Block time. |
| `movements[].chain` | string | ethereum \| arbitrum \| base \| bitcoin. |
| `movements[].type` | string | transfer \| exchange_in \| exchange_out \| exchange_exchange \| mint \| burn \| bridge \| dex_buy \| dex_sell. |
| `movements[].asset` | string | Asset symbol; "(unverified)" after a symbol outside our curated token list (the token’s own claim). |
| `movements[].amount` | number | Units of the asset. |
| `movements[].usd` | number, nullable | Value at our price; null = price unavailable (always for unverified tokens) (USD). |
| `movements[].priceSource` | string, nullable | Basis of usd, as in /movements. |
| `movements[].title` | string | Factual one-liner with the short source, e.g. "Listed wallet (OFAC) moved 10 ETH ($30K) to Binance on Ethereum". |
| `movements[].listedAddress` | string | The listed address of the movement. |
| `movements[].listedSide` | "from" \| "to" | Which side of the movement is the listed address. |
| `movements[].from` | object | Start of the window (ISO 8601 UTC) or the sending side of a movement. |
| `movements[].to` | object | End of the window (ISO 8601 UTC) or the receiving side of a movement. |
| `movements[].unverifiedToken` | boolean | Token outside our curated list: never priced. |
| `movements[].block` | integer | Block height. |
| `movements[].tx` | string | Transaction hash. |
| `movements[].txUrl` | string, nullable | Transaction on the official explorer. |

Example response (real data):

```json
{
  "data": {
    "address": "0x51e9d833ecae4e8d9d8be17300aee6d3398c135d",
    "network": "evm",
    "tracked": true,
    "listings": [
      {
        "category": "stolen_funds",
        "source": "fbi_ic3",
        "sourceLabel": "FBI (IC3 PSA I-022625-PSA)",
        "sourceUrl": "https://www.ic3.gov/PSA/2025/PSA250226",
        "sourceDate": "2025-02-26",
        "listing": "Listed as holding stolen funds by FBI (IC3 PSA I-022625-PSA), 2025-02-26",
        "detail": "The following Ethereum addresses are holding or have held assets from the theft, and are operated by or closely connected to North Korean TraderTraitor actors",
        "assets": null,
        "incidentId": null,
        "firstSeen": "2026-11-03T10:36:54.590Z"
      }
    ],
    "balances": [],
    "movements": []
  },
  "meta": {
    "updatedAt": "2026-11-03T10:36:54.590Z",
    "source": "fbi_ic3",
    "sources": [
      "fbi_ic3"
    ],
    "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: FBI / IC3 public service announcements",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 365,
      "historyFrom": "2025-11-03T10:47:00.000Z"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/security-wallets-address

### GET /movements: Whale movements (on-chain + Hyperliquid)

Whale movements, newest first, in one feed: large on-chain transfers (Ethereum, Arbitrum, Base from $1M, stablecoins from $5M; Bitcoin from $1M, change excluded), exchange in- and outflows (exchanges’ own proof-of-reserves addresses), stablecoin mints / burns, bridge transfers, large swaps on the biggest Uniswap v3 / Aerodrome pools (from $500K) and Hyperliquid whale position changes and large Hyperliquid trades (from $1M). Labels only from cited sources; every other wallet is named by its address. USD: stablecoins at their latest fresh Chainlink answer (USDT, USDC, DAI / USD), WBTC at the Hyperliquid BTC mark × Chainlink WBTC / BTC, other assets at the Hyperliquid mark; no fresh price → usd null and priceSource "unavailable" (such items never pass minUsd). priceSource and details.value say which. CEX trade prints are not included.

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. Paginated.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | query | string | no | Comma list of transfer \| exchange_in \| exchange_out \| exchange_exchange \| mint \| burn \| bridge \| dex_buy \| dex_sell \| perp_position \| big_trade (optional, default all). |
| `chain` | query | string | no | ethereum \| arbitrum \| base \| bitcoin \| hyperliquid (optional). (one of ethereum, arbitrum, base, bitcoin, hyperliquid) |
| `asset` | query | string | no | Asset symbol, e.g. BTC, ETH, USDT, USDC (ETH also finds WETH, BTC finds WBTC, USDT finds USDT0) (optional). |
| `minUsd` | query | number | no | Minimum value in USD on top of the feed thresholds, default 0. (range 0–; default 0) |
| `labelled` | query | boolean | no | true = only items with a labelled sender or receiver. (one of true, false; default false) |
| `address` | query | string | no | Only movements of this EVM or Bitcoin address (includes smaller transfers of addresses watched by alert rules). |
| `since` | query | string | no | ISO time; clamped to the plan history. |
| `limit` | query | integer | no | Number of items, default 50, clamped to 1–500. (range 1–500; default 50) |
| `cursor` | query | string | no | Next page: the value of meta.nextCursor from the previous response (keep the other parameters unchanged). Cursors are signed: an edited cursor answers 400; paging stops at the plan history. |
| `fields` | query | string | no | Comma-separated fields of every item to return, e.g. ts,type,asset,usd,from,to (case-insensitive). All other fields are left out, so large lists get much smaller; an unknown name answers 400 with the list of fields. Default: every field. |
| `format` | query | string | no | json (default: the { data, meta } envelope) \| csv (the rows with a header line; nested values as JSON text) \| ndjson (one JSON object per row and line). csv and ndjson carry the meta block in headers: Link rel="next" and X-Blockmetric-Next-Cursor (next page), X-Blockmetric-Next-After (forward polling), X-Blockmetric-Updated-At, X-Blockmetric-Warnings, X-Blockmetric-License. Errors stay JSON. (one of json, csv, ndjson; default json) |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/movements?minUsd=5000000&limit=20"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `[].id` | string | "m<id>" on-chain movement, "p<id>" Hyperliquid position change, "t<id>" Hyperliquid trade print. |
| `[].ts` | string (ISO 8601) | Block time (on-chain) or event time. |
| `[].type` | string (enum) | Type of the item (enum of this field). |
| `[].chain` | string | ethereum \| arbitrum \| base \| bitcoin \| hyperliquid. |
| `[].asset` | string | Asset symbol (USDT, USDC, ETH, WETH, BTC, WBTC, …) or Hyperliquid coin. |
| `[].amount` | number, nullable | Units of the asset. |
| `[].usd` | number, nullable | Value at our price: stablecoins at the fresh Chainlink answer, WBTC at Hyperliquid BTC mark × Chainlink WBTC / BTC, other assets at the Hyperliquid mark; null = price unavailable (USD). |
| `[].priceSource` | string, nullable | Basis of usd: "chainlink:USDC/USD" (Chainlink feed answer; details.value names the answer and its round time), "hl:ETH" (Hyperliquid mark), "hl:BTC*chainlink:WBTC/BTC", "unavailable" (no fresh price, usd null), "hyperliquid" (position / trade value). |
| `[].title` | string | Factual one-liner, e.g. "50M USDT ($50M) moved to Binance from 0x12ab…cd34 on Ethereum" (a wallet without a sourced label is named by its address). |
| `[].context` | string, nullable | Context from our own records, e.g. "largest USDC mint this week". |
| `[].from` | object, nullable | Start of the window (ISO 8601 UTC) or the sending side of a movement. |
| `[].from.address` | string, nullable | Wallet or contract address (EVM lowercase 0x…, or Bitcoin). |
| `[].from.label` | string, nullable | Label with a cited source, else null (no sourced label). |
| `[].from.url` | string, nullable | Explorer page. |
| `[].to` | object, nullable | End of the window (ISO 8601 UTC) or the receiving side of a movement. |
| `[].to.address` | string, nullable | Wallet or contract address (EVM lowercase 0x…, or Bitcoin). |
| `[].to.label` | string, nullable | Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified). |
| `[].to.url` | string, nullable | Link (absolute URL). |
| `[].txUrl` | string, nullable | Transaction on the public block explorer of its chain. |
| `[].details` | object | Readable details (chain, amount, value basis, block, venue, label source …). |

Example response (real data):

```json
{
  "data": [
    {
      "id": "p224941",
      "ts": "2026-10-27T13:10:12.766Z",
      "type": "perp_position",
      "chain": "hyperliquid",
      "asset": "BTC",
      "amount": 13.45034,
      "usd": 1078098.55,
      "priceSource": "hyperliquid",
      "title": "Whale 0x01e2…e977 reduced $1.1M BTC short on Hyperliquid",
      "context": null,
      "from": {
        "address": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
        "label": null,
        "url": "https://hypurrscan.io/address/0x01e273fc08012db1b75e8ca93f8139bfac2ee977"
      },
      "to": null,
      "txUrl": null,
      "details": {
        "venue": "Hyperliquid (position poll)",
        "change": "decrease short · $1.1M",
        "mark": "$80,154"
      }
    },
    {
      "id": "t143459",
      "ts": "2026-10-27T13:10:11.416Z",
      "type": "big_trade",
      "chain": "hyperliquid",
      "asset": "BTC",
      "amount": 13.4453635774,
      "usd": 1077619,
      "priceSource": "hyperliquid",
      "title": "Wallet 0x01e2…e977 bought $1.1M of BTC on Hyperliquid perps (tracked whale)",
      "context": null,
      "from": {
        "address": "0x01e273fc08012db1b75e8ca93f8139bfac2ee977",
        "label": null,
        "url": null
      },
      "to": null,
      "txUrl": null,
      "details": {
        "venue": "Hyperliquid perp",
        "price": "$80,148",
        "fills": "45 fills of one taker order"
      }
    }
  ],
  "meta": {
    "updatedAt": "2026-10-27T13:10:12.766Z",
    "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"
    },
    "nextCursor": "<cursor>",
    "nextUrl": "https://api.blockmetric.io/v1/movements?cursor=<cursor>"
  }
}
```

Docs: https://blockmetric.io/docs/api/movements

### GET /exchange-flows: Exchange on-chain flows

On-chain exchange flows: inflow, outflow and net (in − out) per exchange and asset over a window, from every scanned transfer into or out of the exchange’s own proof-of-reserves addresses (all sizes on Ethereum, Arbitrum and Base; large transactions on Bitcoin). Internal moves between two addresses of one exchange are left out. coverageFrom = first hour with data (earlier flows are unknown, not zero).

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.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hours` | query | integer | no | Window in hours, default 24, clamped to 1–2160 and to the plan history. (range 1–2160; default 24) |
| `exchange` | query | string | no | Only this exchange, e.g. Binance (optional). |
| `asset` | query | string | no | Only this asset family, e.g. BTC, ETH, USDT, USDC (optional). |

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/exchange-flows?hours=24"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `windowHours` | integer | Window in hours. |
| `since` | string (ISO 8601) | Start of the window (full hour). |
| `rows[]` | array of objects | The rows of this view. |
| `rows[].exchange` | string | Exchange name (as labelled from its own proof-of-reserves addresses). |
| `rows[].asset` | string | Asset symbol (stablecoins, ETH, BTC …). |
| `rows[].chains[]` | array of string | Chains involved. |
| `rows[].inUsd` | number | Inflow (USD). |
| `rows[].outUsd` | number | Outflow (USD). |
| `rows[].netUsd` | number | In − out (USD). |
| `rows[].inAmount` | number | Units of the asset that flowed in (priced and unpriced). |
| `rows[].outAmount` | number | Units of the asset that flowed out. |
| `rows[].inCount` | integer | Transfers in. |
| `rows[].outCount` | integer | Transfers out. |
| `rows[].unpricedInCount` | integer | Transfers in without a fresh price (not in any USD figure). |
| `rows[].unpricedOutCount` | integer | Transfers out without a fresh price. |
| `rows[].unpricedInAmount` | number | Units of the unpriced inflows. |
| `rows[].unpricedOutAmount` | number | Units of the unpriced outflows. |
| `byExchange[]` | array of objects | Totals per exchange over all assets (priced transfers only). |
| `byExchange[].exchange` | string | Exchange name (as labelled from its own proof-of-reserves addresses). |
| `byExchange[].inUsd` | number | Inflow (USD). |
| `byExchange[].outUsd` | number | Outflow (USD). |
| `byExchange[].netUsd` | number | In − out (USD). |
| `coverageFrom` | string (ISO 8601), nullable | First hour with data. |
| `updatedAt` | string (ISO 8601), nullable | Latest hour with data. |

Example response (real data, lists shortened):

```json
{
  "data": {
    "windowHours": 24,
    "since": "2026-10-26T13:00:00.000Z",
    "rows": [
      {
        "exchange": "Binance",
        "asset": "BTC",
        "chains": [
          "bitcoin",
          "ethereum"
        ],
        "inUsd": 792332203.07,
        "outUsd": 1437054542.99,
        "inAmount": 9902.49893212,
        "outAmount": 18013.6408404,
        "inCount": 104,
        "outCount": 103,
        "unpricedInCount": 0,
        "unpricedOutCount": 0,
        "unpricedInAmount": 0,
        "unpricedOutAmount": 0,
        "netUsd": -644722339.93
      },
      {
        "exchange": "Binance",
        "asset": "USDC",
        "chains": [
          "arbitrum",
          "base"
        ],
        "inUsd": 878273639.87,
        "outUsd": 837616419.36,
        "inAmount": 878546014.508,
        "outAmount": 837853633.855,
        "inCount": 8093,
        "outCount": 5694,
        "unpricedInCount": 0,
        "unpricedOutCount": 0,
        "unpricedInAmount": 0,
        "unpricedOutAmount": 0,
        "netUsd": 40657220.51
      }
    ],
    "byExchange": [
      {
        "exchange": "Binance",
        "inUsd": 2591399030.16,
        "outUsd": 3290579582.33,
        "netUsd": -699180552.17
      }
    ],
    "coverageFrom": "2026-10-23T17:00:00.000Z",
    "updatedAt": "2026-10-27T13:00:00.000Z"
  },
  "meta": {
    "updatedAt": "2026-10-27T13:00:00.000Z",
    "source": "onchain-rpc,mempool,cex_por",
    "sources": [
      "cex_por",
      "publicnode"
    ],
    "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/exchange-flows

### GET /stats: 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.

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 parameters.

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/stats"
```

Response `data`:

| Field | Type | 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. |

Example response (real data, lists shortened):

```json
{
  "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"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/stats

### GET /me: The calling key: plan, limits, usage

The caller: the key (masked, never the secret: name, scopes, expiry, IP allowlist, browser origins), the plan and its limits, the account’s usage of the current minute and UTC day, overage, the history window and the venues the licence gate withholds. Not counted against the limits and never 429: ask it when a client is limited. Keyless public access (X-Blockmetric-Access: public) gets the public tier and key null.

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 parameters.

```bash
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/me"
```

Response `data`:

| Field | Type | Description |
|---|---|---|
| `keyless` | boolean | true = keyless public access (X-Blockmetric-Access: public). |
| `key` | object, nullable | The calling key; null with keyless access. |
| `key.masked` | string | Prefix and last 4 characters (bm_live_…ABCD), never the key. |
| `key.name` | string, nullable | Your label of the key. |
| `key.createdAt` | string (ISO 8601) | Created. |
| `key.expiresAt` | string (ISO 8601), nullable | Expiry; null = none. |
| `key.lastUsedAt` | string (ISO 8601), nullable | Last request with the key (updated at most once a minute). |
| `key.scopes[]` | array of "api" \| "node" | api = this data API, node = the node gateway. |
| `key.ipAllowlist[]` | array of string | CIDR ranges the key is limited to; empty = any address. |
| `key.allowedOrigins[]` | array of string | Browser origins that may use the key; empty = server use only. |
| `plan` | "free" \| "pro" \| "desk" \| "api_dev" \| "api_pro" | The caller's plan. |
| `limits` | object | Limits of the plan. |
| `limits.perMinute` | integer | Requests per minute (account, all keys). |
| `limits.perDay` | integer | Requests per UTC day. |
| `limits.webhookEndpoints` | integer | Webhook endpoints the plan includes. |
| `limits.streams` | integer | Concurrent live streams the plan includes. |
| `usage` | object | Requests of the account in the current minute and UTC day (this request is not counted). |
| `usage.minute` | object, nullable | The current one-minute window; null when unknown. |
| `usage.day` | object, nullable | The current UTC day; null when unknown. |
| `overage` | object | Requests beyond the daily limit (billed per 1,000 calls up to the monthly cap). |
| `overage.available` | boolean | The plan can bill requests beyond the daily limit (API Dev, API Pro). |
| `overage.enabled` | boolean | Overage is switched on for the account. |
| `overage.capUsd` | number, nullable | Monthly cap of the overage cost in USD. |
| `overage.pricePer1kUsd` | number, nullable | Price per 1,000 calls beyond the daily limit in USD. |
| `overage.monthCalls` | integer | Calls billed as overage this UTC month. |
| `overage.monthCostUsd` | number | Overage cost this UTC month (USD). |
| `access` | object | Data scope of the plan. |
| `access.historyDays` | integer | Days of history the plan reads. |
| `access.delayMinutes` | integer | Feed delay in minutes (0 = real time). |
| `access.heatmapTimeframes[]` | array of string (enum) | Heatmap intervals of the plan. |
| `access.liqMapCoins` | integer, nullable | Coins with liquidation levels now (top by open interest); null = every coin. |
| `access.commercial` | boolean | Whether the licence allows commercial use (see meta.license). |
| `restrictedVenues[]` | array of "binance" \| "bybit" \| "okx" | Exchanges whose raw rows the API withholds during the licence review. |

Example response (real data):

```json
{
  "data": {
    "keyless": true,
    "key": null,
    "plan": "free",
    "limits": {
      "perMinute": 10,
      "perDay": 300,
      "webhookEndpoints": 0,
      "streams": 0
    },
    "usage": {
      "minute": {
        "limit": 10,
        "used": 0,
        "remaining": 10,
        "resetsAt": "2026-10-27T13:14:53.000Z"
      },
      "day": {
        "limit": 300,
        "used": 0,
        "remaining": 300,
        "resetsAt": "2026-10-28T00:00:00.000Z"
      }
    },
    "overage": {
      "available": false,
      "enabled": false,
      "capUsd": null,
      "pricePer1kUsd": null,
      "monthCalls": 0,
      "monthCostUsd": 0
    },
    "access": {
      "historyDays": 1,
      "delayMinutes": 0,
      "heatmapTimeframes": [
        "15m",
        "1h"
      ],
      "liqMapCoins": null,
      "commercial": false
    },
    "restrictedVenues": [
      "binance",
      "bybit"
    ]
  },
  "meta": {
    "updatedAt": "2026-10-27T13:13:53.378Z",
    "source": "blockmetric",
    "sources": [],
    "plan": "free",
    "delayMinutes": 0,
    "commercial": false,
    "license": {
      "id": "public",
      "display": true,
      "attributionRequired": true,
      "attribution": "Data by Blockmetric",
      "redistribution": false,
      "mauCap": null,
      "terms": "https://blockmetric.io/terms#api-license"
    },
    "attribution": {
      "text": "Data by Blockmetric",
      "url": "https://blockmetric.io/"
    },
    "access": {
      "historyDays": 1,
      "historyFrom": "2026-10-26T13:14:00.000Z"
    }
  }
}
```

Docs: https://blockmetric.io/docs/api/me

## Live stream (API Pro)

GET https://api.blockmetric.io/v1/stream: Server-Sent Events (text/event-stream) with every radar event as soon as it is stored, in the webhook envelope. One connection counts as one request against the per-minute limit. Send Last-Event-ID (EventSource does this automatically on reconnect; "evt_<id>" is accepted too) to receive what you missed: events stored in the last 15 minutes after that id, at most 500. Without it the stream starts with new events only. At most 2 open streams per account (429 stream_limit otherwise; a dropped connection frees its slot within 45 s).

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `kinds` | query | string | no | Comma-separated event kinds (whale_open, whale_close, whale_liquidated, whale_near_liq, big_liquidation, liq_cascade, funding_extreme, funding_flip, oi_spike, record, smart_money, hack, depeg, tvl_drop, cex_outflow, hl_market_change, hl_manipulation, hl_adl, oracle_deviation, vault_drawdown, liq_extreme, protocol_outflow, incident, big_transfer, stablecoin_mint, stablecoin_burn, dex_whale_trade, risk_wallet_move, risk_wallet_listed); default all. |
| `minSeverity` | query | integer | no | 1 info, 2 notable, 3 major, 4 critical; default 1. |
| `coin` | query | string | no | One coin or up to 20 comma-separated (BTC,ETH,kPEPE); case-insensitive. Events without a coin are then not sent. |
| `lastEventId` | query | integer | no | Alternative to the Last-Event-ID header (resume after this event id). |

## Webhooks (API Dev, API Pro)

Signed HTTPS POSTs of every radar event to your endpoint within seconds of detection: whale moves, big liquidations, cascades, funding extremes and flips, OI spikes, whales near liquidation, records, exploits, depegs, TVL drops and CEX outflows. Signature: `Blockmetric-Signature: t=<unix seconds>,v1=<64 hex chars>[,v1=<64 hex chars>]`, HMAC-SHA256, key = the whole signing secret string (including "whsec_") as UTF-8 bytes, output lowercase hex, over `<t> + "." + <raw request body bytes>`, tolerance 300 s. Any 2xx status within 10 seconds. The response body is ignored (the first 2 KiB are shown in the delivery log). Attempt 1 immediately, then 1 min, 5 min, 30 min, 2 h and 12 h after the previous failure (6 attempts over ~15 h). Timeouts, network errors, 3xx, 4xx (except 410) and 5xx count as failures. At-least-once delivery: deduplicate on the envelope id.

| Field | Type | Description |
|---|---|---|
| `id` | string | "evt_<radar event id>": stable across retries and identical to Blockmetric-Event-Id; use it to deduplicate. Test events: "evt_test_<hex>". |
| `type` | string | The event kind (one of EVENT_TYPES) or "test". |
| `created` | integer | Unix seconds of the event (data.ts). |
| `createdAt` | string | The same moment as ISO 8601 (API 1.14.0). Every other time in the API is ISO. |
| `data` | object | Exactly one item of GET /api/v1/radar/events: id, ts, kind, severity (1–4), coin, title, body, data, source. data.truncated: true when an oversized event was shortened (fetch it via /radar/events). |

Event types: whale_open, whale_close, whale_liquidated, whale_near_liq, big_liquidation, liq_cascade, funding_extreme, funding_flip, oi_spike, record, smart_money, hack, depeg, tvl_drop, cex_outflow, hl_market_change, hl_manipulation, hl_adl, oracle_deviation, vault_drawdown, liq_extreme, protocol_outflow, incident, big_transfer, stablecoin_mint, stablecoin_burn, dex_whale_trade, risk_wallet_move, risk_wallet_listed, test.

Data from public sources, without guarantee. Not investment advice. Terms: https://blockmetric.io/terms#api-license.