Contents
Conventions & glossary
The same envelope, units and names on every endpoint. Learn them once.
Response envelope
Success: { data, meta }. Errors: { error: { code, message, doc_url, request_id, retryable, param? } }. New fields may appear at any time; ignore the ones you do not know.
| Field | Description |
|---|---|
updatedAtstring (ISO 8601) · nullable | Newest data timestamp in the response; null when there is no data yet. |
sourcestring | Venues / public sources the data comes from, comma-separated. |
sourcesarray | 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. |
delayMinutesinteger | Feed delay of the caller's plan in minutes (0 = real time). |
commercialboolean | Whether the caller's licence allows commercial use (with attribution). |
licenseobject | What the caller may do with this response (see /terms#api-license). |
attributionobject | Ready-made credit (API 1.13.0). Display licences show it next to the data (license.attributionRequired). |
accessobject | The history window of the caller’s plan (API 1.14.0): rows before historyFrom are not served. |
nextCursorstring · nullable | Paginated lists only: pass as ?cursor= for the next page; null on the last page. |
nextUrlstring (URL) · nullable | Paginated lists only: the complete URL of the next page (same parameters + cursor); null on the last page. |
nextAfterinteger | Forward polling (?after=) only: pass as ?after= on the next poll: the id of the newest row returned, else the id that was given. |
warningsarray | Only when the request was not served exactly as asked (API 1.14.0); absent otherwise. |
restrictedarray | Only on endpoints the licence review touches: exchanges whose raw rows are withheld from this response (aggregates stay). Absent once their data is licensed. |
A real meta object
{
"updatedAt": "2026-10-27T13:12:16.218Z",
"source": "hyperliquid,binance,bybit",
"sources": [
"hyperliquid",
"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: Blockmetric Research · Binance · Bybit",
"url": "https://blockmetric.io/"
},
"access": {
"historyDays": 365,
"historyFrom": "2025-10-27T13:14:00.000Z"
},
"restricted": [
"binance",
"bybit"
]
}Units
Numbers are plain JSON numbers. When a name carries a unit, that is the unit.
| What | Format | Examples |
|---|---|---|
| Times | ISO 8601 in UTC, e.g. 2026-10-23T12:00:00.000Z | ts, updatedAt, snapshotAt |
| Durations | The unit is in the name | ageSec, lifetimeSec, colMs, avgHoldMin |
| Money | US dollars as numbers, rounded to cents | usd, longUsd, openInterestUsd |
| Prices | In the quote currency of the venue (USD, USDT or USDC); other non-integers keep up to 12 significant digits | price, mark, entryPx, liqPx |
| Funding | Fractions per period: 0.0001 = 0.01 %; *Apr fields are annualised fractions | fundingHourly, fundingApr |
| Distances and shares | Fractions: 0.01 = 1 %. Fields ending in Pct are fractions too (bucketPct 0.005 = 0.5 %) | liqDistance, distancePct, freshUsdShare |
| Ratios | Plain numbers, long divided by short | ratio, accountRatio |
| Sizes | In coins (base units) unless the name says Usd | qty, size |
Field names
A few names mean nearly the same thing on different endpoints. This is what each one is.
price · px · mark- price is a trade or liquidation price; px a price level (order book, tape); mark the venue mark price.
qty · size- Amount in coins; the direction is in side.
oiUsd · openInterestUsd- Both are open interest in USD (oiUsd in the screener); new fields use openInterestUsd.
t · ts- Both are ISO 8601 times; t is the start of a bar or bucket in a series, ts the time of a single event.
o · h · l · c- Open, high, low, close per column in compact series (order flow); /candles spells them out (open, high, low, close).
side- long | short for positions and liquidations (the side of the liquidated position); buy | sell for trades.
coin- The Hyperliquid name: BTC, ETH, kPEPE, HIP-3 markets as xyz:GOLD. Case-insensitive in requests.
venue- hyperliquid, binance, bybit, okx. Only enabled venues appear (meta.sources).
Every common field name (165)
15m- Change over 15 minutes.
1h- Change over 1 hour.
24h- Change over 24 hours.
3d- Change over 3 days.
4h- Change over 4 hours.
7d- Change over 7 days.
address- Wallet or contract address (EVM lowercase 0x…, or Bitcoin).
ageSec- Seconds since the last update.
allTime- All time.
asset- Asset symbol (stablecoins, ETH, BTC …).
avgHoldMin- Average holding time in minutes (open → close pairs).
band- Band around the mid, fraction (0.01 = 1 %).
basis- current = published rates now, predicted = predicted next rates.
binance- Binance published long/short ratios (only while Binance is switched on and licensed for the API).
body- Details in our own words, or null.
book- Open tracked positions of the wallet, else null.
bucketFraction- Bucket width of the layer as a fraction of the mark (0.001 = 0.1 %).
buckets- Price buckets.
bybit- Bybit published long/short ratio (only while Bybit is switched on and licensed for the API).
byExchange- Totals per exchange over all assets (priced transfers only).
byVenue- Split per venue.
c- Close price per column.
chains- Chains involved.
close- Close price of the bucket.
closes- Position closes we observed.
clusterObservations- Liquidation clusters observed for the hit-rate statistic.
clusters- With ?clusters=N: the largest buckets above and below the mark of the newest column with a snapshot.
clustersReached- Of those, clusters the price reached.
cohort- Cohort key within its dimension.
coin- Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA).
coins- Number of coins.
components- Affected parts of the service.
count- Number of items (liquidations, positions …) in the group.
createdAt- The same moment as `created`, ISO 8601 UTC.
currentMonth- Availability of the current UTC month.
day- Last 24 hours.
delayMinutes- Minutes the events are delayed for the caller’s plan (0 = real time).
depth- Resting liquidity within bands around the mid (1 / 2 / 5 %).
dim- Cohort dimension: size (account value) or pnl (all-time PnL).
distance- Signed distance from the price, fraction (−0.03 = 3 % below).
endedAt- When it ended (ISO 8601 UTC); null while active.
error- The error.
events- Events of this view (newest first) or their count.
exchange- Exchange name (as labelled from its own proof-of-reserves addresses).
expectedIntervalSec- How often the job is expected to run, in seconds.
fetchedAt- When the portfolio history was read.
firstSeen- First time this item was observed (ISO 8601 UTC).
focus- Heatmap, long/short and whale-label tables.
from- Start of the window (ISO 8601 UTC) or the sending side of a movement.
h- High price per column.
health- ok, warn (delayed) or bad (down).
heatmap- Order book heatmap over time (with ?hours=), else null.
heatmapCoins- Coins with heatmap snapshots.
heatmapSnapshots- Stored heatmap snapshots.
heatmapUpdatedAt- Newest heatmap snapshot.
hedged- Delta-neutral books (long and short notional nearly equal).
hi- Upper edge.
high- High price of the bucket.
high_fills- Wallets with very many fills per hour (market making). Deprecated: use highFills.
highFills- Wallets with very many fills per hour (market making).
hl- Hyperliquid from the tracked positions; null when no tracked position exists.
id- Stable id of the item; on paginated feeds the order key together with ts.
impact- maintenance, minor or major.
inAmount- Units of the asset that flowed in (priced and unpriced).
inCount- Transfers in.
job- Collector job id (internal name; see /status for the plain-English feeds).
k- Wallets needed for a convergence event.
kind- Kind of the item (enum of this field).
l- Low price per column.
label- Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified).
largest- Largest single liquidation in the window (of a venue the API serves), null when there is none.
lastPolledAt- Last time the wallet was read from Hyperliquid (ISO 8601 UTC), null = not yet.
lastRun- Last successful run (ISO 8601 UTC).
lastSeen- Last time this item was observed (ISO 8601 UTC).
layer- Storage layer the data was read from (enum of this field).
levels- Price levels, ascending.
leverage- Leverage of the position (notional / margin).
liqLevels- Liquidation map: coins, price buckets and the last update.
liqPx- Liquidation price of the position.
liquidations24h- Liquidations in the last 24 hours.
lo- Lower edge.
longAccounts- Tracked wallets with a long position.
longShortRows- Stored long/short rows.
longShortUpdatedAt- Newest long/short row.
longUsd- Long notional in USD.
longWallets- Wallets on the long side.
low- Low price of the bucket.
many_positions- Wallets with many open positions (market makers, multi-asset algos). Deprecated: use manyPositions.
manyPositions- Wallets with many open positions (market makers, multi-asset algos).
map- Stop / take-profit buckets of the coin (with ?coin=), else null.
mark- Hyperliquid mark price.
market- perp = perpetual futures, spot = spot market.
markets- Markets per venue.
maxDrawdown- Largest peak-to-trough fall as a fraction of the account value at the peak (0.17 = 17 %).
maxDrawdownUsd- Largest peak-to-trough fall of the account value in USD.
maxLeverage- Maximum leverage the venue allows on this market.
method- How the figures are computed, in plain words.
mid- Mid price between the best bid and ask.
minDistance- Closest distance to the price, fraction.
minUsd- Minimum position change per wallet in USD.
month- Last 30 days.
newestFetch- Newest open-orders read among the covered wallets.
o- Open price per column (null = no trade).
okx- OKX published long/short ratio (only while OKX is switched on and licensed for the API).
oldestFetch- Oldest open-orders read among the covered wallets.
open- Open price of the bucket.
orders- Number of orders.
origin- detector = found by our detectors in market data; curated = an incident written up by us with primary sources.
outAmount- Units of the asset that flowed out.
outCount- Transfers out.
overlay- Items to draw on top of the liquidation heatmap.
pnlCohort- PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M.
points- Bars of the series, oldest first.
polled- Wallets read at least once.
positionCount- Number of open positions.
positionEvents- Stored whale position changes.
positions- Number of positions.
price- Price in the quote currency of the venue (USD / USDT / USDC).
px- Price (lower edge of a price bucket where the object is a bucket).
radar- Stored radar events.
rangeFraction- Range of the layer around the mark as a fraction (0.5 = ±50 %).
rank- Rank in the current sort.
resolvedAt- End of the incident (ISO 8601 UTC); null while open.
resting_orders- Wallets with many resting limit orders (a quoted book). Deprecated: use restingOrders.
restingOrders- Wallets with many resting limit orders (a quoted book).
risk- Risk figures from the Hyperliquid portfolio history (top traders), else null.
rows- The rows of this view.
settings- Detector settings in force.
severity- 1 info, 2 notable, 3 major, 4 critical.
shortAccounts- Tracked wallets with a short position.
shortUsd- Short notional in USD.
shortWallets- Wallets on the short side.
side- Position side (long / short); for trades and orders the side named in the description.
sizeCohort- Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M.
source- Data source id or name of this item.
sources- Per data source: health and last run.
startedAt- Start of the incident (ISO 8601 UTC).
status- State of the item (enum of this field).
step- Price step of the buckets.
stepMinutes- Bar / column width in minutes.
styles- Style tags from observed behaviour (scalper, swing, position, high_turnover, high_leverage, mostly_long, mostly_short).
t- Start of the bucket or bar (ISO 8601 UTC).
telegramCards- Cards posted to the public Telegram channel.
tf- Bucket interval (5m, 15m, 1h, …).
title- One-line factual title in our own words.
to- End of the window (ISO 8601 UTC) or the receiving side of a movement.
top- Upper edge of the price bucket.
total- Total number.
totals- Sums over the rows of this object.
ts- Time of the event (ISO 8601 UTC).
turnover- Wallets whose 30-day volume is a large multiple of the account value (market making / HFT).
type- Type of the item (enum of this field).
updatedAt- Newest data time of this item (ISO 8601 UTC).
url- Link (absolute URL).
usd- Notional in USD.
vault- Hyperliquid vaults (including HLP).
venue- Trading venue the row comes from.
venues- Venues covered by this view.
wallets- Number of distinct wallets.
week- Last 7 days.
whaleLabels- Public wallet labels with a cited source.
windowHours- Window in hours.
windowMin- Window of a convergence in minutes.
wins- Of those, closes with a profit.
withPositions- Wallets with at least one open position.
Definitions of the market metrics (liquidation heatmap, CVD, funding spread, smart money …) are in the metrics library; trading terms in the glossary.
Venues
Venue ids in requests and responses. A venue that is switched off answers 400 invalid_param, and its data disappears from every response, totals included.
- hyperliquid
- lighter
- binance · aggregates only
- bybit · aggregates only
- okx · off
Sources and licence
Every response names its sources (meta.sources) and what you may do with it (meta.license).
Exchange data: aggregates only. Raw rows of Binance and Bybit (single liquidations, trades, order books, tickers, per-exchange funding and ratios) are not redistributed through the API while their licence review is pending, also not as single-liquidation radar events, in webhooks or the stream. Totals and Blockmetric's own figures built from them stay available where they cannot be turned back into one exchange's value (a funding spread needs at least three venues and no published rate at either end); asking for such a venue explicitly answers
403 source_restricted. Responses list the withheld venues in meta.restricted. Details: data sources.| meta.license.id | Who | What you may do |
|---|---|---|
public | No key | Keyless public access: personal and non-commercial use; when you show the data, show the linked credit "Data by Blockmetric". |
personal | Free, Pro, Desk | Your own personal use only. No display to anybody else, no sharing of keys or data. |
internal | API Dev | Internal use within one organisation (research, dashboards, bots for your own team). No display to third parties. |
display | API Pro | Display in your own product to your end users with the visible attribution "Data by Blockmetric" (linked), up to 50,000 monthly active users. No raw redistribution or resale. |
enterprise | Contract | Redistribution, white-label, data feeds and dataset licences, SLA and invoicing: individual yearly contract from $12,000. |
When you show the data, use meta.attribution: the finished credit line ("Data by Blockmetric · Source: …") with its link. Full terms: API licence.
Code snippets in these docs are licensed under MIT-0: copy them into your own code without attribution. The SDKs, CLI and MCP server will be, once published, Apache-2.0; the name Blockmetric is not licensed (forks must be renamed). Data from the API is governed by the API terms; third-party exchange data by the exchange’s terms.