API reference
REST + JSON over HTTPS, read-only. Every endpoint with its parameters, response fields, a real example and a live console. API 1.24.0.
Contents
Base URL
Every endpoint is a GET below this URL and answers JSON.
https://api.blockmetric.io/v1curl -s -H "X-Blockmetric-Access: public" \
"https://api.blockmetric.io/v1/liquidations/summary?hours=24"X-Blockmetric-Access: public runs without a key (free-tier data, 24 h of history, 10 requests a minute and 300 a day per IP address). A free key gives you 30 days of history (the heatmap: the last 24 hours) and your own limits (see authentication).
Endpoints
35 read-only endpoints, plus a live stream and signed webhooks.
Markets
- GET
/marketsMarket state of a venueLatest market state of one venue: mark, oracle, funding (hourly and annualised), open interest, 24h volume, premium, max leverage. - GET
/fundingCross-venue funding boardCross-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. - GET
/coinsHyperliquid coinsHyperliquid coins with market data, largest open interest first, with the number of tracked positions and whether a liquidation map exists. - GET
/long-shortLong/short positioningLong/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. - GET
/candles/{coin}Price candles (OHLC)Price candles (OHLC) of a Hyperliquid coin, oldest first. - GET
/screenerScreener (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). - GET
/funding/predictedPredicted next fundingPredicted 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. - GET
/funding/spreadsCross-venue funding spreadsCross-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. - GET
/sentimentBlockmetric Sentiment indexBlockmetric 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.
Liquidations
- GET
/liquidationsLiquidations feedMarket-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. - GET
/liquidations/summaryLiquidation totalsLiquidation totals of the last hours (default 24): long/short USD and count, per venue, the 50 coins with the most USD, the largest single liquidation and an hourly series. - GET
/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. - GET
/heatmap/{coin}Liquidation heatmap over timeLiquidation 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. - GET
/heatmap/{coin}/open-interestOpen interest added per price bandWhere 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. - GET
/heatmap/{coin}/walletsWallets with their liquidation price in a bandTracked 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). - GET
/scoreboardCluster 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.
Whales
- GET
/positions/topLargest positionsLargest 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). - GET
/whalesWhale leaderboardWhale 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. - GET
/whales/feedWhale position changesWhale position changes (open, close, increase, decrease, flip, liquidated), newest first. - GET
/wallets/{address}Wallet detailOne 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. - GET
/whales/stopsWhale stop / TP mapStop / 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. - GET
/tradersTrader leaderboardTrader 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. - GET
/cohortsCohort positioningPositioning 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. - GET
/smart-moneySmart-money convergenceSmart-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. - GET
/movementsWhale 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). - GET
/exchange-flowsExchange on-chain flowsOn-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).
Order flow
- GET
/orderbook/{coin}Order book liquidity and wallsOrder 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. - GET
/flow/{coin}Taker flow (CVD) and volume profileTaker 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. - GET
/tapeLarge-trade tapeLarge-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.
Radar
- GET
/radar/eventsRisk radar eventsRisk radar events (whale moves, big liquidations, cascades, funding extremes, OI spikes, hacks, depegs, TVL drops, CEX outflows), newest first. - GET
/security/incidentsSecurity incidentsSecurity 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). - GET
/security/walletsListed 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. - GET
/security/wallets/{address}Listed wallet detailOne 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).
Meta
- GET
/statsCoverage and freshnessCoverage and freshness: tracked wallets and positions, markets per venue, event counts, liquidation-map size and the last run of every collector job. - GET
/meThe calling key: plan, limits, usageThe 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.
Guides
QuickstartYour first request in 60 seconds. No key needed for the first one.RecipesStep-by-step builds with complete code: alert bots, scanners, backtests, agents.Authentication & limitsKeys, headers, rate limits and the daily quota of your plan.Pagination & cachingCursors, time windows, ETag and polling without waste.Conventions & glossaryUnits, names, the response envelope, sources and licence.ErrorsEvery error code with causes and fixes.WebhooksSigned radar events pushed to your server, with verification code.Live stream (SSE)Server-Sent Events with resume, in cURL, JavaScript and Python.AI agents & LLMsllms.txt, the full reference as Markdown and tool definitions.Changelog & versioningWhat changed, and what we promise not to break.
Testing
The API only reads, so there is no separate test mode. Every call is safe to repeat.
- Before you have a key: send
X-Blockmetric-Access: publicto use the same endpoints on the free tier. - In the browser: every endpoint page has a "Try it" console, and the explorer builds a shareable link per request.
- Webhooks: "Send test event" on the account page delivers a signed
testevent to your endpoint at once. - In CI: mock against the OpenAPI document and the real example responses on each endpoint page.
Downloads
Generated from the same source as this reference, so they always match the server.
- OpenAPI 3.1 (JSON) · YAML (code generators, API tools, AI agents)
- Postman collection · environment (set apiKey once and every endpoint is ready; Insomnia imports it too)
- blockmetric.http (VS Code REST Client and JetBrains HTTP client)
- The full reference as Markdown · llms.txt (for LLMs and agents)
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.