Contents
AI agents & LLMs
Everything an agent needs to call the API correctly, in formats models read well.
Files for models
Generated from the same source as this reference, so an agent never reads outdated parameters.
/llms.txtis the map: what the API does, the docs pages and every endpoint in one line each./docs/api.md(also/developers/llms-full.txt) is the complete reference as Markdown: parameters, response fields, a curl example and a real response per endpoint./llms-skill.mdis an agent skill (SKILL.md) on how to fetch the data and how to present it./api/v1/openapi.jsonis OpenAPI 3.1 for tool and function calling; every operation has an id and typed parameters.
A system prompt that works
Paste it into your agent's instructions.
You can read live crypto derivatives data from the https://api.blockmetric.io/v1 REST API (read-only JSON).
The full reference is at https://blockmetric.io/docs/api.md. Read it before the first call.
Without a key, send the header "X-Blockmetric-Access: public" (free tier, 24 h of history, 10 requests a minute and 300 a day per IP address).
State the data time (meta.updatedAt, UTC) and credit "Data by Blockmetric" with the sources in meta.attribution.
Report facts only. Never turn the data into buy or sell advice.No key needed to start
Agents can call every endpoint with X-Blockmetric-Access: public (the free tier, with 24 h of history, 10 requests a minute and 300 a day per IP address). Give the agent a key for more history and its own limits.
Never put a key into a prompt or a chat. Use an environment variable the tool reads. Authentication & limits
MCP server
21 read-only tools for the liquidation heatmap, liquidations, whales, funding, order flow, radar events and more, for Claude, Cursor and any MCP client.
The MCP server package is being prepared for release. Until then an agent reaches the same data through the REST API with the files above, no package needed.
get_liquidation_heatmap- Where liquidations WOULD happen for one coin: the liquidation heatmap over time built from real tracked Hyperliquid positions. Arguments:
coin*,hours,tf,end,top get_liquidation_map- Current liquidation levels of one coin from tracked Hyperliquid positions: USD of long and short positions per price bucket right now, with totals. Arguments:
coin*,top get_liquidations- Liquidations that HAPPENED: totals of the last hours (long/short USD, per venue, top coins, largest single liquidation) plus the latest individual liquidations the data licence allows, optionally only large ones (min_usd) or one side. Arguments:
hours,coin,venue,side,min_usd,limit get_whales- Largest tracked Hyperliquid wallets with public labels (and the label source), open notional, all-time PnL, largest position and its distance to liquidation. Arguments:
sort,coin,labelled,limit get_wallet- One tracked Hyperliquid wallet: account value, open positions with leverage and liquidation prices, totals and the latest position changes. Arguments:
address* get_funding- Funding rates per coin across Hyperliquid and the exchanges the data licence allows (annualised, as fractions) and the spread between venues. Arguments:
coin,limit get_long_short- Long/short positioning per coin: Hyperliquid from tracked positions (USD ratio) and, where the data licence allows, the account ratios the exchanges publish. Arguments:
coin,limit get_events- Risk radar events, newest first: whale moves, whales near liquidation, big liquidations, cascades, funding extremes and flips, open interest spikes, records, exploits/hacks, stablecoin depegs, TVL drops, exchange outflows. Arguments:
kinds,min_severity,coin,limit get_candles- OHLC price candles of one coin (UTC-aligned) with volume: the price change, high and low over the window plus the newest candles. Arguments:
coin*,tf,limit,from,to get_screener- Every coin in one table: price and open-interest change, funding now and predicted, long/short, liquidations in 24 h, nearest liquidation cluster, RSI and volatility. Arguments:
sort,dir,coin,min_oi_usd,limit get_orderbook- Order book liquidity of one coin: depth within bands around the mid (bids vs asks, imbalance) and the largest walls with their status (active, pulled before the price arrived, filled). Arguments:
coin*,venue,walls get_order_flow- Taker flow of one coin over a window: buy vs sell volume, delta and cumulative volume delta in total, per venue, by print size and for tracked whales, plus the volume profile (point of control, value area). Arguments:
coin*,hours,venue get_large_trades- The newest large taker prints (trades above the tape threshold) with side, price, size and whether a tracked whale was the taker. Arguments:
coin,venue,side,min_usd,minutes,limit get_movements- Large on-chain transfers and whale moves, newest first: exchange in/outflows, transfers between wallets, stablecoin mints and burns, bridges, DEX swaps and large Hyperliquid positions and trades, with labels where a source names the wallet. Arguments:
types,chain,asset,min_usd,labelled,limit get_traders- Hyperliquid trader leaderboard: PnL and ROI per window, account value, observed win rate, drawdown, Sharpe and style tags. Arguments:
sort,style,limit get_smart_money- What the most profitable tracked wallets do: convergence events (several top wallets opening the same side of a coin within a short window) and their current net positioning per coin. Arguments:
coin,limit get_security_incidents- Hacks, exploits, depegs and other security incidents, newest first: detector events and curated incidents with the reported loss and primary-source links. Arguments:
origin,chain,min_severity,limit get_listed_wallets- Wallets an official source lists (OFAC SDN list, FBI / IC3 announcements, official incident post-mortems), each as "Listed as <category> by <source>, <date>" with a link. Arguments:
address,category,source,network,limit get_exchange_flows- On-chain flows into and out of exchange wallets over a window: inflow, outflow and net per exchange and asset (stablecoins, BTC, ETH). Arguments:
hours,exchange,asset get_my_limits- The plan behind this server's key (or keyless public access): requests per minute and per day and how many are left, the history window, heatmap intervals and whether commercial use is allowed.
get_api_status- Whether the Blockmetric API and its data feeds are healthy right now: overall status, API version, feeds that are delayed or down, and open incidents.
* required. Wrong arguments come back as a tool error the model can correct.
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.