{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "Blockmetric API", "version": "1.24.0", "summary": "Real-time crypto market data: Hyperliquid on-chain positions + exchange data where licensed.", "description": "Real-time crypto market data: Hyperliquid on-chain positions (liquidation map and heatmap from real positions, whales) plus centralized exchanges where their terms allow it (funding, open interest, liquidations), and a risk radar of events. Read-only JSON over HTTPS.\n\n**Sources and attribution**: every response lists the data sources it is built from in `meta.sources` (ids as on https://blockmetric.io/methodology#sources). Sources can be switched off by the operator; their data then disappears from every response, aggregates included. Name the sources next to the data when you show it.\n\n**Authentication**: `Authorization: Bearer bm_live_…` (or `x-api-key`), over HTTPS only. Keys in the URL (`?api_key=`) are refused with 400. Create keys on https://blockmetric.io/account/api, optionally with a name, an expiry date and an IP allowlist (CIDR); the full key is shown once. Keys end in a checksum (`bm_live_` + 44 random + 6 checksum characters, base58), so typos fail fast and leaked keys are recognisable by secret scanners. Keep keys on your server: a request with a key from a browser (an Origin header) answers 403 `origin_not_allowed` unless the key lists that origin; keyless public access (`X-Blockmetric-Access: public`) works from any page. GET /me shows the key, plan, limits and today's usage without counting.\n\n**Licence**: what you may do with the data depends on the plan and is stated in every response (`meta.license`) and in `info.x-license`: Free / Pro / Desk keys personal use only; API Dev internal use within one organisation (no display to third parties); API Pro display in your own product to your end users with the visible, linked attribution \"Data by Blockmetric\" up to 50,000 monthly active users (no raw redistribution or resale); redistribution, white-label and dataset licences only with an Enterprise contract (https://blockmetric.io/enterprise). Terms: https://blockmetric.io/terms#api-license.\n\n**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.\n\n**Envelope**: success: `{ \"data\": …, \"meta\": { updatedAt, source, sources, plan, delayMinutes, commercial, license, attribution, access, nextCursor? + nextUrl?, nextAfter?, warnings?, restricted? } }`; error: `{ \"error\": { code, message, doc_url, request_id, retryable, param? } }` (snake_case on purpose; the rest is camelCase). Unknown fields may be added at any time; ignore them.\n\n**Parameters**: unknown query parameters answer 400 `invalid_param` with the closest known name; values outside their range are clamped and named in `meta.warnings` (never silently); `meta.access` says from when your plan reads history. Time windows: `from` / `to` (ISO 8601) where a feed has them; `sinceMinutes`, `since` and `hours` stay.\n\n**Units**: times ISO 8601 UTC (the event envelope also carries `created` in unix seconds); money USD in cents; rates, distances and shares are fractions (0.0001 = 0.01 %); fields named …Pct hold fractions too and have unit-true aliases (`deprecated: true` marks the old name); ratios long/short. Every response field is described in the schemas below.\n\n**Pagination**: `/liquidations`, `/positions/top`, `/whales/feed`, `/radar/events`, `/tape`, `/movements`, `/traders`, `/security/incidents`, `/security/wallets`: `limit` + `cursor`; the next cursor is `meta.nextCursor` and the next page `meta.nextUrl` (null on the last page). `/liquidations` and `/tape` also poll forward with `after` (`meta.nextAfter`).\n\n**Smaller responses**: responses are compressed when the client sends Accept-Encoding (gzip, br or zstd; most HTTP clients do it by default), often 5 to 8 times smaller. The row lists (`/markets`, `/funding`, `/liquidations`, `/positions/top`, `/whales/feed`, `/radar/events`, `/coins`, `/candles/{coin}`, `/long-short`, `/whales`, `/traders`, `/tape`, `/screener`, `/funding/predicted`, `/funding/spreads`, `/security/incidents`, `/security/wallets`, `/movements`) also take `fields` (only the named fields of every row) and `format=csv` or `format=ndjson` (only the rows; the meta block as `X-Blockmetric-*` and `Link` headers).\n\n**Caching**: every 200 carries an `ETag`; send `If-None-Match` to get `304 Not Modified` (still counts against the limit, but no body).\n\n**Rate limits**: per account (all keys share them): Free 10/min, 1,000/day · Pro 20/min, 5,000/day · Desk 30/min, 10,000/day · API Dev 60/min, 50,000/day · API Pro 300/min, 500,000/day. Every response to a request with a valid key or with keyless public access carries the minute (`X-RateLimit-Limit`, `-Remaining`, `-Reset`) and the UTC day (`X-RateLimit-Limit-Day`, `-Remaining-Day`, `-Reset-Day`), and both in the IETF draft format (`RateLimit-Policy`, `RateLimit`); 429 adds `Retry-After`. A 401 (missing or invalid key) belongs to no account and carries no rate-limit headers. Requests answered 429 are not counted; every other answer is (also 4xx). Calls billed as overage carry `X-Blockmetric-Overage: billed`.\n\n**Versioning**: the major version is in the path (/api/v1); within v1 only additive changes. Breaking changes ship as /api/v2 with at least 6 months overlap; deprecated endpoints send `Deprecation` / `Sunset` headers. Changelog: https://blockmetric.io/developers/changelog.\n\n**Errors**: `invalid_param` (400), `unauthorized` (401), `plan_required` (403), `scope_required` (403), `ip_not_allowed` (403), `origin_not_allowed` (403), `source_restricted` (403), `https_required` (403), `not_found` (404), `method_not_allowed` (405), `rate_limited` (429), `daily_limit_exceeded` (429), `stream_limit` (429), `internal_error` (500). Catalogue: https://blockmetric.io/developers/errors.\n\nData from public sources, without guarantee. Not investment advice.", "termsOfService": "https://blockmetric.io/terms", "contact": { "name": "Blockmetric developer support", "url": "https://blockmetric.io/help?topic=api#contact" }, "license": { "name": "Blockmetric API licence (see x-license)", "url": "https://blockmetric.io/terms#api-license" }, "x-license": { "terms": "https://blockmetric.io/terms#api-license", "attribution": "Data by Blockmetric", "displayMauCap": 50000, "tiers": [ { "id": "public", "plans": [], "summary": "Keyless public access: personal and non-commercial use; when you show the data, show the linked credit \"Data by Blockmetric\".", "display": true, "attributionRequired": true, "redistribution": false, "mauCap": null }, { "id": "personal", "plans": [ "free", "pro", "desk" ], "summary": "Your own personal use only. No display to anybody else, no sharing of keys or data.", "display": false, "attributionRequired": false, "redistribution": false, "mauCap": null }, { "id": "internal", "plans": [ "api_dev" ], "summary": "Internal use within one organisation (research, dashboards, bots for your own team). No display to third parties.", "display": false, "attributionRequired": false, "redistribution": false, "mauCap": null }, { "id": "display", "plans": [ "api_pro" ], "summary": "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.", "display": true, "attributionRequired": true, "redistribution": false, "mauCap": 50000 }, { "id": "enterprise", "plans": [], "summary": "Redistribution, white-label, data feeds and dataset licences, SLA and invoicing: individual yearly contract from $12,000.", "display": true, "attributionRequired": false, "redistribution": true, "mauCap": null, "contact": "https://blockmetric.io/enterprise", "fromMonthlyUsd": 1000, "fromYearlyUsd": 12000 } ] } }, "externalDocs": { "description": "Developer hub", "url": "https://blockmetric.io/developers" }, "servers": [ { "url": "https://api.blockmetric.io/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Markets", "description": "Prices, funding, open interest and positioning across Hyperliquid and the enabled exchanges (see meta.sources)." }, { "name": "Liquidations", "description": "Liquidations that happened (feed, totals) and where they would happen (liquidation map and heatmap from real positions)." }, { "name": "Whales", "description": "Tracked Hyperliquid wallets: largest positions, leaderboard, position changes, wallet detail." }, { "name": "Radar", "description": "Risk radar events: whale moves, big liquidations, cascades, funding extremes, exploits, depegs." }, { "name": "Order flow", "description": "Order book liquidity and walls, taker flow (CVD, by print size, whales), volume profile and the large-trade tape from Hyperliquid and the enabled exchanges." }, { "name": "Realtime", "description": "API Pro: Server-Sent Events stream and signed webhooks." }, { "name": "Meta", "description": "Coverage, freshness and status." } ], "x-rate-limits": [ { "plan": "free", "label": "Free", "perMinute": 10, "perDay": 1000, "historyDays": 30, "delayMinutes": 0, "commercial": false, "stream": false, "webhooks": false }, { "plan": "pro", "label": "Pro", "perMinute": 20, "perDay": 5000, "historyDays": 365, "delayMinutes": 0, "commercial": false, "stream": false, "webhooks": false }, { "plan": "desk", "label": "Desk", "perMinute": 30, "perDay": 10000, "historyDays": 1095, "delayMinutes": 0, "commercial": false, "stream": false, "webhooks": false }, { "plan": "api_dev", "label": "API Dev", "perMinute": 60, "perDay": 50000, "historyDays": 365, "delayMinutes": 0, "commercial": false, "stream": false, "webhooks": true }, { "plan": "api_pro", "label": "API Pro", "perMinute": 300, "perDay": 500000, "historyDays": 1095, "delayMinutes": 0, "commercial": true, "stream": true, "webhooks": true } ], "x-exposed-headers": [ "X-Request-Id", "X-Client-Request-Id", "X-Blockmetric-Api-Version", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "X-RateLimit-Limit-Day", "X-RateLimit-Remaining-Day", "X-RateLimit-Reset-Day", "RateLimit-Policy", "RateLimit", "X-Blockmetric-Overage", "X-Blockmetric-Key-Expires", "Retry-After", "ETag", "Deprecation", "Sunset", "Link", "X-Blockmetric-Next-Cursor", "X-Blockmetric-Next-After", "X-Blockmetric-Updated-At", "X-Blockmetric-Warnings", "X-Blockmetric-Restricted", "X-Blockmetric-License", "Content-Disposition" ], "paths": { "/markets": { "get": { "operationId": "getMarkets", "summary": "Market state of a venue", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/premium-basis" }, "x-plan": "any", "x-sdk-method": { "typescript": "markets", "python": "markets" }, "parameters": [ { "name": "venue", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "hyperliquid", "lighter", "binance", "bybit", "okx" ] } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketsResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: venue, coin, mark, oracle, fundingHourly, fundingApr, openInterestUsd, volume24hUsd, premium, maxLeverage, updatedAt (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/funding": { "get": { "operationId": "getFunding", "summary": "Cross-venue funding board", "description": "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).\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/funding-rate" }, "x-plan": "any", "x-sdk-method": { "typescript": "funding", "python": "funding" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 500, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, hlOpenInterestUsd, byVenue, aprSpread, maxAbsApr (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/coins": { "get": { "operationId": "listCoins", "summary": "Hyperliquid coins", "description": "Hyperliquid coins with market data, largest open interest first, with the number of tracked positions and whether a liquidation map exists.\n\nAvailable 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.", "tags": [ "Markets" ], "x-plan": "any", "x-sdk-method": { "typescript": "coins", "python": "coins" }, "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoinsResponse" }, "example": { "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" } } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, mark, openInterestUsd, volume24hUsd, fundingApr, maxLeverage, trackedPositions, hasLiqMap (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/long-short": { "get": { "operationId": "getLongShort", "summary": "Long/short positioning", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/long-short-ratio" }, "x-plan": "any", "x-sdk-method": { "typescript": "longShort", "python": "long_short" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LongShortResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, hl, updatedAt, binance, bybit, okx (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/liquidations": { "get": { "operationId": "listLiquidations", "summary": "Liquidations feed", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.\n\nForward polling: pass the newest id you have as `after` (then `meta.nextAfter`) to get only new rows, oldest first.\n\nLicence 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidations" }, "x-plan": "any", "x-sdk-method": { "typescript": "liquidations", "python": "liquidations" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "venue", "in": "query", "required": false, "description": "hyperliquid | lighter | binance | bybit (okx only while enabled, see /methodology#sources) (optional).", "schema": { "type": "string", "enum": [ "hyperliquid", "lighter", "binance", "bybit", "okx" ] } }, { "name": "side", "in": "query", "required": false, "description": "long | short = side of the liquidated position (optional).", "schema": { "type": "string", "enum": [ "long", "short" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum notional in USD, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "sinceMinutes", "in": "query", "required": false, "description": "Look-back window in minutes, default 60, clamped to the plan history (API Dev 365 days, API Pro 1095 days).", "schema": { "type": "integer", "minimum": 1, "default": 60 } }, { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601, inclusive); replaces sinceMinutes. Clamped to the plan history (meta.warnings says so).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Window end (ISO 8601, exclusive; default now): liquidations before it.", "schema": { "type": "string", "format": "date-time" } }, { "name": "after", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 100, clamped to 1–1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiquidationsResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, ts, venue, coin, side, price, qty, usd (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/liquidations/summary": { "get": { "operationId": "getLiquidationSummary", "summary": "Liquidation totals", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidations" }, "x-plan": "any", "x-sdk-method": { "typescript": "liquidationSummary", "python": "liquidation_summary" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "hours", "in": "query", "required": false, "description": "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).", "schema": { "type": "integer", "minimum": 1, "maximum": 26280, "default": 24 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiquidationSummaryResponse" }, "example": { "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", "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" ] } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/liqmap/{coin}": { "get": { "operationId": "getLiqMap", "summary": "Liquidation map (current)", "description": "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).\n\nAvailable 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidation-clusters" }, "x-plan": "any", "x-sdk-method": { "typescript": "liqmap", "python": "liqmap" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiqMapResponse" }, "example": { "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 }, { "px": 41000, "longUsd": 4285714, "shortUsd": 0, "positions": 9 } ], "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/candles/{coin}": { "get": { "operationId": "getCandles", "summary": "Price candles (OHLC)", "description": "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).\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "x-plan": "any", "x-sdk-method": { "typescript": "candles", "python": "candles" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC or xyz:TSLA (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "tf", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "5m", "15m", "1h", "4h", "1d" ], "default": "1h" } }, { "name": "from", "in": "query", "required": false, "description": "Start (ISO 8601, optional; default: `limit` candles before `to`).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "End, exclusive (ISO 8601, optional; default now).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 500, clamped to 1–5000.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 500 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: t, open, high, low, close, volumeUsd, volumeBase, volumeVenue, price, complete (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/heatmap/{coin}": { "get": { "operationId": "getHeatmap", "summary": "Liquidation heatmap over time", "description": "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.\n\nAvailable 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidation-heatmap" }, "x-plan": "any", "x-sdk-method": { "typescript": "heatmap", "python": "heatmap" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "tf", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "12h", "1d" ] } }, { "name": "hours", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 1, "maximum": 26280 } }, { "name": "end", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "format": "date-time" } }, { "name": "columns", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "all", "live" ], "default": "all" } }, { "name": "clusters", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "name": "venue", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "hyperliquid", "lighter", "lighter_rh", "dydx", "gmx", "all" ], "default": "hyperliquid" } }, { "name": "stepMinutes", "in": "query", "required": false, "description": "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.", "deprecated": true, "schema": { "type": "integer", "minimum": 5, "maximum": 1440 } }, { "name": "layer", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "real" ], "default": "real", "description": "est / both were removed in 1.9.0 (estimated layer; real data only) and answer 400." } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/heatmap/{coin}/open-interest": { "get": { "operationId": "getHeatmapOpenInterest", "summary": "Open interest added per price band", "description": "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).\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/open-interest" }, "x-plan": "any", "x-sdk-method": { "typescript": "heatmapOpenInterest", "python": "heatmap_open_interest" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name as on Hyperliquid, e.g. BTC (case-insensitive). Exchange listings are matched to it (kPEPE = 1000PEPE).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "hours", "in": "query", "required": false, "description": "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).", "schema": { "type": "integer", "minimum": 1, "maximum": 840, "default": 24 } }, { "name": "end", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "venue", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "enum": [ "all", "binance", "bybit", "okx" ], "default": "all" } }, { "name": "bandPct", "in": "query", "required": false, "description": "Band width in percent of the price, default 0.5 (a round step near it, like the heatmap rows), 0.1 to 5.", "schema": { "type": "number", "minimum": 0.1, "maximum": 5, "default": 0.5 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapOpenInterestResponse" }, "example": { "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" ] } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/heatmap/{coin}/wallets": { "get": { "operationId": "getHeatmapWallets", "summary": "Wallets with their liquidation price in a band", "description": "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}.\n\nAvailable 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.", "tags": [ "Liquidations" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidation-clusters" }, "x-plan": "any", "x-sdk-method": { "typescript": "heatmapWallets", "python": "heatmap_wallets" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "lo", "in": "query", "required": false, "description": "Lower edge of the band (USD, inclusive). Needs hi; the band is at most 20 % of the price wide.", "schema": { "type": "number", "minimum": 0 } }, { "name": "hi", "in": "query", "required": false, "description": "Upper edge of the band (USD, exclusive). Needs lo.", "schema": { "type": "number", "minimum": 0 } }, { "name": "price", "in": "query", "required": false, "description": "Instead of lo / hi: the heatmap row (0.5 % bucket of the liquidation map) holding this price.", "schema": { "type": "number", "minimum": 0 } }, { "name": "clusters", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } }, { "name": "side", "in": "query", "required": false, "description": "long | short (optional).", "schema": { "type": "string", "enum": [ "long", "short" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum position notional in USD, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 20, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapWalletsResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/scoreboard": { "get": { "operationId": "getScoreboard", "summary": "Cluster hit rates (scoreboard)", "description": "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.\n\nAvailable 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.", "tags": [ "Liquidations" ], "x-plan": "any", "x-sdk-method": { "typescript": "scoreboard", "python": "scoreboard" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Optional: one coin, with the hit rates of its current clusters.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreboardResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/positions/top": { "get": { "operationId": "listTopPositions", "summary": "Largest positions", "description": "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).\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.", "tags": [ "Whales" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/liquidation-distance" }, "x-plan": "any", "x-sdk-method": { "typescript": "topPositions", "python": "top_positions" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "side", "in": "query", "required": false, "description": "long | short (optional).", "schema": { "type": "string", "enum": [ "long", "short" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum position notional in USD, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "venue", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "hyperliquid", "lighter" ], "default": "hyperliquid" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopPositionsResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/positions/top?cursor=" } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: address, label, accountValue, coin, side, size, entryPx, positionUsd, leverage, leverageType, liqPx, liqDistance, mark, marginUsed, unrealizedPnl, updatedAt, venue (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/whales": { "get": { "operationId": "listWhales", "summary": "Whale leaderboard", "description": "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).\n\nAvailable 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.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "whales", "python": "whales" }, "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "size (open notional, default) | pnl (all-time PnL) | near_liq (closest liquidation of a position ≥ $100k) | liquidated (most fill-confirmed liquidations).", "schema": { "type": "string", "enum": [ "size", "pnl", "near_liq", "liquidated" ], "default": "size" } }, { "name": "coin", "in": "query", "required": false, "description": "Only wallets with a position in this coin (sort=liquidated: liquidations in this coin).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "labelled", "in": "query", "required": false, "description": "true = only wallets with a public label from a cited source; default false.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "venue", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "hyperliquid", "lighter" ], "default": "hyperliquid" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhalesResponse" }, "example": { "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" } } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: address, label, labelSource, accountValue, pnlMonth, pnlAllTime, positionsUsd, positionCount, top, liquidations, updatedAt, venue, l1Address (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/whales/feed": { "get": { "operationId": "listWhaleEvents", "summary": "Whale position changes", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "whaleFeed", "python": "whale_feed" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum absolute USD change, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "since", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhaleFeedResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/whales/feed?cursor=" } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, ts, address, label, coin, kind, side, sizeDelta, usdDelta, price, data (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/wallets/{address}": { "get": { "operationId": "getWallet", "summary": "Wallet detail", "description": "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.\n\nAvailable 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.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "wallet", "python": "wallet" }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "0x address (40 hex characters, any case).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of position events, default 50, clamped to 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/whales/stops": { "get": { "operationId": "getWhaleStops", "summary": "Whale stop / TP map", "description": "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.\n\nAvailable 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.", "tags": [ "Whales" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/whale-stops" }, "x-plan": "any", "x-sdk-method": { "typescript": "whaleStops", "python": "whale_stops" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin for the bucket map and the overlay (optional; without it: per-coin table).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhaleStopsResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/traders": { "get": { "operationId": "listTraders", "summary": "Trader leaderboard", "description": "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).\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "traders", "python": "traders" }, "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "pnl_day | pnl_week | pnl_month (default) | pnl_all | roi_week | roi_month | roi_all | account_value | vlm_month | sharpe | drawdown (smallest first).", "schema": { "type": "string", "enum": [ "pnl_day", "pnl_week", "pnl_month", "pnl_all", "roi_week", "roi_month", "roi_all", "account_value", "vlm_month", "sharpe", "drawdown" ], "default": "pnl_month" } }, { "name": "search", "in": "query", "required": false, "description": "Address prefix (0x…) or part of a displayed name (paid plans).", "schema": { "type": "string", "pattern": "^.{1,40}$" } }, { "name": "style", "in": "query", "required": false, "description": "scalper | swing | position | high_turnover | high_leverage | mostly_long | mostly_short (paid plans).", "schema": { "type": "string", "enum": [ "scalper", "swing", "position", "high_turnover", "high_leverage", "mostly_long", "mostly_short" ] } }, { "name": "minAccountValue", "in": "query", "required": false, "description": "Minimum account value in USD (paid plans).", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradersResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/traders?cursor=" } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: rank, address, label, labelSource, accountValue, pnl, roi, vlm, observed, risk, book, styles, sizeCohort, pnlCohort, updatedAt (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/cohorts": { "get": { "operationId": "getCohorts", "summary": "Cohort positioning", "description": "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).\n\nAvailable 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.", "tags": [ "Whales" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/cohorts" }, "x-plan": "any", "x-sdk-method": { "typescript": "cohorts", "python": "cohorts" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Coin, or ALL (default) for every position.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "dim", "in": "query", "required": false, "description": "size | pnl. With `cohort`: only changes of that cohort.", "schema": { "type": "string", "enum": [ "size", "pnl" ] } }, { "name": "cohort", "in": "query", "required": false, "description": "shrimp | fish | dolphin | shark | whale | top | profitable | flat | losing | rekt (needs dim).", "schema": { "type": "string", "enum": [ "shrimp", "fish", "dolphin", "shark", "whale", "top", "profitable", "flat", "losing", "rekt" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 30, clamped to 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohortsResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/smart-money": { "get": { "operationId": "getSmartMoney", "summary": "Smart-money convergence", "description": "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).\n\nAvailable 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.", "tags": [ "Whales" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/learn/smart-money" }, "x-plan": "any", "x-sdk-method": { "typescript": "smartMoney", "python": "smart_money" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 30, clamped to 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartMoneyResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/orderbook/{coin}": { "get": { "operationId": "getOrderbook", "summary": "Order book liquidity and walls", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Order flow" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/order-book-walls" }, "x-plan": "any", "x-sdk-method": { "typescript": "orderbook", "python": "orderbook" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "venue", "in": "query", "required": false, "description": "hyperliquid | binance | bybit (optional; default every covered venue the API serves).", "schema": { "type": "string", "enum": [ "hyperliquid", "binance", "bybit" ] } }, { "name": "hours", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 0, "maximum": 720, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderbookResponse" }, "example": { "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" ] } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/flow/{coin}": { "get": { "operationId": "getFlow", "summary": "Taker flow (CVD) and volume profile", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Order flow" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/cvd" }, "x-plan": "any", "x-sdk-method": { "typescript": "flow", "python": "flow" }, "parameters": [ { "name": "coin", "in": "path", "required": true, "description": "Coin name, e.g. BTC (case-insensitive).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "venue", "in": "query", "required": false, "description": "hyperliquid | binance | bybit (optional).", "schema": { "type": "string", "enum": [ "hyperliquid", "binance", "bybit" ] } }, { "name": "hours", "in": "query", "required": false, "description": "Window in hours, default 24 (free key 1), clamped to the plan history (Pro / API Dev 168, Desk / API Pro 9600).", "schema": { "type": "integer", "minimum": 1, "maximum": 9600, "default": 24 } }, { "name": "stepMinutes", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "enum": [ 1, 5, 15, 60, 240, 1440 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" }, "example": { "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", "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" ] } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/tape": { "get": { "operationId": "listTape", "summary": "Large-trade tape", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.\n\nForward polling: pass the newest id you have as `after` (then `meta.nextAfter`) to get only new rows, oldest first.\n\nLicence 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.", "tags": [ "Order flow" ], "x-plan": "any", "x-sdk-method": { "typescript": "tape", "python": "tape" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional; free keys: BTC, ETH or HYPE, default all three).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "venue", "in": "query", "required": false, "description": "hyperliquid | binance | bybit (optional).", "schema": { "type": "string", "enum": [ "hyperliquid", "binance", "bybit" ] } }, { "name": "side", "in": "query", "required": false, "description": "buy | sell = side of the taker (optional).", "schema": { "type": "string", "enum": [ "buy", "sell" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum print size in USD on top of the tape threshold, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "sinceMinutes", "in": "query", "required": false, "description": "Look-back window in minutes, default 60, clamped to the plan history (free key 60).", "schema": { "type": "integer", "minimum": 1, "default": 60 } }, { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601, inclusive); replaces sinceMinutes. Clamped to the plan history (meta.warnings says so).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Window end (ISO 8601, exclusive; default now): prints before it.", "schema": { "type": "string", "format": "date-time" } }, { "name": "after", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 100, clamped to 1–1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TapeResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/tape?cursor=", "restricted": [ "binance", "bybit" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, ts, coin, venue, market, side, px, usd, fills, taker, whale (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/screener": { "get": { "operationId": "getScreener", "summary": "Screener (every coin)", "description": "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).\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/open-interest" }, "x-plan": "any", "x-sdk-method": { "typescript": "screener", "python": "screener" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "sort", "in": "query", "required": false, "description": "oi (default) | change1h | change24h | oiChange1h | oiChange24h | funding | fundingPred | ls | liq24h | cluster | rsi1h | rsi4h | vol | coin; missing values sort last.", "schema": { "type": "string", "enum": [ "oi", "change1h", "change24h", "oiChange1h", "oiChange24h", "funding", "fundingPred", "ls", "liq24h", "cluster", "rsi1h", "rsi4h", "vol", "coin" ], "default": "oi" } }, { "name": "dir", "in": "query", "required": false, "description": "desc (default) | asc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "minOiUsd", "in": "query", "required": false, "description": "Minimum open interest in USD, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 100, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenerResponse" }, "example": { "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", "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, mark, change1h, change24h, oiUsd, oiChange1h, oiChange24h, volume24hUsd, fundingApr, fundingPredApr, lsHl, lsBinanceTop, liq24hUsd, liq24hLongUsd, liq24hShortUsd, clusterDistance, clusterUsd, clusterSide, rsi1h, rsi4h, vol24h, maxLeverage (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/funding/predicted": { "get": { "operationId": "getPredictedFunding", "summary": "Predicted next funding", "description": "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.\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/predicted-funding" }, "x-plan": "any", "x-sdk-method": { "typescript": "predictedFunding", "python": "predicted_funding" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 300, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 300 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictedFundingResponse" }, "example": { "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, byVenue, updatedAt (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/funding/spreads": { "get": { "operationId": "getFundingSpreads", "summary": "Cross-venue funding spreads", "description": "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).\n\nAvailable 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.\n\nLicence 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.", "tags": [ "Markets" ], "externalDocs": { "description": "Methodology", "url": "https://blockmetric.io/metrics/funding-spread" }, "x-plan": "any", "x-sdk-method": { "typescript": "fundingSpreads", "python": "funding_spreads" }, "parameters": [ { "name": "coin", "in": "query", "required": false, "description": "Only this coin (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "basis", "in": "query", "required": false, "description": "current (default) | predicted.", "schema": { "type": "string", "enum": [ "current", "predicted" ], "default": "current" } }, { "name": "minOiUsd", "in": "query", "required": false, "description": "Minimum open interest of the thinner leg in USD, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 100, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingSpreadsResponse" }, "example": { "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", "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" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: coin, basis, high, low, spreadApr, spreadDaily, minOpenInterestUsd, venues, updatedAt (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/sentiment": { "get": { "operationId": "getSentiment", "summary": "Blockmetric Sentiment index", "description": "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.\n\nAvailable 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.", "tags": [ "Markets" ], "x-plan": "any", "x-sdk-method": { "typescript": "sentiment", "python": "sentiment" }, "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Days of daily history, default 90, clamped to 1–1095 and to the plan history (free key 30 days, keyless 24 h).", "schema": { "type": "integer", "minimum": 1, "maximum": 1095, "default": 90 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentimentResponse" }, "example": { "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", "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-28T00:24:00.000Z" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/radar/events": { "get": { "operationId": "listRadarEvents", "summary": "Risk radar events", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.\n\nLicence 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.", "tags": [ "Radar" ], "x-plan": "any", "x-sdk-method": { "typescript": "radarEvents", "python": "radar_events" }, "parameters": [ { "name": "kinds", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "pattern": "^(?:whale_open|whale_close|whale_liquidated|big_liquidation|liq_cascade|funding_extreme|funding_flip|oi_spike|hack|depeg|tvl_drop|cex_outflow|whale_near_liq|record|smart_money|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)(?:,(?:whale_open|whale_close|whale_liquidated|big_liquidation|liq_cascade|funding_extreme|funding_flip|oi_spike|hack|depeg|tvl_drop|cex_outflow|whale_near_liq|record|smart_money|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))*$", "description": "Comma-separated radar event kinds." } }, { "name": "minSeverity", "in": "query", "required": false, "description": "1 info, 2 notable, 3 major, 4 critical; default 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } }, { "name": "coin", "in": "query", "required": false, "description": "Coin name as on Hyperliquid (BTC, ETH, kPEPE, HIP-3 names like xyz:TSLA); case-insensitive.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}$", "examples": [ "BTC" ] } }, { "name": "since", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarEventsResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/radar/events?cursor=", "restricted": [ "binance", "bybit" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, ts, kind, severity, coin, title, body, data, source (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/security/incidents": { "get": { "operationId": "listSecurityIncidents", "summary": "Security incidents", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.\n\nLicence 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.", "tags": [ "Radar" ], "x-plan": "any", "x-sdk-method": { "typescript": "securityIncidents", "python": "security_incidents" }, "parameters": [ { "name": "origin", "in": "query", "required": false, "description": "all (default) | detector | curated.", "schema": { "type": "string", "enum": [ "all", "detector", "curated" ], "default": "all" } }, { "name": "type", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "enum": [ "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" ], "description": "Incident type (curated) or detector type." } }, { "name": "chain", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "enum": [ "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" ] } }, { "name": "minSeverity", "in": "query", "required": false, "description": "1 info, 2 notable, 3 major, 4 critical; default 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityIncidentsResponse" }, "example": { "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", "bybit", "publicnode", "chainlink_onchain", "protocol_registry" ], "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": "", "nextUrl": "https://api.blockmetric.io/v1/security/incidents?cursor=", "restricted": [ "binance", "bybit" ] } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, origin, ts, date, kind, type, severity, title, summary, chains, coin, amountUsd, status, url, links, data (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/security/wallets": { "get": { "operationId": "listSecurityWallets", "summary": "Listed wallets (OFAC, FBI, post-mortems)", "description": "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 by , \"; 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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.", "tags": [ "Radar" ], "x-plan": "any", "x-sdk-method": { "typescript": "securityWallets", "python": "security_wallets" }, "parameters": [ { "name": "category", "in": "query", "required": false, "description": "sanctioned | stolen_funds | exploit | drainer | phishing | other (optional).", "schema": { "type": "string", "enum": [ "sanctioned", "stolen_funds", "exploit", "drainer", "phishing", "other" ] } }, { "name": "network", "in": "query", "required": false, "description": "Address family: evm, bitcoin, tron, litecoin, monero … (optional).", "schema": { "type": "string", "enum": [ "evm", "bitcoin", "tron", "litecoin", "monero", "bitcoin_cash", "dash", "zcash", "solana", "ripple", "dogecoin", "bitcoin_gold", "bitcoin_sv", "verge", "ethereum_classic", "bnb_beacon", "other" ] } }, { "name": "source", "in": "query", "required": false, "description": "ofac_sdn | fbi_ic3 | incident (optional).", "schema": { "type": "string", "enum": [ "ofac_sdn", "fbi_ic3", "incident" ] } }, { "name": "q", "in": "query", "required": false, "description": "Address or part of one (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9:]{1,90}$", "description": "Address or part of one." } }, { "name": "movedDays", "in": "query", "required": false, "description": "Only addresses with a tracked movement in the last N days (1–400, optional).", "schema": { "type": "integer", "minimum": 1, "maximum": 400 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 100, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityWalletsResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/security/wallets?cursor=" } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: address, network, tracked, category, source, sourceLabel, sourceUrl, sourceDate, listing, detail, assets, incidentId, firstSeen, lastMoveTs, movements, balanceUsd, balanceAt (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/security/wallets/{address}": { "get": { "operationId": "getSecurityWallet", "summary": "Listed wallet detail", "description": "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.\n\nAvailable 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.", "tags": [ "Radar" ], "x-plan": "any", "x-sdk-method": { "typescript": "securityWallet", "python": "security_wallet" }, "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The address as the source lists it (EVM 0x + 40 hex in any case, Bitcoin, Tron …).", "schema": { "type": "string", "pattern": "^(0x[0-9a-fA-F]{40}|[A-Za-z0-9:]{20,120})$", "description": "The address as the source lists it." } }, { "name": "limit", "in": "query", "required": false, "description": "Number of movements, default 25, clamped to 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityWalletResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/movements": { "get": { "operationId": "listMovements", "summary": "Whale movements (on-chain + Hyperliquid)", "description": "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.\n\nAvailable 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.\n\nPaginated: pass `meta.nextCursor` as `cursor` (or follow `meta.nextUrl`) to get the next page; cursors are bound to this endpoint and its filters.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "movements", "python": "movements" }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Comma list of transfer | exchange_in | exchange_out | exchange_exchange | mint | burn | bridge | dex_buy | dex_sell | perp_position | big_trade (optional, default all).", "schema": { "type": "string", "pattern": "^(?:transfer|exchange_in|exchange_out|exchange_exchange|mint|burn|bridge|dex_buy|dex_sell|perp_position|big_trade)(?:,(?:transfer|exchange_in|exchange_out|exchange_exchange|mint|burn|bridge|dex_buy|dex_sell|perp_position|big_trade))*$", "description": "Comma-separated movement types." } }, { "name": "chain", "in": "query", "required": false, "description": "ethereum | arbitrum | base | bitcoin | hyperliquid (optional).", "schema": { "type": "string", "enum": [ "ethereum", "arbitrum", "base", "bitcoin", "hyperliquid" ] } }, { "name": "asset", "in": "query", "required": false, "description": "Asset symbol, e.g. BTC, ETH, USDT, USDC (ETH also finds WETH, BTC finds WBTC, USDT finds USDT0) (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{1,12}$", "examples": [ "USDT" ] } }, { "name": "minUsd", "in": "query", "required": false, "description": "Minimum value in USD on top of the feed thresholds, default 0.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "labelled", "in": "query", "required": false, "description": "true = only items with a labelled sender or receiver.", "schema": { "type": "boolean", "default": false } }, { "name": "address", "in": "query", "required": false, "description": "Only movements of this EVM or Bitcoin address (includes smaller transfers of addresses watched by alert rules).", "schema": { "type": "string", "pattern": "^(0x[0-9a-fA-F]{40}|bc1[02-9ac-hj-np-z]{11,71}|[13][1-9A-HJ-NP-Za-km-z]{25,34})$", "description": "EVM or Bitcoin address." } }, { "name": "since", "in": "query", "required": false, "description": "ISO time; clamped to the plan history.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of items, default 50, clamped to 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,400}$" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,40}(,[A-Za-z0-9_]{1,40}){0,63}$", "examples": [ "coin,mark" ] } }, { "name": "format", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "enum": [ "json", "csv", "ndjson" ], "default": "json" } } ], "responses": { "200": { "description": "OK. With format=csv or format=ndjson the body is only the rows (text/csv, application/x-ndjson) and the meta block comes as X-Blockmetric-* and Link headers.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Blockmetric-Next-Cursor": { "$ref": "#/components/headers/X-Blockmetric-Next-Cursor" }, "X-Blockmetric-Next-After": { "$ref": "#/components/headers/X-Blockmetric-Next-After" }, "X-Blockmetric-Updated-At": { "$ref": "#/components/headers/X-Blockmetric-Updated-At" }, "X-Blockmetric-Warnings": { "$ref": "#/components/headers/X-Blockmetric-Warnings" }, "X-Blockmetric-Restricted": { "$ref": "#/components/headers/X-Blockmetric-Restricted" }, "X-Blockmetric-License": { "$ref": "#/components/headers/X-Blockmetric-License" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovementsResponse" }, "example": { "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": "", "nextUrl": "https://api.blockmetric.io/v1/movements?cursor=" } } }, "text/csv": { "schema": { "type": "string", "description": "format=csv: a header line, then one line per row. Columns: id, ts, type, chain, asset, amount, usd, priceSource, title, context, from, to, txUrl, details (or the fields= list, in its order). Empty cell = null; nested values as JSON text." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "format=ndjson: one JSON object per row and line, the same objects as the JSON data list (gzip when Accept-Encoding allows it)." } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/exchange-flows": { "get": { "operationId": "getExchangeFlows", "summary": "Exchange on-chain flows", "description": "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).\n\nAvailable 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.", "tags": [ "Whales" ], "x-plan": "any", "x-sdk-method": { "typescript": "exchangeFlows", "python": "exchange_flows" }, "parameters": [ { "name": "hours", "in": "query", "required": false, "description": "Window in hours, default 24, clamped to 1–2160 and to the plan history.", "schema": { "type": "integer", "minimum": 1, "maximum": 2160, "default": 24 } }, { "name": "exchange", "in": "query", "required": false, "description": "Only this exchange, e.g. Binance (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9 ._-]{2,40}$", "examples": [ "Binance" ] } }, { "name": "asset", "in": "query", "required": false, "description": "Only this asset family, e.g. BTC, ETH, USDT, USDC (optional).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{1,12}$", "examples": [ "USDT" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeFlowsResponse" }, "example": { "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", "mempool_space" ], "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stats": { "get": { "operationId": "getStats", "summary": "Coverage and freshness", "description": "Coverage and freshness: tracked wallets and positions, markets per venue, event counts, liquidation-map size and the last run of every collector job.\n\nAvailable 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.", "tags": [ "Meta" ], "x-plan": "any", "x-sdk-method": { "typescript": "stats", "python": "stats" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsResponse" }, "example": { "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", "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me": { "get": { "operationId": "getMe", "summary": "The calling key: plan, limits, usage", "description": "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.\n\nAvailable 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.\n\nNot counted against the rate limits and never answered with 429.", "tags": [ "Meta" ], "x-plan": "any", "x-sdk-method": { "typescript": "me", "python": "me" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-Blockmetric-Overage": { "$ref": "#/components/headers/X-Blockmetric-Overage" }, "X-Blockmetric-Key-Expires": { "$ref": "#/components/headers/X-Blockmetric-Key-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" }, "example": { "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" } } } } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag). No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stream": { "get": { "operationId": "streamEvents", "summary": "Live event stream (SSE)", "description": "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.\n\nRequires API Pro.\n\nSend Last-Event-ID (EventSource does this automatically on reconnect; \"evt_\" 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.\n\nAt most 2 open streams per account (429 stream_limit otherwise; a dropped connection frees its slot within 45 s).\n\nFrames:\n- **message (no event: line)** (`id: · data: `): One radar event. The SSE id is the numeric event id; the envelope id is \"evt_\" + id.\n- **ready** (`data: { plan, filter: { kinds, minSeverity, coins }, resumedFrom, backlog, heartbeatSec, maxDurationSec }`): Sent once after connecting (no id).\n- **gap** (`data: { lastEventId, message }`): Some events after Last-Event-ID were outside the resume window; backfill with GET /api/v1/radar/events.\n- **bye** (`data: { reason: \"max_duration\" | \"plan\" | \"key_revoked\" | \"error\" | \"slow_consumer\", reconnect }`): The server closes the connection. Reconnect after max_duration / error / slow_consumer (the client read too slowly, so resume with Last-Event-ID); not after plan / key_revoked (also sent when the key expired or the address left its IP allowlist).\n- **(comment)** (`: ping `): Heartbeat every 15 s (keeps proxies from closing idle connections).\n\nEvery event's `data:` line is one EventEnvelope (components/schemas/EventEnvelope) as JSON on a single line.", "tags": [ "Realtime" ], "x-plan": "api_pro", "x-sdk-method": { "typescript": "stream", "python": "stream" }, "parameters": [ { "name": "kinds", "in": "query", "required": false, "description": "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.", "schema": { "type": "string", "pattern": "^(?:whale_open|whale_close|whale_liquidated|big_liquidation|liq_cascade|funding_extreme|funding_flip|oi_spike|hack|depeg|tvl_drop|cex_outflow|whale_near_liq|record|smart_money|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)(?:,(?:whale_open|whale_close|whale_liquidated|big_liquidation|liq_cascade|funding_extreme|funding_flip|oi_spike|hack|depeg|tvl_drop|cex_outflow|whale_near_liq|record|smart_money|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))*$", "description": "Comma-separated radar event kinds." } }, { "name": "minSeverity", "in": "query", "required": false, "description": "1 info, 2 notable, 3 major, 4 critical; default 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } }, { "name": "coin", "in": "query", "required": false, "description": "One coin or up to 20 comma-separated (BTC,ETH,kPEPE); case-insensitive. Events without a coin are then not sent.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,39}(?:,[A-Za-z0-9][A-Za-z0-9:._-]{0,39}){0,19}$" } }, { "name": "lastEventId", "in": "query", "required": false, "description": "Alternative to the Last-Event-ID header (resume after this event id).", "schema": { "type": "integer", "minimum": 0 } }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume after this event id (EventSource sends it automatically on reconnect).", "schema": { "type": "string", "pattern": "^(?:evt_)?\\d{1,15}$" } } ], "responses": { "200": { "description": "An open text/event-stream. Closed by the server after max 1 h (`event: bye`); reconnect with Last-Event-ID.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE frames; see the operation description." }, "x-event-schema": { "$ref": "#/components/schemas/EventEnvelope" }, "example": "retry: 3000\n: connected\n\nevent: ready\ndata: {\"plan\":\"api_pro\",\"filter\":{\"kinds\":null,\"minSeverity\":1,\"coins\":null},\"resumedFrom\":null,\"backlog\":0,\"heartbeatSec\":15,\"maxDurationSec\":3600}\n\nid: 5468\ndata: {\"id\":\"evt_5468\",\"type\":\"funding_extreme\",\"created\":1793106660,\"createdAt\":\"2026-10-27T13:11:00.000Z\",\"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\"}}\n\n: ping " } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "API status (public)", "description": "Public, no key: API version, data freshness per source and collector job, measured uptime (24 h / 7 / 30 / 90 days, current SLA month) and incident notes. Cached for 15 s; at most 120 requests per minute per IP.", "tags": [ "Meta" ], "security": [], "x-sdk-method": { "typescript": "status", "python": "status" }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "304": { "description": "Not Modified." }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This document", "description": "Public, no key. Also available as YAML at /api/v1/openapi.yaml.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not Modified." }, "400": { "$ref": "#/components/responses/BadRequest" } } } } }, "webhooks": { "radarEvent": { "post": { "operationId": "radarEventWebhook", "summary": "Radar event (webhook delivery)", "description": "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.\n\nRequires API Dev (2 endpoints) or API Pro (10 endpoints). Create endpoints on /account/webhooks: URL, event kinds (none = all), minimum severity and an optional coin list (with a coin filter, events without a coin are not sent). The signing secret (whsec_ + 43 characters) is shown once; rotation keeps the old secret signing for 24 hours. Up to 2 endpoints per account with API Dev, 10 with API Pro. \"Send test event\" delivers a type \"test\" event immediately.\n\nSignature: `Blockmetric-Signature: t=,v1=<64 hex chars>[,v1=<64 hex chars>]`, signed payload ` + \".\" + `, HMAC-SHA256, key = the whole signing secret string (including \"whsec_\") as UTF-8 bytes, output lowercase hex. Tolerance 300 s.\n\n- Compute the HMAC over the raw body bytes as received. Do not parse and re-serialise the JSON first.\n- Accept the request when any v1 value matches (constant-time comparison); ignore unknown keys (future versions such as v2).\n- Reject timestamps more than 300 seconds away from your clock (replay protection); keep your server clock in sync (NTP).\n- Retries are signed again with a fresh t; the body is byte-identical.\n\nDelivery: 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.", "tags": [ "Realtime" ], "x-plan": "api_dev", "x-plans": [ "api_dev", "api_pro" ], "parameters": [ { "name": "Blockmetric-Signature", "in": "header", "required": true, "description": "t=,v1=; during a secret rotation a second v1 signed with the previous secret follows.", "schema": { "type": "string" } }, { "name": "Blockmetric-Event-Id", "in": "header", "required": false, "description": "Same as the body id (\"evt_\"); identical on every retry.", "schema": { "type": "string" } }, { "name": "Blockmetric-Event-Type", "in": "header", "required": false, "description": "Same as the body type.", "schema": { "type": "string" } }, { "name": "Blockmetric-Delivery-Attempt", "in": "header", "required": false, "description": "1 for the first attempt, up to 6.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": false, "description": "Blockmetric-Webhooks/1.0 (+)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" }, "example": { "id": "evt_5468", "type": "funding_extreme", "created": 1793106660, "createdAt": "2026-10-27T13:11:00.000Z", "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" } } } } }, "responses": { "410": { "description": "Gone: disables the endpoint." }, "2XX": { "description": "Delivered. Answer within 10 s; the body is ignored." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bm_live_ + 50 base58 characters (44 random + 6 checksum)", "description": "Authorization: Bearer " }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative to the Authorization header." } }, "headers": { "X-Request-Id": { "description": "Unique id of this response (also error.request_id). Quote it when contacting support.", "schema": { "type": "string" } }, "X-Client-Request-Id": { "description": "Your own request id, when you sent one as X-Client-Request-Id or X-Request-Id (printable, at most 64 characters); logged next to ours.", "schema": { "type": "string" } }, "X-Blockmetric-Api-Version": { "description": "Version of the v1 contract that served the response (OpenAPI info.version).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for the account.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the current minute window ends.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for the account.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left today (UTC); 0 with overage on means further calls are billed.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix seconds when the UTC day ends.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Both quotas in the IETF draft format (draft-ietf-httpapi-ratelimit-headers), e.g. \"minute\";q=60;w=60, \"day\";q=100000;w=86400.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining requests and seconds to the reset per window, IETF draft format, e.g. \"minute\";r=59;t=42, \"day\";r=99990;t=50000.", "schema": { "type": "string" } }, "X-Blockmetric-Overage": { "description": "\"billed\" when this request was beyond the daily limit and billed as overage (API Dev / API Pro with overage on).", "schema": { "type": "string" } }, "X-Blockmetric-Key-Expires": { "description": "Expiry of the key (ISO 8601), sent during its last 14 days. Create a new key on /account/api in time.", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds to wait before retrying (429).", "schema": { "type": "integer" } }, "ETag": { "description": "Strong validator of the body; send it as If-None-Match to get 304 Not Modified when nothing changed.", "schema": { "type": "string" } }, "Deprecation": { "description": "Only on deprecated endpoints or parameters: \"@\" (RFC 9745).", "schema": { "type": "string" } }, "Sunset": { "description": "Only on deprecated endpoints with a removal date: HTTP date (RFC 8594).", "schema": { "type": "string" } }, "Link": { "description": "Only together with Deprecation: ; rel=\"deprecation\" (RFC 9745). With format=csv / ndjson also ; rel=\"next\" and ; rel=\"license\" (RFC 8288).", "schema": { "type": "string" } }, "X-Blockmetric-Next-Cursor": { "description": "format=csv / ndjson only: meta.nextCursor (pass it as cursor); absent on the last page.", "schema": { "type": "string" } }, "X-Blockmetric-Next-After": { "description": "format=csv / ndjson only: meta.nextAfter of feeds with forward polling.", "schema": { "type": "integer" } }, "X-Blockmetric-Updated-At": { "description": "format=csv / ndjson only: meta.updatedAt, the newest data timestamp.", "schema": { "type": "string", "format": "date-time" } }, "X-Blockmetric-Warnings": { "description": "format=csv / ndjson only: meta.warnings as code:param pairs, e.g. history:from, clamped:limit (the JSON format has the messages).", "schema": { "type": "string" } }, "X-Blockmetric-Restricted": { "description": "format=csv / ndjson only: meta.restricted, the venues the licence gate withheld.", "schema": { "type": "string" } }, "X-Blockmetric-License": { "description": "format=csv / ndjson only: meta.license.id, the licence the rows are served under (attribution duties as in meta.license).", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Invalid or unknown parameter (error.param names it; also: an API key sent in the URL, since keys are only accepted in headers). Codes: `invalid_param`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "invalid_param", "message": "Unknown parameter \"limt\". Did you mean \"limit\"? Known parameters: coin, venue, side, minUsd, sinceMinutes, from, to, after, limit, cursor.", "doc_url": "https://blockmetric.io/developers/errors#invalid_param", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": false, "param": "limt" } } } } }, "Unauthorized": { "description": "Missing, malformed (checksum mismatch), unknown, revoked or expired key. Codes: `unauthorized`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or revoked API key.", "doc_url": "https://blockmetric.io/developers/errors#unauthorized", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": false } } } } }, "Forbidden": { "description": "The plan does not include this, the key's scopes do not include the data API, the request came from an address outside the key's IP allowlist or from a browser origin the key does not allow, it used plain http, or it asked for exchange data that is not redistributed during the licence review. Codes: `plan_required`, `scope_required`, `ip_not_allowed`, `origin_not_allowed`, `https_required`, `source_restricted`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "plan_required", "message": "5m heatmap columns need Pro, Desk or an API plan.", "doc_url": "https://blockmetric.io/developers/errors#plan_required", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": false, "param": "tf" } } } } }, "NotFound": { "description": "Unknown coin, a coin without a Hyperliquid market on an endpoint built from Hyperliquid data, untracked wallet or unknown endpoint. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "not_found", "message": "Unknown coin \"BTCX\". List the coins with GET /api/v1/coins.", "doc_url": "https://blockmetric.io/developers/errors#not_found", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": false, "param": "coin" } } } } }, "TooManyRequests": { "description": "Per-minute or daily limit reached (or, for /stream, too many open streams). Wait Retry-After seconds. Codes: `rate_limited`, `daily_limit_exceeded`, `stream_limit`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit of 60 requests per minute exceeded.", "doc_url": "https://blockmetric.io/developers/errors#rate_limited", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": true } } } } }, "InternalError": { "description": "Unexpected server error; retry with backoff. Codes: `internal_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Blockmetric-Api-Version": { "$ref": "#/components/headers/X-Blockmetric-Api-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": { "code": "internal_error", "message": "Internal error.", "doc_url": "https://blockmetric.io/developers/errors#internal_error", "request_id": "req_5f0c1a9e2b7d4c3a8e6f1b20", "retryable": true } } } } } }, "schemas": { "Venue": { "type": "string", "enum": [ "hyperliquid", "lighter", "binance", "bybit", "okx" ], "description": "Trading venue." }, "Side": { "type": "string", "enum": [ "long", "short" ], "description": "Position side (for liquidations: the side of the liquidated position)." }, "Severity": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "1 info, 2 notable, 3 major, 4 critical." }, "RadarEventKind": { "type": "string", "enum": [ "whale_open", "whale_close", "whale_liquidated", "big_liquidation", "liq_cascade", "funding_extreme", "funding_flip", "oi_spike", "hack", "depeg", "tvl_drop", "cex_outflow", "whale_near_liq", "record", "smart_money", "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" ], "description": "Risk radar event kind." }, "PositionEventKind": { "type": "string", "enum": [ "open", "close", "increase", "decrease", "flip", "liquidated" ], "description": "Kind of whale position change (liquidated = confirmed by the wallet’s Hyperliquid liquidation fills)." }, "Plan": { "type": "string", "enum": [ "free", "pro", "desk", "api_dev", "api_pro" ], "description": "The caller's plan." }, "Meta": { "type": "object", "properties": { "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data timestamp in the response; null when there is no data yet." }, "source": { "type": "string", "description": "Venues / public sources the data comes from, comma-separated." }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "hyperliquid", "hl_position_snapshot", "lighter", "lighter_rh", "dydx", "gmx", "binance", "bybit", "okx", "defillama", "cex_por", "publicnode", "chainlink_onchain", "protocol_registry", "mempool_space", "robinhood_chain", "official_news", "ofac_sdn", "fbi_ic3" ] }, "description": "Enabled data sources this response is built from (ids as on /methodology#sources). Name them next to the data (attribution)." }, "plan": { "$ref": "#/components/schemas/Plan" }, "delayMinutes": { "type": "integer", "description": "Feed delay of the caller's plan in minutes (0 = real time)." }, "commercial": { "type": "boolean", "description": "Whether the caller's licence allows commercial use (with attribution)." }, "license": { "$ref": "#/components/schemas/License" }, "attribution": { "type": "object", "description": "Ready-made credit (API 1.13.0). Display licences show it next to the data (license.attributionRequired).", "properties": { "text": { "type": "string", "description": "\"Data by Blockmetric · Source: Hyperliquid · Binance\": the credit line for this response." }, "url": { "type": "string", "format": "uri", "description": "Link the credit must carry." } }, "required": [ "text", "url" ] }, "access": { "type": "object", "description": "The history window of the caller’s plan (API 1.14.0): rows before historyFrom are not served.", "properties": { "historyDays": { "type": "integer", "description": "Days of history the caller’s plan may read." }, "historyFrom": { "type": "string", "format": "date-time", "description": "Oldest time the caller may read right now (now − historyDays)." } }, "required": [ "historyDays", "historyFrom" ] }, "nextCursor": { "type": [ "string", "null" ], "description": "Paginated lists only: pass as ?cursor= for the next page; null on the last page." }, "nextUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Paginated lists only: the complete URL of the next page (same parameters + cursor); null on the last page." }, "nextAfter": { "type": "integer", "description": "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": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "clamped", "history", "coverage" ], "description": "clamped = a value outside its range was replaced by the nearest allowed one; history = cut to the plan history; coverage = part of the window was not collected." }, "param": { "type": "string", "description": "The parameter concerned." }, "message": { "type": "string", "description": "What was served instead, in plain words." }, "requested": { "type": [ "string", "number" ], "description": "The value asked for." }, "applied": { "type": [ "string", "number" ], "description": "The value used." } }, "required": [ "code", "param", "message" ] }, "description": "Only when the request was not served exactly as asked (API 1.14.0); absent otherwise." }, "restricted": { "type": "array", "items": { "type": "string", "enum": [ "binance", "bybit", "okx" ] }, "description": "Only on endpoints the licence review touches: exchanges whose raw rows are withheld from this response (aggregates stay). Absent once their data is licensed." } }, "required": [ "updatedAt", "source", "sources", "plan", "delayMinutes", "commercial", "license", "attribution", "access" ] }, "License": { "type": "object", "description": "What the caller may do with this response (see /terms#api-license).", "properties": { "id": { "type": "string", "enum": [ "public", "personal", "internal", "display", "enterprise" ], "description": "Licence tier of the caller: public (keyless X-Blockmetric-Access: public: non-commercial, attribution), personal (Free / Pro / Desk keys), internal (API Dev: one organisation), display (API Pro: your own product, attribution required), enterprise (contract)." }, "display": { "type": "boolean", "description": "Whether the data may be shown to people outside the licensee (end users of its own product)." }, "attributionRequired": { "type": "boolean", "description": "Whether the attribution must be shown next to the data, linked to the site." }, "attribution": { "type": [ "string", "null" ], "description": "Exact attribution text (\"Data by Blockmetric\"); null when no attribution duty applies." }, "redistribution": { "type": "boolean", "description": "Whether raw redistribution / resale is allowed (Enterprise only)." }, "mauCap": { "type": [ "integer", "null" ], "description": "Monthly active end users a display licence covers; null when not applicable." }, "terms": { "type": "string", "format": "uri", "description": "Licence terms." } }, "required": [ "id", "display", "attributionRequired", "attribution", "redistribution", "mauCap", "terms" ] }, "ErrorBody": { "type": "object", "properties": { "error": { "type": "object", "description": "snake_case on purpose (doc_url, request_id); the rest of the API is camelCase.", "properties": { "code": { "type": "string", "enum": [ "invalid_param", "unauthorized", "plan_required", "scope_required", "ip_not_allowed", "origin_not_allowed", "source_restricted", "https_required", "not_found", "method_not_allowed", "rate_limited", "daily_limit_exceeded", "stream_limit", "internal_error" ], "description": "Stable machine-readable code (see the error catalogue)." }, "message": { "type": "string", "description": "Human-readable explanation; may change, do not parse it." }, "doc_url": { "type": "string", "format": "uri", "description": "Error catalogue entry for this code." }, "request_id": { "type": "string", "description": "Same as the X-Request-Id header; quote it when contacting support." }, "retryable": { "type": "boolean", "description": "Whether the same request can succeed later (429 after Retry-After, 5xx with backoff). API 1.14.0." }, "param": { "type": "string", "description": "The query or path parameter the error is about (API 1.14.0)." } }, "required": [ "code", "message", "doc_url", "request_id", "retryable" ] } }, "required": [ "error" ] }, "Market": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid." }, "mark": { "type": [ "number", "null" ], "description": "Mark price." }, "oracle": { "type": [ "number", "null" ], "description": "Oracle / index price." }, "fundingHourly": { "type": [ "number", "null" ], "description": "Hourly funding rate, fraction (0.0001 = 0.01 %/h)." }, "fundingApr": { "type": [ "number", "null" ], "description": "Annualised funding (hourly × 24 × 365), fraction." }, "openInterestUsd": { "type": [ "number", "null" ], "description": "Open interest (USD)." }, "volume24hUsd": { "type": [ "number", "null" ], "description": "24h volume (USD)." }, "premium": { "type": [ "number", "null" ], "description": "Mark premium over the oracle, fraction." }, "maxLeverage": { "type": [ "integer", "null" ], "description": "Maximum leverage." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "venue", "coin", "mark", "oracle", "fundingHourly", "fundingApr", "openInterestUsd", "volume24hUsd", "premium", "maxLeverage", "updatedAt" ] }, "FundingCell": { "type": "object", "properties": { "fundingHourly": { "type": [ "number", "null" ], "description": "Hourly funding rate, fraction." }, "fundingApr": { "type": [ "number", "null" ], "description": "Annualised funding, fraction." }, "openInterestUsd": { "type": [ "number", "null" ], "description": "Open interest (USD)." }, "mark": { "type": [ "number", "null" ], "description": "Mark price." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "fundingHourly", "fundingApr", "openInterestUsd", "mark", "updatedAt" ] }, "FundingRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "hlOpenInterestUsd": { "type": [ "number", "null" ], "description": "Hyperliquid open interest (sort key) (USD)." }, "byVenue": { "type": "object", "description": "Funding per venue; venues without the coin are missing.", "properties": { "hyperliquid": { "$ref": "#/components/schemas/FundingCell" }, "lighter": { "$ref": "#/components/schemas/FundingCell" }, "binance": { "$ref": "#/components/schemas/FundingCell" }, "bybit": { "$ref": "#/components/schemas/FundingCell" }, "okx": { "$ref": "#/components/schemas/FundingCell" } }, "additionalProperties": false }, "aprSpread": { "type": [ "number", "null" ], "description": "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": { "type": [ "number", "null" ], "description": "Largest absolute annualised funding of any venue, fraction." } }, "required": [ "coin", "hlOpenInterestUsd", "byVenue", "aprSpread", "maxAbsApr" ] }, "Liquidation": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "venue": { "$ref": "#/components/schemas/Venue" }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "side": { "type": [ "string", "null" ], "enum": [ "long", "short", null ], "description": "Side of the liquidated position." }, "price": { "type": [ "number", "null" ], "description": "Fill price." }, "qty": { "type": [ "number", "null" ], "description": "Quantity in coins." }, "usd": { "type": [ "number", "null" ], "description": "Notional (USD)." } }, "required": [ "id", "ts", "venue", "coin", "side", "price", "qty", "usd" ] }, "LiqBucket": { "type": "object", "properties": { "px": { "type": "number", "description": "Lower edge of the price bucket." }, "longUsd": { "type": "number", "description": "Long positions liquidated in this bucket (USD)." }, "shortUsd": { "type": "number", "description": "Short positions liquidated in this bucket (USD)." }, "positions": { "type": "integer", "description": "Positions in the bucket." } }, "required": [ "px", "longUsd", "shortUsd", "positions" ] }, "LiqMap": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Current Hyperliquid mark." }, "bucketSize": { "type": [ "number", "null" ], "description": "Width of a price bucket." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/LiqBucket" }, "description": "Price buckets ascending; long liquidations sit below the mark, short liquidations above it." }, "totals": { "type": "object", "properties": { "longUsd": { "type": "number", "description": "Total long (USD)." }, "shortUsd": { "type": "number", "description": "Total short (USD)." }, "positions": { "type": "integer", "description": "Number of positions." } }, "required": [ "longUsd", "shortUsd", "positions" ], "description": "Sums over the rows of this object." } }, "required": [ "coin", "mark", "bucketSize", "updatedAt", "buckets", "totals" ] }, "Position": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^(0x[0-9a-f]{40}|[0-9]{1,20})$", "description": "Hyperliquid address (lowercase), or with venue \"lighter\" the Lighter account index." }, "label": { "type": [ "string", "null" ], "description": "Wallet label (public label or leaderboard display name)." }, "accountValue": { "type": [ "number", "null" ], "description": "Account value (USD)." }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "side": { "$ref": "#/components/schemas/Side" }, "size": { "type": "number", "description": "Size in coins." }, "entryPx": { "type": [ "number", "null" ], "description": "Entry price." }, "positionUsd": { "type": "number", "description": "Notional (USD)." }, "leverage": { "type": [ "number", "null" ], "description": "Leverage of the position (notional / margin)." }, "leverageType": { "type": [ "string", "null" ], "description": "cross | isolated" }, "liqPx": { "type": [ "number", "null" ], "description": "Liquidation price." }, "liqDistance": { "type": [ "number", "null" ], "description": "Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark price." }, "marginUsed": { "type": [ "number", "null" ], "description": "Margin used (USD)." }, "unrealizedPnl": { "type": [ "number", "null" ], "description": "Unrealised PnL (USD)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." }, "venue": { "type": "string", "enum": [ "hyperliquid", "lighter" ], "description": "Venue of the position (present for Lighter rows; absent = Hyperliquid)." } }, "required": [ "address", "label", "accountValue", "coin", "side", "size", "entryPx", "positionUsd", "leverage", "leverageType", "liqPx", "liqDistance", "mark", "marginUsed", "unrealizedPnl", "updatedAt" ] }, "PositionEvent": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "label": { "type": [ "string", "null" ], "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "kind": { "$ref": "#/components/schemas/PositionEventKind" }, "side": { "type": [ "string", "null" ], "enum": [ "long", "short", null ], "description": "Position side (long / short); for trades and orders the side named in the description." }, "sizeDelta": { "type": [ "number", "null" ], "description": "Change in coins." }, "usdDelta": { "type": [ "number", "null" ], "description": "Change (USD)." }, "price": { "type": [ "number", "null" ], "description": "Price in the quote currency of the venue (USD / USDT / USDC)." }, "data": { "description": "Kind-specific details (JSON) or null." } }, "required": [ "id", "ts", "address", "label", "coin", "kind", "side", "sizeDelta", "usdDelta", "price", "data" ] }, "Wallet": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "label": { "type": [ "string", "null" ], "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "accountValue": { "type": [ "number", "null" ], "description": "Account value (USD)." }, "pnlMonth": { "type": [ "number", "null" ], "description": "30-day PnL (leaderboard) (USD)." }, "vlmMonth": { "type": [ "number", "null" ], "description": "30-day volume (leaderboard) (USD)." }, "source": { "type": [ "string", "null" ], "description": "How the wallet was found (e.g. hl_leaderboard)." }, "priority": { "type": "integer", "description": "Polling priority (1 = most often)." }, "firstSeen": { "type": "string", "format": "date-time", "description": "First time this item was observed (ISO 8601 UTC)." }, "lastPolledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last time the wallet was read from Hyperliquid (ISO 8601 UTC), null = not yet." }, "positionCount": { "type": [ "integer", "null" ], "description": "Number of open positions." } }, "required": [ "address", "label", "accountValue", "pnlMonth", "vlmMonth", "source", "priority", "firstSeen", "lastPolledAt", "positionCount" ] }, "WalletDetail": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" }, "description": "Current positions, largest first." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PositionEvent" }, "description": "Latest position events, newest first." }, "totals": { "type": "object", "properties": { "positionUsd": { "type": "number", "description": "Open notional (USD)." }, "longUsd": { "type": "number", "description": "Long notional (USD)." }, "shortUsd": { "type": "number", "description": "Short notional (USD)." }, "unrealizedPnl": { "type": "number", "description": "Unrealised PnL summed over the positions that report one (USD)." }, "unrealizedPnlMissing": { "type": "integer", "description": "Positions without a reported unrealised PnL (left out of unrealizedPnl, not counted as 0)." } }, "required": [ "positionUsd", "longUsd", "shortUsd", "unrealizedPnl", "unrealizedPnlMissing" ], "description": "Sums over the rows of this object." } }, "required": [ "wallet", "positions", "events", "totals" ] }, "SecurityItem": { "type": "object", "properties": { "id": { "type": "string", "description": "\"evt_\" (detector) or \"inc_\" (curated)." }, "origin": { "type": "string", "enum": [ "detector", "curated" ], "description": "detector = found by our detectors in market data; curated = an incident written up by us with primary sources." }, "ts": { "type": "string", "format": "date-time", "description": "Event time (detector) or publication time (curated)." }, "date": { "type": "string", "description": "UTC day of the incident (YYYY-MM-DD)." }, "kind": { "type": "string", "description": "Radar event kind (\"incident\" for curated items)." }, "type": { "type": "string", "description": "Incident type (exploit, oracle_manipulation, …) or detector type (depeg, outflow, adl, …)." }, "severity": { "$ref": "#/components/schemas/Severity" }, "title": { "type": "string", "description": "One-line factual title in our own words." }, "summary": { "type": [ "string", "null" ], "description": "Our own factual text." }, "chains": { "type": "array", "items": { "type": "string" }, "description": "Chains involved." }, "coin": { "type": [ "string", "null" ], "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "amountUsd": { "type": [ "number", "null" ], "description": "Reported loss / flow (USD)." }, "status": { "type": [ "string", "null" ], "description": "Curated: unknown | ongoing | funds_frozen | partially_recovered | recovered | not_recovered | resolved." }, "url": { "type": "string", "description": "Evidence page on the website." }, "links": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Kind of the item (enum of this field)." }, "url": { "type": "string", "description": "Link (absolute URL)." }, "label": { "type": "string", "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." } }, "required": [ "kind", "url", "label" ] }, "description": "Curated: primary-source links (post-mortem, announcement, tx, address, governance) and coverage links." }, "data": { "description": "Detector: the evidence numbers of the event (JSON). Curated: recoveredUsd, amountSource, txs." } }, "required": [ "id", "origin", "ts", "date", "kind", "type", "severity", "title", "summary", "chains", "coin", "amountUsd", "status", "url", "links", "data" ] }, "RiskListing": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "sanctioned", "stolen_funds", "exploit", "drainer", "phishing", "other" ], "description": "The source’s classification: sanctioned (OFAC), stolen_funds, exploit, drainer, phishing, other." }, "source": { "type": "string", "enum": [ "ofac_sdn", "fbi_ic3", "incident" ], "description": "ofac_sdn (OFAC SDN list), fbi_ic3 (FBI / IC3 announcement) or incident (official post-mortem)." }, "sourceLabel": { "type": "string", "description": "How the source is named, e.g. \"OFAC SDN list\", \"FBI (IC3 PSA I-022625-PSA)\"." }, "sourceUrl": { "type": "string", "description": "Link to the listing at the source." }, "sourceDate": { "type": [ "string", "null" ], "description": "Date of the listing (YYYY-MM-DD): the publication for FBI and post-mortems, the first SDN list that contained the address for OFAC." }, "listing": { "type": "string", "description": "The one claim, in the source’s terms: \"Listed as by , \"." }, "detail": { "type": [ "string", "null" ], "description": "The source’s own wording (FBI quote, OFAC sanctions programs, role in the post-mortem). Never a name." }, "assets": { "type": [ "string", "null" ], "description": "OFAC: the currency tickers of the address fields, e.g. \"ETH, USDT\"." }, "incidentId": { "type": [ "integer", "null" ], "description": "Curated incident the listing belongs to (/security/incidents/)." }, "firstSeen": { "type": "string", "format": "date-time", "description": "When we first imported the listing." } }, "required": [ "category", "source", "sourceLabel", "sourceUrl", "sourceDate", "listing", "detail", "assets", "incidentId", "firstSeen" ] }, "ListedWallet": { "type": "object", "properties": { "address": { "type": "string", "description": "The address as listed (EVM and bech32 lower case, other formats as the source publishes them)." }, "network": { "type": "string", "description": "Address family: evm (one key on every EVM chain), bitcoin, tron, litecoin, monero …" }, "tracked": { "type": "boolean", "description": "We follow its on-chain movements (EVM on Ethereum, Arbitrum, Base; Bitcoin)." }, "category": { "type": "string", "enum": [ "sanctioned", "stolen_funds", "exploit", "drainer", "phishing", "other" ], "description": "The source’s classification." }, "source": { "type": "string", "enum": [ "ofac_sdn", "fbi_ic3", "incident" ], "description": "ofac_sdn | fbi_ic3 | incident." }, "sourceLabel": { "type": "string", "description": "How the source is named." }, "sourceUrl": { "type": "string", "description": "Link to the listing at the source." }, "sourceDate": { "type": [ "string", "null" ], "description": "Date of the listing (YYYY-MM-DD)." }, "listing": { "type": "string", "description": "\"Listed as by , \"." }, "detail": { "type": [ "string", "null" ], "description": "The source’s own wording. Never a name." }, "assets": { "type": [ "string", "null" ], "description": "OFAC: currency tickers of the address fields." }, "incidentId": { "type": [ "integer", "null" ], "description": "Curated incident of the listing." }, "firstSeen": { "type": "string", "format": "date-time", "description": "When we first imported the listing." }, "lastMoveTs": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest tracked movement of the address." }, "movements": { "type": "integer", "description": "Tracked movements of the address." }, "balanceUsd": { "type": [ "number", "null" ], "description": "Last known balance on the scanned EVM chains at our prices, null when not read or not priced (USD)." }, "balanceAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the balance was read." } }, "required": [ "address", "network", "tracked", "category", "source", "sourceLabel", "sourceUrl", "sourceDate", "listing", "detail", "assets", "incidentId", "firstSeen", "lastMoveTs", "movements", "balanceUsd", "balanceAt" ] }, "RiskMovement": { "type": "object", "properties": { "id": { "type": "integer", "description": "Movement id." }, "ts": { "type": "string", "format": "date-time", "description": "Block time." }, "chain": { "type": "string", "description": "ethereum | arbitrum | base | bitcoin." }, "type": { "type": "string", "description": "transfer | exchange_in | exchange_out | exchange_exchange | mint | burn | bridge | dex_buy | dex_sell." }, "asset": { "type": "string", "description": "Asset symbol; \"(unverified)\" after a symbol outside our curated token list (the token’s own claim)." }, "amount": { "type": "number", "description": "Units of the asset." }, "usd": { "type": [ "number", "null" ], "description": "Value at our price; null = price unavailable (always for unverified tokens) (USD)." }, "priceSource": { "type": [ "string", "null" ], "description": "Basis of usd, as in /movements." }, "title": { "type": "string", "description": "Factual one-liner with the short source, e.g. \"Listed wallet (OFAC) moved 10 ETH ($30K) to Binance on Ethereum\"." }, "listedAddress": { "type": "string", "description": "The listed address of the movement." }, "listedSide": { "type": "string", "enum": [ "from", "to" ], "description": "Which side of the movement is the listed address." }, "from": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "description": "Wallet or contract address (EVM lowercase 0x…, or Bitcoin)." }, "label": { "type": [ "string", "null" ], "description": "Label with a cited source (exchange proof of reserves, protocol docs), else null. Never a risk label." }, "url": { "type": [ "string", "null" ], "description": "Explorer page." } }, "required": [ "address", "label", "url" ], "description": "Start of the window (ISO 8601 UTC) or the sending side of a movement." }, "to": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "description": "Wallet or contract address (EVM lowercase 0x…, or Bitcoin)." }, "label": { "type": [ "string", "null" ], "description": "Label with a cited source, else null. Never a risk label." }, "url": { "type": [ "string", "null" ], "description": "Explorer page." } }, "required": [ "address", "label", "url" ], "description": "End of the window (ISO 8601 UTC) or the receiving side of a movement." }, "unverifiedToken": { "type": "boolean", "description": "Token outside our curated list: never priced." }, "block": { "type": "integer", "description": "Block height." }, "tx": { "type": "string", "description": "Transaction hash." }, "txUrl": { "type": [ "string", "null" ], "description": "Transaction on the official explorer." } }, "required": [ "id", "ts", "chain", "type", "asset", "amount", "usd", "priceSource", "title", "listedAddress", "listedSide", "from", "to", "unverifiedToken", "block", "tx", "txUrl" ] }, "ListedWalletDetail": { "type": "object", "properties": { "address": { "type": "string", "description": "The address as listed." }, "network": { "type": "string", "description": "Address family (evm, bitcoin, tron …)." }, "tracked": { "type": "boolean", "description": "We follow its on-chain movements." }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/RiskListing" }, "description": "Every active listing of the address, oldest first." }, "balances": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "ethereum | arbitrum | base | hyperliquid." }, "checkedAt": { "type": "string", "format": "date-time", "description": "When the balances were read." }, "balances": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Units per asset (native ETH and the curated tokens with a balance; on hyperliquid the account value in USD as accountValue)." }, "usd": { "type": [ "number", "null" ], "description": "Their value at our prices (USD)." } }, "required": [ "chain", "checkedAt", "balances", "usd" ] }, "description": "Last known balances per scanned EVM chain and the Hyperliquid account of the same key." }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/RiskMovement" }, "description": "Tracked movements, newest first, within the plan history." } }, "required": [ "address", "network", "tracked", "listings", "balances", "movements" ] }, "RadarEvent": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "kind": { "$ref": "#/components/schemas/RadarEventKind" }, "severity": { "$ref": "#/components/schemas/Severity" }, "coin": { "type": [ "string", "null" ], "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "title": { "type": "string", "description": "One-line factual title in our own words." }, "body": { "type": [ "string", "null" ], "description": "Details in our own words, or null." }, "data": { "description": "Kind-specific details (JSON) or null." }, "source": { "type": [ "string", "null" ], "description": "Data source (radar, defillama, …)." } }, "required": [ "id", "ts", "kind", "severity", "coin", "title", "body", "data", "source" ] }, "Stats": { "type": "object", "properties": { "wallets": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number." }, "polled": { "type": "integer", "description": "Wallets read at least once." }, "withPositions": { "type": "integer", "description": "Wallets with at least one open position." } }, "required": [ "total", "polled", "withPositions" ], "description": "Number of distinct wallets." }, "positions": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of items (liquidations, positions …) in the group." }, "totalUsd": { "type": "number", "description": "Open notional (USD)." }, "longUsd": { "type": "number", "description": "Long (USD)." }, "shortUsd": { "type": "number", "description": "Short (USD)." }, "coins": { "type": "integer", "description": "Number of coins." } }, "required": [ "count", "totalUsd", "longUsd", "shortUsd", "coins" ], "description": "Number of positions." }, "markets": { "type": "array", "items": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" }, "coins": { "type": "integer", "description": "Number of coins." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "venue", "coins", "updatedAt" ] }, "description": "Markets per venue." }, "events": { "type": "object", "properties": { "radar": { "type": "integer", "description": "Stored radar events." }, "positionEvents": { "type": "integer", "description": "Stored whale position changes." }, "liquidations24h": { "type": "integer", "description": "Liquidations in the last 24 hours." }, "liquidations24hUsd": { "type": "number", "description": "Liquidations in the last 24 h (USD)." } }, "required": [ "radar", "positionEvents", "liquidations24h", "liquidations24hUsd" ], "description": "Events of this view (newest first) or their count." }, "liqLevels": { "type": "object", "properties": { "coins": { "type": "integer", "description": "Number of coins." }, "buckets": { "type": "integer", "description": "Price buckets." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "coins", "buckets", "updatedAt" ], "description": "Liquidation map: coins, price buckets and the last update." }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "job": { "type": "string", "description": "Collector job id." }, "lastRun": { "type": "string", "format": "date-time", "description": "Last successful run." }, "feed": { "type": "string", "description": "Public data feed the job belongs to: the id in GET /status feeds[], whose label is its plain-English name (API 1.14.0)." } }, "required": [ "job", "lastRun" ] }, "description": "Last successful run of each collector job behind a public data feed, newest first (internal maintenance jobs are not listed since 1.14.0)." }, "focus": { "type": "object", "properties": { "heatmapSnapshots": { "type": "integer", "description": "Stored heatmap snapshots." }, "heatmapCoins": { "type": "integer", "description": "Coins with heatmap snapshots." }, "heatmapUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest heatmap snapshot." }, "longShortRows": { "type": "integer", "description": "Stored long/short rows." }, "longShortUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest long/short row." }, "whaleLabels": { "type": "integer", "description": "Public wallet labels with a cited source." }, "clusterObservations": { "type": "integer", "description": "Liquidation clusters observed for the hit-rate statistic." }, "clustersReached": { "type": "integer", "description": "Of those, clusters the price reached." }, "telegramCards": { "type": "integer", "description": "Cards posted to the public Telegram channel." } }, "required": [ "heatmapSnapshots", "heatmapCoins", "heatmapUpdatedAt", "longShortRows", "longShortUpdatedAt", "whaleLabels", "clusterObservations", "clustersReached", "telegramCards" ], "description": "Heatmap, long/short and whale-label tables." } }, "required": [ "wallets", "positions", "markets", "events", "liqLevels", "jobs" ] }, "Coin": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark price." }, "openInterestUsd": { "type": [ "number", "null" ], "description": "Open interest (USD)." }, "volume24hUsd": { "type": [ "number", "null" ], "description": "24h volume (USD)." }, "fundingApr": { "type": [ "number", "null" ], "description": "Annualised funding, fraction." }, "maxLeverage": { "type": [ "integer", "null" ], "description": "Maximum leverage the venue allows on this market." }, "trackedPositions": { "type": "integer", "description": "Tracked positions on this coin." }, "hasLiqMap": { "type": "boolean", "description": "Whether a liquidation map exists." } }, "required": [ "coin", "mark", "openInterestUsd", "volume24hUsd", "fundingApr", "maxLeverage", "trackedPositions", "hasLiqMap" ] }, "Candles": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "tf": { "type": "string", "enum": [ "5m", "15m", "1h", "4h", "1d" ], "description": "Bucket interval (5m, 15m, 1h, …)." }, "candles": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time", "description": "Bucket start (UTC)." }, "open": { "type": "number", "description": "Open price of the bucket." }, "high": { "type": "number", "description": "High price of the bucket." }, "low": { "type": "number", "description": "Low price of the bucket." }, "close": { "type": "number", "description": "Close price of the bucket." }, "volumeUsd": { "type": [ "number", "null" ], "description": "Traded quote volume of the bucket where the venue reports it (USD)." }, "volumeBase": { "type": [ "number", "null" ], "description": "Traded volume in base units (Hyperliquid units)." }, "volumeVenue": { "type": [ "string", "null" ], "enum": [ "binance", "hyperliquid", null ], "description": "Venue the volume was traded on." }, "price": { "type": "string", "enum": [ "mark", "trades", "mixed" ], "description": "mark = 30-second Hyperliquid mark samples, trades = trade candles of the volume venue, mixed = both within the bucket." }, "complete": { "type": "boolean", "description": "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)." } }, "required": [ "t", "open", "high", "low", "close", "volumeUsd", "volumeBase", "volumeVenue", "price", "complete" ] }, "description": "Oldest → newest." } }, "required": [ "coin", "tf", "candles" ] }, "Heatmap": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "bucketSize": { "type": "number", "description": "Price step between rows (0 when there is no data)." }, "times": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Column times, oldest → newest." }, "prices": { "type": "array", "items": { "type": "number" }, "description": "Lower edge of each price row, ascending." }, "cells": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "cells[timeIndex][priceIndex]: USD that would be liquidated in that bucket at that time (long + short)." }, "longCells": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "Same shape, long positions (below the mark)." }, "shortCells": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "Same shape, short positions (above the mark)." }, "mark": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Mark price per column (null when no snapshot exists for that slot)." }, "hasSnapshot": { "type": "array", "items": { "type": "boolean" }, "description": "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": { "type": "number", "description": "Largest cell value (USD)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest snapshot." }, "tf": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "12h", "1d" ], "description": "Column interval (absent with the deprecated stepMinutes)." }, "stepMinutes": { "type": "integer", "description": "Column width in minutes." }, "layer": { "type": "string", "enum": [ "fine", "wide" ], "description": "fine = 0.1 % buckets within ±10 % (every minute, top 20 coins); wide = 0.5 % buckets within ±50 %. One layer per response." }, "bucketPct": { "type": "number", "description": "Bucket width of the layer as a fraction of the mark (0.001 / 0.005). Deprecated: use bucketFraction (same value).", "deprecated": true }, "rangePct": { "type": "number", "description": "Range of the layer around the mark as a fraction (0.1 / 0.5). Deprecated: use rangeFraction (same value).", "deprecated": true }, "bucketFraction": { "type": "number", "description": "Bucket width of the layer as a fraction of the mark (0.001 = 0.1 %)." }, "rangeFraction": { "type": "number", "description": "Range of the layer around the mark as a fraction (0.5 = ±50 %)." }, "clusters": { "type": [ "object", "null" ], "properties": { "time": { "type": "string", "format": "date-time", "description": "Column the clusters are read from (the newest one with a snapshot)." }, "mark": { "type": [ "number", "null" ], "description": "Mark of that column." }, "above": { "type": "array", "items": { "$ref": "#/components/schemas/HeatmapCluster" }, "description": "Largest buckets at or above the mark, largest first (short liquidations)." }, "below": { "type": "array", "items": { "$ref": "#/components/schemas/HeatmapCluster" }, "description": "Largest buckets below the mark, largest first (long liquidations)." } }, "required": [ "time", "mark", "above", "below" ], "description": "With ?clusters=N: the largest buckets above and below the mark of the newest column with a snapshot." }, "snapshotAt": { "type": "array", "items": { "type": [ "string", "null" ], "format": "date-time" }, "description": "Per column: exact time of the snapshot drawn (the first one inside the column; the newest one in a live column); null = gap." }, "live": { "type": "boolean", "description": "The last column is still running and shows the newest snapshot." }, "freshUsdShare": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "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": { "type": "array", "items": { "type": [ "integer", "null" ] }, "description": "Per column: USD-weighted median age of the mapped positions in seconds; null = unknown." }, "venue": { "type": "string", "enum": [ "hyperliquid", "lighter", "lighter_rh", "dydx", "gmx", "all" ], "description": "Venue layer of the answer (present with ?venue=lighter | lighter_rh | dydx | gmx | all; absent = Hyperliquid)." }, "venueColumns": { "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string", "enum": [ "hyperliquid", "lighter", "lighter_rh", "dydx", "gmx" ], "description": "Trading venue the row comes from." }, "present": { "type": "array", "items": { "type": "boolean" }, "description": "Per column: the venue contributed a snapshot." } }, "required": [ "venue", "present" ] }, "description": "venue=all: per venue, the columns it contributed a snapshot to (a venue without one adds nothing to that column)." }, "columnSource": { "type": "array", "items": { "type": [ "string", "null" ], "enum": [ "all_positions", "daily_fill", "reconstructed", "tracked", null ], "description": "all_positions = daily history of every open Hyperliquid position (1d); reconstructed (not returned since 1.22.0) = an intraday column without a live snapshot showing the levels of all positions reconstructed from fills between two daily snapshots; daily_fill = the daily snapshot in an intraday column without a live one (when no reconstruction exists); tracked = tracked wallets." }, "description": "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": { "type": "array", "items": { "type": [ "string", "null" ], "enum": [ "live", "reconstructed_fills", "daily_snapshot", null ] }, "description": "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": { "type": "array", "items": { "type": [ "string", "null" ], "format": "date-time" }, "description": "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": { "type": "array", "items": { "type": [ "integer", "null" ] }, "description": "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": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "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": { "type": "array", "items": { "type": [ "string", "null" ], "enum": [ "pass", "warn", "fail", "unvalidated", null ] }, "description": "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." } }, "required": [ "coin", "bucketSize", "times", "prices", "cells", "longCells", "shortCells", "mark", "hasSnapshot", "maxUsd", "updatedAt" ] }, "OiBand": { "type": "object", "properties": { "priceLo": { "type": "number", "description": "Lower edge of the band (USD, inclusive)." }, "priceHi": { "type": "number", "description": "Upper edge of the band (USD, exclusive)." }, "addedUsd": { "type": [ "number", "null" ], "description": "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)." }, "removedUsd": { "type": [ "number", "null" ], "description": "Open interest removed while the price was in this band (sum of the negative changes, as a positive number); null = withheld (USD)." }, "netUsd": { "type": [ "number", "null" ], "description": "addedUsd minus removedUsd; null = withheld (USD)." }, "steps": { "type": "integer", "description": "5-minute steps with a change whose price was in this band." }, "venues": { "type": "array", "items": { "type": "string", "enum": [ "binance", "bybit", "okx" ] }, "description": "Exchanges with a change in this band." }, "byVenue": { "type": "object", "description": "Per exchange (only exchanges that are not withheld by the licence review).", "properties": { "binance": { "type": "object", "description": "The part of binance in this band.", "properties": { "addedUsd": { "type": "number", "description": "Added (USD)." }, "removedUsd": { "type": "number", "description": "Removed (USD)." }, "steps": { "type": "integer", "description": "Steps with a change." } }, "required": [ "addedUsd", "removedUsd", "steps" ] }, "bybit": { "type": "object", "description": "The part of bybit in this band.", "properties": { "addedUsd": { "type": "number", "description": "Added (USD)." }, "removedUsd": { "type": "number", "description": "Removed (USD)." }, "steps": { "type": "integer", "description": "Steps with a change." } }, "required": [ "addedUsd", "removedUsd", "steps" ] }, "okx": { "type": "object", "description": "The part of okx in this band.", "properties": { "addedUsd": { "type": "number", "description": "Added (USD)." }, "removedUsd": { "type": "number", "description": "Removed (USD)." }, "steps": { "type": "integer", "description": "Steps with a change." } }, "required": [ "addedUsd", "removedUsd", "steps" ] } }, "additionalProperties": false }, "withheld": { "type": "boolean", "description": "true: amounts left out: with the licence review pending, the sum over the exchanges of this band would be one exchange's own figure." } }, "required": [ "priceLo", "priceHi", "addedUsd", "removedUsd", "netUsd", "steps", "venues" ] }, "HeatmapOpenInterest": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "venue": { "type": "string", "enum": [ "all", "binance", "bybit", "okx" ], "description": "The venue asked for (all = every enabled exchange, summed per band)." }, "venues": { "type": "array", "items": { "type": "string", "enum": [ "binance", "bybit", "okx" ] }, "description": "Exchanges read for this answer (enabled ones)." }, "from": { "type": "string", "format": "date-time", "description": "Window start." }, "to": { "type": "string", "format": "date-time", "description": "Window end." }, "hours": { "type": "integer", "description": "Window in hours." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark now (the band width is a round step near bandFraction of it)." }, "bandSize": { "type": "number", "description": "Width of a price band (USD); 0 without a price." }, "bandFraction": { "type": "number", "description": "Band width asked for, fraction of the price (0.005 = 0.5 %)." }, "stepMinutes": { "type": "integer", "description": "Length of one step: two consecutive 5-minute buckets of our collection." }, "steps": { "type": "integer", "description": "Steps with a change of open interest in the window (all exchanges read)." }, "spanningSteps": { "type": "integer", "description": "Of those, steps whose price range crossed a band edge (counted in the band of their middle price)." }, "firstStep": { "type": [ "string", "null" ], "format": "date-time", "description": "First step with data in the window." }, "lastStep": { "type": [ "string", "null" ], "format": "date-time", "description": "Last step with data in the window." }, "fullResolutionDays": { "type": "integer", "description": "Days of 5-minute open interest kept (older history is hourly and not used)." }, "totals": { "type": "object", "properties": { "addedUsd": { "type": "number", "description": "Open interest added over the published bands (USD)." }, "removedUsd": { "type": "number", "description": "Open interest removed over the published bands (USD)." }, "netUsd": { "type": "number", "description": "addedUsd minus removedUsd (USD)." }, "withheldBands": { "type": "integer", "description": "Bands without amounts (licence review: a single withheld exchange would be readable from them)." } }, "required": [ "addedUsd", "removedUsd", "netUsd", "withheldBands" ], "description": "Sums over the rows of this object." }, "bands": { "type": "array", "items": { "$ref": "#/components/schemas/OiBand" }, "description": "Price bands with a change, lowest first." } }, "required": [ "coin", "venue", "venues", "from", "to", "hours", "mark", "bandSize", "bandFraction", "stepMinutes", "steps", "spanningSteps", "firstStep", "lastStep", "fullResolutionDays", "totals", "bands" ] }, "WalletBand": { "type": "object", "properties": { "priceLo": { "type": "number", "description": "Lower edge of the band (USD, inclusive)." }, "priceHi": { "type": "number", "description": "Upper edge of the band (USD, exclusive)." }, "distance": { "type": [ "number", "null" ], "description": "Signed distance from the mark to priceLo, fraction (−0.03 = 3 % below)." }, "positions": { "type": "integer", "description": "Tracked positions with their liquidation price in the band now (all of them)." }, "longUsd": { "type": "number", "description": "Notional of those long positions (USD)." }, "shortUsd": { "type": "number", "description": "Notional of those short positions (USD)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest poll among those positions." }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/ZoneWallet" }, "description": "The largest of them, largest first (limit)." }, "longLevelUsd": { "type": "number", "description": "clusters only: long liquidations of this level in the current liquidation map (USD)." }, "shortLevelUsd": { "type": "number", "description": "clusters only: short liquidations of this level in the current liquidation map (USD)." } }, "required": [ "priceLo", "priceHi", "distance", "positions", "longUsd", "shortUsd", "updatedAt", "wallets" ] }, "ZoneWallet": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "label": { "type": [ "string", "null" ], "description": "Wallet label (leaderboard display name)." }, "side": { "$ref": "#/components/schemas/Side" }, "positionUsd": { "type": "number", "description": "Notional (USD)." }, "size": { "type": "number", "description": "Size in coins." }, "entryPx": { "type": [ "number", "null" ], "description": "Entry price." }, "leverage": { "type": [ "number", "null" ], "description": "Leverage of the position (notional / margin)." }, "leverageType": { "type": [ "string", "null" ], "description": "cross | isolated" }, "liqPx": { "type": [ "number", "null" ], "description": "Liquidation price." }, "liqDistance": { "type": [ "number", "null" ], "description": "Signed distance from the mark to the liquidation price, fraction (−0.12 = 12 % below the mark)." }, "accountValue": { "type": [ "number", "null" ], "description": "Account value (USD)." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the wallet was last read." }, "url": { "type": "string", "description": "The wallet page on the website." } }, "required": [ "address", "label", "side", "positionUsd", "size", "entryPx", "leverage", "leverageType", "liqPx", "liqDistance", "accountValue", "updatedAt", "url" ] }, "HeatmapWallets": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark now." }, "bucketSize": { "type": [ "number", "null" ], "description": "Row width of the current liquidation map (USD)." }, "mapUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the current liquidation map." }, "bands": { "type": "array", "items": { "$ref": "#/components/schemas/WalletBand" }, "description": "One band (lo / hi or price), or the clusters largest levels above the mark, then below it." } }, "required": [ "coin", "mark", "bucketSize", "mapUpdatedAt", "bands" ] }, "Scoreboard": { "type": "object", "properties": { "method": { "type": "string", "description": "How clusters are recorded and scored." }, "rules": { "type": "object", "description": "The fixed rules behind the numbers.", "properties": { "minUsd": { "type": "number", "description": "Smallest recorded cluster (USD)." }, "topN": { "type": "integer", "description": "Clusters recorded per coin and side at most (the largest buckets)." }, "rangePct": { "type": "number", "description": "Clusters within this many percent of the mark are recorded." }, "repeatHours": { "type": "integer", "description": "The same bucket is recorded at most once per this many hours." }, "horizons": { "type": "array", "items": { "type": "integer" }, "description": "Horizons in hours." }, "minSample": { "type": "integer", "description": "Below this many scored clusters no rate is given." }, "smallSample": { "type": "integer", "description": "Below this many scored clusters a rate is flagged small." }, "distanceBands": { "type": "array", "items": { "type": "string" }, "description": "Distance bands of the comparison (percent from the mark to the near edge)." } }, "required": [ "minUsd", "topN", "rangePct", "repeatHours", "horizons", "minSample", "smallSample", "distanceBands" ] }, "coins": { "type": "array", "items": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin, or ALL for every coin." }, "since": { "type": [ "string", "null" ], "format": "date-time", "description": "First observation." }, "horizons": { "type": "array", "items": { "type": "object", "properties": { "horizonHours": { "type": "integer", "description": "Horizon in hours." }, "clusters": { "type": "integer", "description": "Scored clusters (observed at least the horizon ago)." }, "reached": { "type": "integer", "description": "Of those, touched by the price within the horizon." }, "hitRate": { "type": [ "number", "null" ], "description": "reached / clusters (fraction)." }, "medianMinutesToReach": { "type": [ "number", "null" ], "description": "Median minutes to the touch over the reached ones." }, "medianDistancePct": { "type": [ "number", "null" ], "description": "Median distance from the mark in percent." } }, "required": [ "horizonHours", "clusters", "reached", "hitRate", "medianMinutesToReach", "medianDistancePct" ] }, "description": "One entry per horizon (4, 24, 72 hours)." } }, "required": [ "coin", "since", "horizons" ] }, "description": "Per coin, most scored clusters first (ALL first without coin)." }, "current": { "type": [ "object", "null" ], "description": "With coin: the big clusters of its liquidation map now and how often similar past ones were reached; null without coin.", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark now." }, "mapUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the current liquidation map." }, "clusters": { "type": "array", "items": { "type": "object", "properties": { "side": { "$ref": "#/components/schemas/Side" }, "bucketPx": { "type": "number", "description": "Lower edge of the bucket (USD)." }, "bucketTop": { "type": "number", "description": "Upper edge of the bucket (USD)." }, "usd": { "type": "number", "description": "Liquidations in the bucket (USD)." }, "positions": { "type": "integer", "description": "Tracked positions in the bucket." }, "distancePct": { "type": "number", "description": "Percent from the mark to the near edge of the bucket." }, "rank": { "type": "integer", "description": "1 = the largest of its coin now." }, "distanceBand": { "type": "string", "description": "Distance band of the comparison." }, "scope": { "type": "string", "enum": [ "coin", "all_coins" ], "description": "coin = past clusters of this coin; all_coins = this coin had fewer than minSample scored at 24 hours, so every coin (same side and band)." }, "horizons": { "type": "array", "items": { "type": "object", "properties": { "horizonHours": { "type": "integer", "description": "Horizon in hours." }, "n": { "type": "integer", "description": "Scored past clusters like it." }, "reached": { "type": "integer", "description": "Of those, reached within the horizon." }, "rate": { "type": [ "number", "null" ], "description": "reached / n (fraction); null below minSample." }, "ci": { "type": [ "array", "null" ], "items": { "type": "number" }, "description": "95 % Wilson interval [low, high] (fractions)." }, "small": { "type": "boolean", "description": "n is at least minSample but below smallSample." } }, "required": [ "horizonHours", "n", "reached", "rate", "ci", "small" ] }, "description": "How often past clusters like it were reached, per horizon." } }, "required": [ "side", "bucketPx", "bucketTop", "usd", "positions", "distancePct", "rank", "distanceBand", "scope", "horizons" ] }, "description": "The big clusters of the liquidation map now (same rule as the recorded ones)." } }, "required": [ "coin", "mark", "mapUpdatedAt", "clusters" ] } }, "required": [ "method", "rules", "coins", "current" ] }, "HeatmapCluster": { "type": "object", "properties": { "price": { "type": "number", "description": "Lower edge of the price bucket." }, "usd": { "type": "number", "description": "Long + short that would be liquidated in the bucket (USD)." }, "longUsd": { "type": "number", "description": "Long positions (USD)." }, "shortUsd": { "type": "number", "description": "Short positions (USD)." }, "distance": { "type": [ "number", "null" ], "description": "Signed distance from the mark, fraction (−0.03 = 3 % below)." } }, "required": [ "price", "usd", "longUsd", "shortUsd", "distance" ] }, "LiquidationSummary": { "type": "object", "properties": { "hours": { "type": "number", "description": "Window in hours." }, "totalUsd": { "type": "number", "description": "Total (USD)." }, "longUsd": { "type": "number", "description": "Long positions liquidated (USD)." }, "shortUsd": { "type": "number", "description": "Short positions liquidated (USD)." }, "count": { "type": "integer", "description": "Number of items (liquidations, positions …) in the group." }, "byVenue": { "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string", "description": "Trading venue the row comes from." }, "longUsd": { "type": "number", "description": "Long (USD)." }, "shortUsd": { "type": "number", "description": "Short (USD)." }, "count": { "type": "integer", "description": "Number of items (liquidations, positions …) in the group." } }, "required": [ "venue", "longUsd", "shortUsd", "count" ] }, "description": "Split per venue." }, "byCoin": { "type": "array", "items": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "longUsd": { "type": "number", "description": "Long (USD)." }, "shortUsd": { "type": "number", "description": "Short (USD)." }, "count": { "type": "integer", "description": "Number of items (liquidations, positions …) in the group." } }, "required": [ "coin", "longUsd", "shortUsd", "count" ] }, "description": "The 50 coins with the most USD." }, "largest": { "anyOf": [ { "$ref": "#/components/schemas/Liquidation" }, { "type": "null" } ], "description": "Largest single liquidation in the window (of a venue the API serves), null when there is none." }, "series": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time", "description": "Start of the UTC hour." }, "longUsd": { "type": [ "number", "null" ], "description": "Long; null = hour not covered (USD)." }, "shortUsd": { "type": [ "number", "null" ], "description": "Short; null = hour not covered (USD)." } }, "required": [ "t", "longUsd", "shortUsd" ] }, "description": "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." }, "coveredSince": { "type": [ "string", "null" ], "format": "date-time", "description": "From when every venue stream was collected (totals before that are incomplete)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest stored liquidation in the window." }, "hourlySumsBefore": { "type": [ "string", "null" ], "format": "date-time", "description": "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": { "type": "integer", "description": "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." } }, "required": [ "hours", "totalUsd", "longUsd", "shortUsd", "count", "byVenue", "byCoin", "largest", "series", "coveredSince", "updatedAt" ] }, "LongShortRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "hl": { "type": [ "object", "null" ], "properties": { "longUsd": { "type": "number", "description": "Tracked long notional (USD)." }, "shortUsd": { "type": "number", "description": "Tracked short notional (USD)." }, "longAccounts": { "type": "integer", "description": "Tracked wallets with a long position." }, "shortAccounts": { "type": "integer", "description": "Tracked wallets with a short position." }, "ratio": { "type": [ "number", "null" ], "description": "longUsd / shortUsd." } }, "required": [ "longUsd", "shortUsd", "longAccounts", "shortAccounts", "ratio" ], "description": "Hyperliquid from the tracked positions; null when no tracked position exists." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." }, "binance": { "type": [ "object", "null" ], "properties": { "accountRatio": { "type": [ "number", "null" ], "description": "Long / short accounts." }, "topAccountRatio": { "type": [ "number", "null" ], "description": "Top traders, accounts." }, "topPositionRatio": { "type": [ "number", "null" ], "description": "Top traders, positions." } }, "required": [ "accountRatio", "topAccountRatio", "topPositionRatio" ], "description": "Binance published long/short ratios (only while Binance is switched on and licensed for the API)." }, "bybit": { "type": [ "object", "null" ], "properties": { "accountRatio": { "type": [ "number", "null" ], "description": "Long / short accounts." } }, "required": [ "accountRatio" ], "description": "Bybit published long/short ratio (only while Bybit is switched on and licensed for the API)." }, "okx": { "type": [ "object", "null" ], "properties": { "accountRatio": { "type": [ "number", "null" ], "description": "Long / short accounts." } }, "required": [ "accountRatio" ], "description": "OKX published long/short ratio (only while OKX is switched on and licensed for the API)." } }, "required": [ "coin", "hl", "updatedAt" ] }, "WhaleRow": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^(0x[0-9a-f]{40}|[0-9]{1,20})$", "description": "Hyperliquid address (lowercase), or with venue \"lighter\" the Lighter account index." }, "label": { "type": [ "string", "null" ], "description": "Public label, else the self-chosen leaderboard name." }, "labelSource": { "type": [ "string", "null" ], "description": "Source URL of a public label, or \"hyperliquid-leaderboard\" (unverified)." }, "accountValue": { "type": [ "number", "null" ], "description": "Account value (USD)." }, "pnlMonth": { "type": [ "number", "null" ], "description": "30-day PnL (USD)." }, "pnlAllTime": { "type": [ "number", "null" ], "description": "All-time PnL (USD)." }, "positionsUsd": { "type": "number", "description": "Open notional (USD)." }, "positionCount": { "type": "integer", "description": "Number of open positions." }, "top": { "type": [ "object", "null" ], "description": "Largest position.", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "side": { "$ref": "#/components/schemas/Side" }, "usd": { "type": "number", "description": "Notional (USD)." }, "leverage": { "type": [ "number", "null" ], "description": "Leverage of the position (notional / margin)." }, "liqPx": { "type": [ "number", "null" ], "description": "Liquidation price of the position." }, "liqDistance": { "type": [ "number", "null" ], "description": "Signed fraction." } }, "required": [ "coin", "side", "usd", "leverage", "liqPx", "liqDistance" ] }, "liquidations": { "type": [ "integer", "null" ], "description": "Fill-confirmed liquidations in the stored history (null for Lighter accounts: liquidations are not attributed per account)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." }, "venue": { "type": "string", "enum": [ "hyperliquid", "lighter" ], "description": "Venue of the position (present for Lighter rows; absent = Hyperliquid)." }, "l1Address": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{40}$", "description": "Lighter: the account’s Ethereum address." } }, "required": [ "address", "label", "labelSource", "accountValue", "pnlMonth", "pnlAllTime", "positionsUsd", "positionCount", "top", "liquidations", "updatedAt" ] }, "StopCoverage": { "type": "object", "description": "Which wallets the stop map covers (the largest tracked wallets in the rotation, main dex only).", "properties": { "walletsFresh": { "type": "integer", "description": "Wallets whose open orders were read within the freshness limit (default 3 h)." }, "walletsWithOrders": { "type": "integer", "description": "Of those, wallets with at least one order (on this coin, when a coin is given)." }, "oldestFetch": { "type": [ "string", "null" ], "format": "date-time", "description": "Oldest open-orders read among the covered wallets." }, "newestFetch": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest open-orders read among the covered wallets." } }, "required": [ "walletsFresh", "walletsWithOrders", "oldestFetch", "newestFetch" ] }, "StopBucket": { "type": "object", "properties": { "px": { "type": "number", "description": "Lower edge of the price bucket." }, "top": { "type": "number", "description": "Upper edge." }, "stopSellUsd": { "type": "number", "description": "Sell stop orders (trigger when the price falls to them) (USD)." }, "stopBuyUsd": { "type": "number", "description": "Buy stop orders (trigger when the price rises to them) (USD)." }, "tpSellUsd": { "type": "number", "description": "Sell take-profit orders (USD)." }, "tpBuyUsd": { "type": "number", "description": "Buy take-profit orders (USD)." }, "orders": { "type": "integer", "description": "Number of orders." }, "wallets": { "type": "integer", "description": "Number of distinct wallets." } }, "required": [ "px", "top", "stopSellUsd", "stopBuyUsd", "tpSellUsd", "tpBuyUsd", "orders", "wallets" ] }, "StopMap": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark." }, "bucketSize": { "type": "number", "description": "Bucket width (same rule as the liquidation map)." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/StopBucket" }, "description": "Buckets within ±30 % of the mark, ascending." }, "totals": { "type": "object", "properties": { "stopSellUsd": { "type": "number", "description": "Sell stops (USD)." }, "stopBuyUsd": { "type": "number", "description": "Buy stops (USD)." }, "tpSellUsd": { "type": "number", "description": "Sell TPs (USD)." }, "tpBuyUsd": { "type": "number", "description": "Buy TPs (USD)." }, "limitBuyUsd": { "type": "number", "description": "Resting buy limits (USD)." }, "limitSellUsd": { "type": "number", "description": "Resting sell limits (USD)." }, "orders": { "type": "integer", "description": "Number of orders." }, "wallets": { "type": "integer", "description": "Number of distinct wallets." } }, "required": [ "stopSellUsd", "stopBuyUsd", "tpSellUsd", "tpBuyUsd", "limitBuyUsd", "limitSellUsd", "orders", "wallets" ], "description": "Sums over the rows of this object." }, "coverage": { "$ref": "#/components/schemas/StopCoverage" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest order read." } }, "required": [ "coin", "mark", "bucketSize", "buckets", "totals", "coverage", "updatedAt" ] }, "StopOverlayItem": { "type": "object", "description": "Heatmap layer item: side long = sell orders (long exits, drawn like long liquidations), short = buy orders.", "properties": { "price": { "type": "number", "description": "Bucket middle." }, "label": { "type": "string", "description": "Plain-language label." }, "side": { "$ref": "#/components/schemas/Side" }, "usd": { "type": "number", "description": "Orders in the bucket (USD)." } }, "required": [ "price", "label", "side", "usd" ] }, "StopTableRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark price." }, "stopSellUsd": { "type": "number", "description": "Sell stops (USD)." }, "stopBuyUsd": { "type": "number", "description": "Buy stops (USD)." }, "tpSellUsd": { "type": "number", "description": "Sell TPs (USD)." }, "tpBuyUsd": { "type": "number", "description": "Buy TPs (USD)." }, "orders": { "type": "integer", "description": "Number of orders." }, "wallets": { "type": "integer", "description": "Number of distinct wallets." }, "nearestBelow": { "type": [ "object", "null" ], "description": "Largest sell-stop bucket below the mark.", "properties": { "px": { "type": "number", "description": "Price (lower edge of a price bucket where the object is a bucket)." }, "usd": { "type": "number", "description": "Sell stops (USD)." }, "distance": { "type": "number", "description": "Fraction of the mark." } }, "required": [ "px", "usd", "distance" ] }, "nearestAbove": { "type": [ "object", "null" ], "description": "Largest buy-stop bucket above the mark.", "properties": { "px": { "type": "number", "description": "Price (lower edge of a price bucket where the object is a bucket)." }, "usd": { "type": "number", "description": "Buy stops (USD)." }, "distance": { "type": "number", "description": "Fraction of the mark." } }, "required": [ "px", "usd", "distance" ] } }, "required": [ "coin", "mark", "stopSellUsd", "stopBuyUsd", "tpSellUsd", "tpBuyUsd", "orders", "wallets", "nearestBelow", "nearestAbove" ] }, "WhaleStops": { "type": "object", "properties": { "coin": { "type": [ "string", "null" ], "description": "The coin of `map` / `overlay`; null = per-coin table." }, "map": { "anyOf": [ { "$ref": "#/components/schemas/StopMap" }, { "type": "null" } ], "description": "Stop / take-profit buckets of the coin (with ?coin=), else null." }, "overlay": { "type": "array", "items": { "$ref": "#/components/schemas/StopOverlayItem" }, "description": "Items to draw on top of the liquidation heatmap." }, "table": { "type": "array", "items": { "$ref": "#/components/schemas/StopTableRow" }, "description": "Per-coin table (without coin), largest first." }, "limited": { "type": "boolean", "description": "Rows were left out by the plan (free key: BTC, ETH, HYPE)." }, "coverage": { "$ref": "#/components/schemas/StopCoverage" }, "method": { "type": "string", "description": "How the figures are computed, in plain words." } }, "required": [ "coin", "map", "overlay", "table", "limited", "coverage", "method" ] }, "TraderRow": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Rank in the current sort." }, "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "label": { "type": [ "string", "null" ], "description": "Public label, else the self-chosen leaderboard name (unverified)." }, "labelSource": { "type": [ "string", "null" ], "description": "Source URL of a public label, or \"hyperliquid-leaderboard\"." }, "accountValue": { "type": [ "number", "null" ], "description": "Account value (USD)." }, "pnl": { "type": "object", "description": "Hyperliquid leaderboard PnL per window (USD): the account with its sub-accounts and spot balances, deposits / withdrawals not counted.", "properties": { "day": { "type": [ "number", "null" ], "description": "Last 24 hours." }, "week": { "type": [ "number", "null" ], "description": "Last 7 days." }, "month": { "type": [ "number", "null" ], "description": "Last 30 days." }, "allTime": { "type": [ "number", "null" ], "description": "All time." } }, "required": [ "day", "week", "month", "allTime" ] }, "roi": { "type": "object", "description": "Hyperliquid leaderboard ROI per window (fraction).", "properties": { "day": { "type": [ "number", "null" ], "description": "Last 24 hours." }, "week": { "type": [ "number", "null" ], "description": "Last 7 days." }, "month": { "type": [ "number", "null" ], "description": "Last 30 days." }, "allTime": { "type": [ "number", "null" ], "description": "All time." } }, "required": [ "day", "week", "month", "allTime" ] }, "vlm": { "type": "object", "description": "Traded volume per window (USD).", "properties": { "day": { "type": [ "number", "null" ], "description": "Last 24 hours." }, "week": { "type": [ "number", "null" ], "description": "Last 7 days." }, "month": { "type": [ "number", "null" ], "description": "Last 30 days." }, "allTime": { "type": [ "number", "null" ], "description": "All time." } }, "required": [ "day", "week", "month", "allTime" ] }, "observed": { "type": "object", "description": "From the opens and closes our position polls saw (empty for free keys).", "properties": { "closes": { "type": "integer", "description": "Position closes we observed." }, "wins": { "type": "integer", "description": "Of those, closes with a profit." }, "winRate": { "type": [ "number", "null" ], "description": "wins / closes, from 10 closes on." }, "avgHoldMin": { "type": [ "number", "null" ], "description": "Average holding time in minutes (open → close pairs), from 3 pairs on." }, "holds": { "type": "integer", "description": "Open→close pairs seen." }, "since": { "type": [ "string", "null" ], "format": "date-time", "description": "First observed event." } }, "required": [ "closes", "wins", "winRate", "avgHoldMin", "holds", "since" ] }, "risk": { "type": [ "object", "null" ], "properties": { "maxDrawdownUsd": { "type": [ "number", "null" ], "description": "Largest peak-to-trough fall of the account value in USD." }, "maxDrawdownPct": { "type": [ "number", "null" ], "description": "Fraction of the account value at the peak (0.17 = 17 %). Deprecated: use maxDrawdown (same value).", "deprecated": true }, "maxDrawdown": { "type": [ "number", "null" ], "description": "Largest fall as a fraction of the account value at the peak (0.17 = 17 %)." }, "sharpe": { "type": [ "number", "null" ], "description": "Annualised mean / standard deviation of the 30-day portfolio returns, no risk-free rate." }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the portfolio history was read." } }, "required": [ "maxDrawdownUsd", "maxDrawdownPct", "maxDrawdown", "sharpe", "fetchedAt" ], "description": "Risk figures from the Hyperliquid portfolio history (top traders), else null." }, "book": { "type": [ "object", "null" ], "properties": { "positionsUsd": { "type": "number", "description": "Open tracked notional (USD)." }, "positions": { "type": "integer", "description": "Number of positions." }, "longShare": { "type": [ "number", "null" ], "description": "Long notional / total." }, "avgLeverage": { "type": [ "number", "null" ], "description": "Notional-weighted." } }, "required": [ "positionsUsd", "positions", "longShare", "avgLeverage" ], "description": "Open tracked positions of the wallet, else null." }, "styles": { "type": "array", "items": { "type": "string", "enum": [ "scalper", "swing", "position", "high turnover", "high leverage", "mostly long", "mostly short" ] }, "description": "Style tags from observed behaviour (scalper, swing, position, high_turnover, high_leverage, mostly_long, mostly_short)." }, "sizeCohort": { "type": [ "string", "null" ], "enum": [ "shrimp", "fish", "dolphin", "shark", "whale", null ], "description": "Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M." }, "pnlCohort": { "type": [ "string", "null" ], "enum": [ "top", "profitable", "flat", "losing", "rekt", null ], "description": "PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Leaderboard row time." } }, "required": [ "rank", "address", "label", "labelSource", "accountValue", "pnl", "roi", "vlm", "observed", "risk", "book", "styles", "sizeCohort", "pnlCohort", "updatedAt" ] }, "Traders": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/TraderRow" }, "description": "The rows of this view." }, "total": { "type": "integer", "description": "Rows matching the filters." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest leaderboard run." }, "riskUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest portfolio read (drawdown, Sharpe)." }, "full": { "type": "boolean", "description": "false = free key: the top 100 of the chosen sort, every column, no search, style filter or paging." }, "rules": { "type": "string", "description": "Who the chosen sort lists." }, "method": { "type": "string", "description": "How the figures are computed, in plain words." } }, "required": [ "rows", "total", "updatedAt", "riskUpdatedAt", "full", "rules", "method" ] }, "CohortRow": { "type": "object", "properties": { "dim": { "type": "string", "enum": [ "size", "pnl" ], "description": "Cohort dimension: size (account value) or pnl (all-time PnL)." }, "cohort": { "type": "string", "description": "Cohort key within its dimension." }, "label": { "type": "string", "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "longUsd": { "type": "number", "description": "Long notional (USD)." }, "shortUsd": { "type": "number", "description": "Short notional (USD)." }, "longWallets": { "type": "integer", "description": "Wallets on the long side." }, "shortWallets": { "type": "integer", "description": "Wallets on the short side." }, "longShare": { "type": [ "number", "null" ], "description": "longUsd / (longUsd + shortUsd)." }, "change": { "type": "object", "description": "Change of longShare against the snapshot that long ago (fraction points); windows beyond the plan history are missing.", "properties": { "15m": { "type": [ "number", "null" ], "description": "Change over 15 minutes." }, "1h": { "type": [ "number", "null" ], "description": "Change over 1 hour." }, "4h": { "type": [ "number", "null" ], "description": "Change over 4 hours." }, "24h": { "type": [ "number", "null" ], "description": "Change over 24 hours." }, "3d": { "type": [ "number", "null" ], "description": "Change over 3 days." }, "7d": { "type": [ "number", "null" ], "description": "Change over 7 days." } }, "required": [] } }, "required": [ "dim", "cohort", "label", "longUsd", "shortUsd", "longWallets", "shortWallets", "longShare", "change" ] }, "CohortChange": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "kind": { "type": "string", "enum": [ "open", "close", "increase", "decrease", "flip", "liquidated" ], "description": "Kind of the item (enum of this field)." }, "side": { "anyOf": [ { "$ref": "#/components/schemas/Side" }, { "type": "null" } ], "description": "Position side (long / short); for trades and orders the side named in the description." }, "usdDelta": { "type": "number", "description": "Signed USD change." }, "price": { "type": [ "number", "null" ], "description": "Price in the quote currency of the venue (USD / USDT / USDC)." }, "sizeCohort": { "type": [ "string", "null" ], "enum": [ "shrimp", "fish", "dolphin", "shark", "whale", null ], "description": "Size cohort by account value: shrimp < $10K, fish, dolphin, shark, whale ≥ $10M." }, "pnlCohort": { "type": [ "string", "null" ], "enum": [ "top", "profitable", "flat", "losing", "rekt", null ], "description": "PnL cohort by all-time PnL: top ≥ +$1M, profitable, flat, losing, rekt ≤ −$1M." } }, "required": [ "id", "ts", "address", "coin", "kind", "side", "usdDelta", "price", "sizeCohort", "pnlCohort" ] }, "Cohorts": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin or ALL." }, "snapshotAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest 5-min snapshot." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/CohortRow" }, "description": "The rows of this view." }, "since": { "type": [ "string", "null" ], "format": "date-time", "description": "Oldest snapshot." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/CohortChange" }, "description": "Recent position changes ≥ $50k with cohorts (delayed for free keys)." }, "netFlow1h": { "type": "array", "items": { "type": "object", "properties": { "dim": { "type": "string", "enum": [ "size", "pnl" ], "description": "Cohort dimension: size (account value) or pnl (all-time PnL)." }, "cohort": { "type": "string", "description": "Cohort key within its dimension." }, "longUsd": { "type": "number", "description": "Long notional in USD." }, "shortUsd": { "type": "number", "description": "Short notional in USD." }, "events": { "type": "integer", "description": "Events of this view (newest first) or their count." } }, "required": [ "dim", "cohort", "longUsd", "shortUsd", "events" ] }, "description": "Net notional added per cohort and side in the last hour." }, "maxMinutes": { "type": "integer", "description": "Longest trend window of the plan." } }, "required": [ "coin", "snapshotAt", "rows", "since", "changes", "netFlow1h", "maxMinutes" ] }, "SmartMoneyEvent": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "coin": { "type": [ "string", "null" ], "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "severity": { "type": "integer", "description": "1 info, 2 notable, 3 major, 4 critical." }, "title": { "type": "string", "description": "One-line factual title in our own words." }, "side": { "anyOf": [ { "$ref": "#/components/schemas/Side" }, { "type": "null" } ], "description": "Position side (long / short); for trades and orders the side named in the description." }, "count": { "type": [ "integer", "null" ], "description": "Wallets that converged." }, "usd": { "type": [ "number", "null" ], "description": "Notional in USD." }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "usd": { "type": "number", "description": "Notional in USD." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "lists": { "type": "array", "items": { "type": "string", "enum": [ "allTime", "month", "roi" ] }, "description": "Smart-money lists the wallet was on at the time of the event (events from 2026-11-03 on)." } }, "required": [ "address", "usd", "ts" ] }, "description": "Number of distinct wallets." } }, "required": [ "id", "ts", "coin", "severity", "title", "side", "count", "usd", "wallets" ] }, "SmartMoney": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/SmartMoneyEvent" }, "description": "Events of this view (newest first) or their count." }, "positioning": { "type": "array", "items": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "longUsd": { "type": "number", "description": "Long notional in USD." }, "shortUsd": { "type": "number", "description": "Short notional in USD." }, "longWallets": { "type": "integer", "description": "Wallets on the long side." }, "shortWallets": { "type": "integer", "description": "Wallets on the short side." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest poll of these positions." } }, "required": [ "coin", "longUsd", "shortUsd", "longWallets", "shortWallets" ] }, "description": "Open tracked positions of the smart wallets." }, "wallets": { "type": "integer", "description": "Smart wallets after the filters." }, "candidates": { "type": "integer", "description": "Leaderboard wallets checked from the top of the lists (smart wallets plus excluded ones)." }, "excluded": { "type": "object", "description": "Excluded wallets per reason.", "properties": { "vault": { "type": "integer", "description": "Hyperliquid vaults (including HLP)." }, "many_positions": { "type": "integer", "deprecated": true, "description": "Deprecated: use manyPositions (same value)." }, "resting_orders": { "type": "integer", "deprecated": true, "description": "Deprecated: use restingOrders (same value)." }, "high_fills": { "type": "integer", "deprecated": true, "description": "Deprecated: use highFills (same value)." }, "turnover": { "type": "integer", "description": "Wallets whose 30-day volume is a large multiple of the account value (market making / HFT)." }, "hedged": { "type": "integer", "description": "Delta-neutral books (long and short notional nearly equal)." }, "manyPositions": { "type": "integer", "description": "Wallets with many open positions (market makers, multi-asset algos)." }, "restingOrders": { "type": "integer", "description": "Wallets with many resting limit orders (a quoted book)." }, "highFills": { "type": "integer", "description": "Wallets with very many fills per hour (market making)." }, "notTrading": { "type": "integer", "description": "All-time PnL above 20 × the all-time volume (token holdings, airdrops)." } }, "required": [] }, "delayMinutes": { "type": "integer", "description": "Minutes the events are delayed for the caller’s plan (0 = real time)." }, "settings": { "type": "object", "properties": { "k": { "type": "integer", "description": "Wallets needed for a convergence event." }, "windowMin": { "type": "number", "description": "Window of a convergence in minutes." }, "minUsd": { "type": "number", "description": "Minimum position change per wallet in USD." }, "top": { "type": "integer", "description": "All-time PnL list size." }, "monthTop": { "type": "integer", "description": "30-day PnL list size (0 = off)." }, "monthMinAccountUsd": { "type": "number", "description": "Lowest account value of the 30-day list (USD)." }, "monthMinRoi": { "type": "number", "description": "Lowest 30-day ROI as a fraction (0.05 = 5 %)." }, "roiTop": { "type": "integer", "description": "All-time ROI list size (0 = off)." }, "roiMinAccountUsd": { "type": "number", "description": "Lowest account value of the ROI list (USD)." }, "roiMinPnlUsd": { "type": "number", "description": "Lowest all-time PnL of the ROI list (USD)." }, "maxWallets": { "type": "integer", "description": "Most smart wallets in all." } }, "required": [ "k", "windowMin", "minUsd", "top" ], "description": "Detector settings in force." }, "method": { "type": "string", "description": "How the figures are computed, in plain words." }, "lists": { "type": "object", "description": "Wallets per list after the filters (a wallet on two lists counts on both).", "properties": { "allTime": { "$ref": "#/components/schemas/SmartMoneyList" }, "month": { "$ref": "#/components/schemas/SmartMoneyList" }, "roi": { "$ref": "#/components/schemas/SmartMoneyList" } }, "required": [ "allTime", "month", "roi" ] }, "leaderboardAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest Hyperliquid leaderboard run the set is built from." } }, "required": [ "events", "positioning", "wallets", "candidates", "excluded", "delayMinutes", "settings", "method" ] }, "SmartMoneyList": { "type": "object", "properties": { "wallets": { "type": "integer", "description": "Number of distinct wallets." }, "floor": { "type": [ "number", "null" ], "description": "Ranking value of the last wallet on the list: all-time or 30-day PnL in USD, all-time ROI as a fraction." } }, "required": [ "wallets", "floor" ] }, "ApiStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "State of the item (enum of this field)." }, "apiVersion": { "type": "string", "description": "Semantic version of the v1 contract." }, "time": { "type": "string", "format": "date-time", "description": "Server time." }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable feed id, e.g. hl-markets, binance-liq." }, "label": { "type": "string", "description": "Plain-English name as on /status, e.g. \"Binance liquidations\"." }, "state": { "type": "string", "enum": [ "ok", "warn", "bad", "off" ], "description": "ok = operational, warn = delayed, bad = down, off = set up but no data delivered yet (does not count against status)." }, "lastUpdate": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest successful update of the feed." }, "ageSec": { "type": [ "integer", "null" ], "description": "Seconds since the last update." } }, "required": [ "id", "label", "state", "lastUpdate", "ageSec" ] }, "description": "Data feeds as on /status (API 1.13.0); status follows them." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Data source id or name of this item." }, "health": { "type": "string", "enum": [ "ok", "warn", "bad" ], "description": "ok, warn (delayed) or bad (down)." }, "lastRun": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful run (ISO 8601 UTC)." }, "ageSec": { "type": [ "integer", "null" ], "description": "Seconds since the last update." } }, "required": [ "source", "health", "lastRun", "ageSec" ] }, "description": "Per data source: health and last run." }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "job": { "type": "string", "description": "Collector job id (internal name; see /status for the plain-English feeds)." }, "label": { "type": "string", "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "source": { "type": "string", "description": "Data source id or name of this item." }, "lastRun": { "type": "string", "format": "date-time", "description": "Last successful run (ISO 8601 UTC)." }, "ageSec": { "type": "integer", "description": "Seconds since the last update." }, "expectedIntervalSec": { "type": "integer", "description": "How often the job is expected to run, in seconds." }, "health": { "type": "string", "enum": [ "ok", "warn", "bad" ], "description": "ok ≤ 3× the expected interval, warn ≤ 10×, bad beyond." } }, "required": [ "job", "label", "source", "lastRun", "ageSec", "expectedIntervalSec", "health" ] }, "description": "Deprecated since 1.13.0, use feeds: the collector jobs behind the data feeds (internal maintenance jobs are not listed)." }, "uptime": { "type": "object", "description": "Measured availability: share of 5-minute slots in which the probe of this endpoint answered (api), the core data jobs ran (data), or both (sla). Slots without a measurement count as unavailable.", "properties": { "since": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of monitoring; figures cover only the time since." }, "slaTarget": { "type": "number", "description": "Monthly availability target of the SLA for paid plans (fraction, 0.995 = 99.5 %)." }, "api": { "$ref": "#/components/schemas/AvailabilityFigures" }, "data": { "$ref": "#/components/schemas/AvailabilityFigures" }, "sla": { "$ref": "#/components/schemas/AvailabilityFigures" }, "currentMonth": { "type": "object", "properties": { "month": { "type": "string", "description": "UTC month, YYYY-MM." }, "availability": { "type": [ "number", "null" ], "description": "SLA availability so far (fraction)." }, "breached": { "type": "boolean", "description": "Below the SLA target so far." } }, "required": [ "month", "availability", "breached" ], "description": "Availability of the current UTC month." } }, "required": [ "since", "slaTarget", "api", "data", "sla", "currentMonth" ] }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "title": { "type": "string", "description": "One-line factual title in our own words." }, "impact": { "type": "string", "enum": [ "maintenance", "minor", "major" ], "description": "maintenance, minor or major." }, "components": { "type": "array", "items": { "type": "string" }, "description": "Affected parts of the service." }, "startedAt": { "type": "string", "format": "date-time", "description": "Start of the incident (ISO 8601 UTC)." }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the incident (ISO 8601 UTC); null while open." } }, "required": [ "id", "title", "impact", "components", "startedAt", "resolvedAt" ] }, "description": "Open incidents and those of the last 7 days (as posted on /status)." } }, "required": [ "status", "apiVersion", "time", "feeds", "sources", "jobs", "uptime", "incidents" ] }, "AvailabilityFigures": { "type": "object", "properties": { "last24h": { "type": [ "number", "null" ], "description": "Fraction of available 5-minute slots, last 24 h." }, "last7d": { "type": [ "number", "null" ], "description": "Last 7 days." }, "last30d": { "type": [ "number", "null" ], "description": "Last 30 days." }, "last90d": { "type": [ "number", "null" ], "description": "Last 90 days." } }, "required": [ "last24h", "last7d", "last30d", "last90d" ] }, "FlowVenue": { "type": "string", "enum": [ "hyperliquid", "binance", "bybit" ], "description": "Venue of the order-flow data." }, "BookLevel": { "type": "object", "properties": { "px": { "type": "number", "description": "Lower edge of the price bucket." }, "usd": { "type": "number", "description": "Resting liquidity in the bucket (USD)." } }, "required": [ "px", "usd" ] }, "BookVenue": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/FlowVenue" }, "layer": { "type": "string", "enum": [ "fine", "coarse", "book" ], "description": "fine / coarse = Hyperliquid l2Book with 3 / 2 significant figures (the coarse layer leaves out the fine range); book = local CEX order book." }, "step": { "type": "number", "description": "Bucket size (price)." }, "mid": { "type": "number", "description": "Mid price (latest trade of the venue, else the book)." }, "ts": { "type": "string", "format": "date-time", "description": "Snapshot time." }, "lo": { "type": "number", "description": "Lowest price covered." }, "hi": { "type": "number", "description": "Highest price covered." }, "bids": { "type": "array", "items": { "$ref": "#/components/schemas/BookLevel" }, "description": "Bid buckets, from the price downwards." }, "asks": { "type": "array", "items": { "$ref": "#/components/schemas/BookLevel" }, "description": "Ask buckets, from the price upwards." }, "bidUsd": { "type": "number", "description": "All bids of the snapshot (USD)." }, "askUsd": { "type": "number", "description": "All asks of the snapshot (USD)." }, "bid1pct": { "type": "number", "description": "Bids within 1 % of the mid (USD)." }, "ask1pct": { "type": "number", "description": "Asks within 1 % of the mid (USD)." } }, "required": [ "venue", "layer", "step", "mid", "ts", "lo", "hi", "bids", "asks", "bidUsd", "askUsd", "bid1pct", "ask1pct" ] }, "Wall": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "venue": { "$ref": "#/components/schemas/FlowVenue" }, "layer": { "type": "string", "enum": [ "fine", "coarse", "book" ], "description": "Storage layer the data was read from (enum of this field)." }, "side": { "type": "string", "enum": [ "bid", "ask" ], "description": "Position side (long / short); for trades and orders the side named in the description." }, "px": { "type": "number", "description": "Lower edge of the bucket." }, "top": { "type": "number", "description": "Upper edge of the bucket." }, "usd": { "type": "number", "description": "Size at the last sighting (USD)." }, "maxUsd": { "type": "number", "description": "Largest size seen (USD)." }, "firstUsd": { "type": "number", "description": "Size when first seen (USD)." }, "firstSeen": { "type": "string", "format": "date-time", "description": "First time this item was observed (ISO 8601 UTC)." }, "lastSeen": { "type": "string", "format": "date-time", "description": "Last time this item was observed (ISO 8601 UTC)." }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended (ISO 8601 UTC); null while active." }, "status": { "type": "string", "enum": [ "active", "pulled", "filled", "gone" ], "description": "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." }, "distancePct": { "type": "number", "description": "Distance from the price when first seen (fraction, 0.01 = 1 %). Deprecated: use distance (same value).", "deprecated": true }, "minDistancePct": { "type": "number", "description": "Closest distance to the price (fraction). Deprecated: use minDistance (same value).", "deprecated": true }, "distance": { "type": "number", "description": "Distance from the price when first seen, fraction (0.01 = 1 %)." }, "minDistance": { "type": "number", "description": "Closest distance to the price, fraction." }, "touchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "First time the price traded into the bucket." }, "lifetimeSec": { "type": "integer", "description": "Seconds from first sighting to the end (or the last sighting)." }, "history": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "[secondsSinceFirstSeen, usd] at size changes of 20 % or more." } }, "required": [ "id", "venue", "layer", "side", "px", "top", "usd", "maxUsd", "firstUsd", "firstSeen", "lastSeen", "endedAt", "status", "distancePct", "minDistancePct", "distance", "minDistance", "touchedAt", "lifetimeSec", "history" ] }, "BookHeatmap": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "venues": { "type": "array", "items": { "$ref": "#/components/schemas/FlowVenue" }, "description": "Venues covered by this view." }, "times": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Column start times, oldest to newest." }, "colMs": { "type": "integer", "description": "Column width in milliseconds." }, "prices": { "type": "array", "items": { "type": "number" }, "description": "Lower edge of each price row, ascending." }, "rowStep": { "type": "number", "description": "Price step between rows." }, "bid": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "bid[timeIndex][priceIndex]: resting bids in USD (rounded to $1,000)." }, "ask": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "Same shape, resting asks." }, "mid": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Mid price per column (null without a snapshot)." }, "candles": { "type": "object", "description": "OHLC of taker trades per column.", "properties": { "o": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Open price per column (null = no trade)." }, "h": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "High price per column." }, "l": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Low price per column." }, "c": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Close price per column." }, "venue": { "anyOf": [ { "$ref": "#/components/schemas/FlowVenue" }, { "type": "null" } ], "description": "Trading venue the row comes from." } }, "required": [ "o", "h", "l", "c", "venue" ] }, "maxUsd": { "type": "number", "description": "Largest cell (USD)." }, "coarse": { "type": "array", "items": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/FlowVenue" }, "step": { "type": "number", "description": "Price step of the buckets." } }, "required": [ "venue", "step" ] }, "description": "Coarse layers whose buckets can be wider than a row (each drawn whole in the row of its centre)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "coin", "venues", "times", "colMs", "prices", "rowStep", "bid", "ask", "mid", "candles", "maxUsd", "coarse", "updatedAt" ] }, "Orderbook": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mid": { "type": [ "number", "null" ], "description": "Mid price between the best bid and ask." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest snapshot." }, "venues": { "type": "array", "items": { "$ref": "#/components/schemas/BookVenue" }, "description": "Venues covered by this view." }, "depth": { "type": "array", "items": { "type": "object", "properties": { "pct": { "type": "number", "description": "Band around the mid (fraction, 0.01 = 1 %). Deprecated: use band (same value).", "deprecated": true }, "band": { "type": "number", "description": "Band around the mid, fraction (0.01 = 1 %)." }, "bidUsd": { "type": "number", "description": "Bids in the band (USD)." }, "askUsd": { "type": "number", "description": "Asks in the band (USD)." }, "imbalance": { "type": [ "number", "null" ], "description": "(bids - asks) / (bids + asks)." } }, "required": [ "pct", "band", "bidUsd", "askUsd", "imbalance" ] }, "description": "Resting liquidity within bands around the mid (1 / 2 / 5 %)." }, "walls": { "type": "array", "items": { "$ref": "#/components/schemas/Wall" }, "description": "Active walls and walls that ended in the last hour, active first, largest first." }, "heatmap": { "anyOf": [ { "$ref": "#/components/schemas/BookHeatmap" }, { "type": "null" } ], "description": "Order book heatmap over time (with ?hours=), else null." } }, "required": [ "coin", "mid", "updatedAt", "venues", "depth", "walls", "heatmap" ] }, "FlowPoint": { "type": "object", "description": "One bar of taker flow. Bars in which no data was collected (collector offline) are left out, so consecutive points can be more than one step apart; a gap is no data, not zero flow. cvd carries on across a gap.", "properties": { "t": { "type": "string", "format": "date-time", "description": "Bar start." }, "buyUsd": { "type": "number", "description": "Taker buys (USD)." }, "sellUsd": { "type": "number", "description": "Taker sells (USD)." }, "delta": { "type": "number", "description": "Buys minus sells (USD)." }, "cvd": { "type": "number", "description": "Cumulative delta since the window start (USD)." } }, "required": [ "t", "buyUsd", "sellUsd", "delta", "cvd" ] }, "VolumeProfile": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "from": { "type": "string", "format": "date-time", "description": "Start of the window (ISO 8601 UTC) or the sending side of a movement." }, "to": { "type": "string", "format": "date-time", "description": "End of the window (ISO 8601 UTC) or the receiving side of a movement." }, "step": { "type": "number", "description": "Price step of the levels." }, "levels": { "type": "array", "items": { "type": "object", "properties": { "px": { "type": "number", "description": "Lower edge." }, "buyUsd": { "type": "number", "description": "Taker buys (USD)." }, "sellUsd": { "type": "number", "description": "Taker sells (USD)." } }, "required": [ "px", "buyUsd", "sellUsd" ] }, "description": "Price levels, ascending." }, "totalUsd": { "type": "number", "description": "Volume (USD)." }, "poc": { "type": [ "number", "null" ], "description": "Point of control (level with the most volume)." }, "valueArea": { "type": [ "object", "null" ], "description": "Smallest range around the POC with 70 % of the volume.", "properties": { "lo": { "type": "number", "description": "Lower edge." }, "hi": { "type": "number", "description": "Upper edge." } }, "required": [ "lo", "hi" ] }, "venues": { "type": "array", "items": { "$ref": "#/components/schemas/FlowVenue" }, "description": "Venues covered by this view." } }, "required": [ "coin", "from", "to", "step", "levels", "totalUsd", "poc", "valueArea", "venues" ] }, "Flow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "stepMinutes": { "type": "integer", "description": "Bar / column width in minutes." }, "from": { "type": "string", "format": "date-time", "description": "Start of the window (ISO 8601 UTC) or the sending side of a movement." }, "to": { "type": "string", "format": "date-time", "description": "End of the window (ISO 8601 UTC) or the receiving side of a movement." }, "total": { "type": "array", "items": { "$ref": "#/components/schemas/FlowPoint" }, "description": "Perpetual venues summed. Can have gaps: bars without collected data are left out (never sent as 0)." }, "byVenue": { "type": "array", "items": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/FlowVenue" }, "market": { "type": "string", "enum": [ "perp", "spot" ], "description": "perp = perpetual futures, spot = spot market." }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/FlowPoint" }, "description": "Bars of the series, oldest first." }, "buyUsd": { "type": "number", "description": "Taker buys (USD)." }, "sellUsd": { "type": "number", "description": "Taker sells (USD)." } }, "required": [ "venue", "market", "points", "buyUsd", "sellUsd" ] }, "description": "Split per venue." }, "bySize": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "lt10k", "10k_100k", "100k_1m", "gt1m" ], "description": "Print size: lt10k, 10k_100k, 100k_1m, gt1m." }, "label": { "type": "string", "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "points": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time", "description": "Start of the bucket or bar (ISO 8601 UTC)." }, "delta": { "type": "number", "description": "Buys minus sells (USD)." }, "cvd": { "type": "number", "description": "Cumulative delta (USD)." } }, "required": [ "t", "delta", "cvd" ] }, "description": "Bars of the series, oldest first. Can have gaps like total." }, "buyUsd": { "type": "number", "description": "Taker buys (USD)." }, "sellUsd": { "type": "number", "description": "Taker sells (USD)." } }, "required": [ "bucket", "label", "points", "buyUsd", "sellUsd" ] }, "description": "Perpetual venues summed, per print size." }, "whales": { "type": [ "object", "null" ], "description": "Tracked Hyperliquid whales (either side of the trade).", "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/FlowPoint" }, "description": "Bars of the series, oldest first." }, "buyUsd": { "type": "number", "description": "Bought by tracked whales (USD)." }, "sellUsd": { "type": "number", "description": "Sold by tracked whales (USD)." } }, "required": [ "points", "buyUsd", "sellUsd" ] }, "totals": { "type": "object", "properties": { "buyUsd": { "type": "number", "description": "Taker buys (USD)." }, "sellUsd": { "type": "number", "description": "Taker sells (USD)." }, "delta": { "type": "number", "description": "Buys minus sells (USD)." }, "trades": { "type": "integer", "description": "Prints." } }, "required": [ "buyUsd", "sellUsd", "delta", "trades" ], "description": "Sums over the rows of this object." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." }, "profile": { "$ref": "#/components/schemas/VolumeProfile" } }, "required": [ "coin", "stepMinutes", "from", "to", "total", "byVenue", "bySize", "whales", "totals", "updatedAt", "profile" ] }, "ScreenerRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "mark": { "type": [ "number", "null" ], "description": "Hyperliquid mark; for a coin without a Hyperliquid market the mark of the enabled exchange with the largest open interest." }, "change1h": { "type": [ "number", "null" ], "description": "Price change in 1 h, fraction." }, "change24h": { "type": [ "number", "null" ], "description": "Price change in 24 h, fraction." }, "oiUsd": { "type": [ "number", "null" ], "description": "Open interest of the enabled venues (USD)." }, "oiChange1h": { "type": [ "number", "null" ], "description": "Open interest change in 1 h (venues with a value at both times), fraction." }, "oiChange24h": { "type": [ "number", "null" ], "description": "Open interest change in 24 h, fraction." }, "volume24hUsd": { "type": [ "number", "null" ], "description": "Hyperliquid 24 h volume (coins without a Hyperliquid market: summed over the exchanges that report one) (USD)." }, "fundingApr": { "type": [ "number", "null" ], "description": "Hyperliquid funding now, annualised fraction (null for a coin without a Hyperliquid market)." }, "fundingPredApr": { "type": [ "number", "null" ], "description": "Predicted next Hyperliquid funding, annualised fraction." }, "lsHl": { "type": [ "number", "null" ], "description": "Tracked Hyperliquid long USD / short USD." }, "lsBinanceTop": { "type": [ "number", "null" ], "description": "Binance top traders long/short (positions); null when Binance is switched off." }, "liq24hUsd": { "type": [ "number", "null" ], "description": "Liquidations in 24 h (CEX as reported, Hyperliquid confirmed by fills) (USD)." }, "liq24hLongUsd": { "type": [ "number", "null" ], "description": "Long liquidations in 24 h (USD)." }, "liq24hShortUsd": { "type": [ "number", "null" ], "description": "Short liquidations in 24 h (USD)." }, "clusterDistance": { "type": [ "number", "null" ], "description": "Signed distance mark → nearest big liquidation cluster, fraction (−0.03 = 3 % below)." }, "clusterUsd": { "type": [ "number", "null" ], "description": "USD in that cluster (USD)." }, "clusterSide": { "type": [ "string", "null" ], "enum": [ "long", "short", null ], "description": "Dominant side of the cluster." }, "rsi1h": { "type": [ "number", "null" ], "description": "RSI(14) of 1h candles, 0–100." }, "rsi4h": { "type": [ "number", "null" ], "description": "RSI(14) of 4h candles, 0–100." }, "vol24h": { "type": [ "number", "null" ], "description": "24 h realised volatility of 1h closes, annualised fraction." }, "maxLeverage": { "type": [ "integer", "null" ], "description": "Maximum leverage the venue allows on this market." } }, "required": [ "coin", "mark", "change1h", "change24h", "oiUsd", "oiChange1h", "oiChange24h", "volume24hUsd", "fundingApr", "fundingPredApr", "lsHl", "lsBinanceTop", "liq24hUsd", "liq24hLongUsd", "liq24hShortUsd", "clusterDistance", "clusterUsd", "clusterSide", "rsi1h", "rsi4h", "vol24h", "maxLeverage" ] }, "PredictedCell": { "type": "object", "properties": { "fundingHourly": { "type": "number", "description": "Predicted rate per hour, fraction." }, "fundingApr": { "type": "number", "description": "Annualised (hourly × 24 × 365), fraction." }, "intervalHours": { "type": "number", "description": "Funding interval of the venue in hours." }, "nextFundingTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Next funding time of the venue." } }, "required": [ "fundingHourly", "fundingApr", "intervalHours", "nextFundingTime" ] }, "PredictedFundingRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "byVenue": { "type": "object", "description": "Per venue (hyperliquid, binance, bybit; switched-off venues are missing).", "properties": { "hyperliquid": { "$ref": "#/components/schemas/PredictedCell" }, "binance": { "$ref": "#/components/schemas/PredictedCell" }, "bybit": { "$ref": "#/components/schemas/PredictedCell" } }, "additionalProperties": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "coin", "byVenue", "updatedAt" ] }, "SentimentInput": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "momentum", "volatility", "funding", "oi", "longShort", "liquidations", "whales" ], "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "name": { "type": "string", "description": "Name of the input, e.g. \"Price momentum\"." }, "weight": { "type": "integer", "description": "Fixed weight of the input (of 100)." }, "status": { "type": "string", "enum": [ "ok", "collecting", "missing", "off" ], "description": "ok = counted; collecting = fewer than method.minSamples earlier daily values; missing = no data for the period; off = a source of it is switched off." }, "samples": { "type": "integer", "description": "Earlier daily values in the 365-day lookback." }, "score": { "type": [ "number", "null" ], "description": "0–100: percentile against its own lookback (volatility inverted); null unless ok." }, "points": { "type": [ "number", "null" ], "description": "Points this input adds to the total (weight renormalised over the counted inputs); null unless ok." } }, "required": [ "id", "name", "weight", "status", "samples", "score", "points" ] }, "SentimentLabel": { "type": "string", "enum": [ "Extreme fear", "Fear", "Neutral", "Greed", "Extreme greed" ] }, "SentimentDay": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC date of the 00:00 value (YYYY-MM-DD)." }, "at": { "type": "string", "format": "date-time", "description": "00:00 UTC of that day." }, "score": { "type": "number", "description": "0–100." }, "label": { "$ref": "#/components/schemas/SentimentLabel" }, "weightUsed": { "type": "integer", "description": "Sum of the weights of the inputs that counted (of 100)." } }, "required": [ "day", "at", "score", "label", "weightUsed" ] }, "Sentiment": { "type": "object", "properties": { "name": { "type": "string", "description": "Always \"Blockmetric Sentiment\"." }, "current": { "type": [ "object", "null" ], "description": "Current value with its breakdown; null while less than method.minWeight of the weight has enough history.", "properties": { "at": { "type": "string", "format": "date-time", "description": "Time of the value." }, "score": { "type": "number", "description": "0–100." }, "label": { "$ref": "#/components/schemas/SentimentLabel" }, "daily": { "type": "boolean", "description": "true: no fresh intraday value, this is the latest daily value at 00:00 UTC." }, "weightUsed": { "type": "integer", "description": "Sum of the weights of the inputs that counted (of 100; at least method.minWeight)." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/SentimentInput" }, "description": "Affected parts of the service." } }, "required": [ "at", "score", "label", "daily", "weightUsed", "components" ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SentimentDay" }, "description": "Daily values at 00:00 UTC, oldest first; days without a score are left out." }, "firstDay": { "type": [ "string", "null" ], "description": "First day with a score." }, "method": { "type": "object", "description": "The fixed rules of the index (/methodology#sentiment).", "properties": { "lookbackDays": { "type": "integer", "description": "Days of daily values every input is ranked against." }, "minSamples": { "type": "integer", "description": "Earlier daily values an input needs before it counts." }, "minWeight": { "type": "integer", "description": "Minimum weight (of 100) of the counted inputs for a value." }, "bands": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "integer", "description": "Lowest rounded score of the band." }, "to": { "type": "integer", "description": "Highest rounded score of the band." }, "label": { "$ref": "#/components/schemas/SentimentLabel" } }, "required": [ "from", "to", "label" ] }, "description": "Label bands on the rounded score." } }, "required": [ "lookbackDays", "minSamples", "minWeight", "bands" ] } }, "required": [ "name", "current", "history", "firstDay", "method" ] }, "SpreadLeg": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" }, "fundingApr": { "type": [ "number", "null" ], "description": "Annualised funding, fraction; null for an exchange whose raw rates are withheld during the licence review (meta.restricted)." }, "intervalHours": { "type": [ "number", "null" ], "description": "Funding interval in hours (null when unknown)." }, "openInterestUsd": { "type": [ "number", "null" ], "description": "Open interest on this venue; null when unknown or withheld (USD)." } }, "required": [ "venue", "fundingApr", "intervalHours", "openInterestUsd" ] }, "FundingSpreadRow": { "type": "object", "properties": { "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "basis": { "type": "string", "enum": [ "current", "predicted" ], "description": "current = published rates now, predicted = predicted next rates." }, "high": { "$ref": "#/components/schemas/SpreadLeg" }, "low": { "$ref": "#/components/schemas/SpreadLeg" }, "spreadApr": { "type": "number", "description": "high − low, annualised fraction." }, "spreadDaily": { "type": "number", "description": "Spread per day (spreadApr / 365), fraction." }, "minOpenInterestUsd": { "type": [ "number", "null" ], "description": "Smaller open interest of the two legs; null when a leg is withheld (USD)." }, "venues": { "type": "integer", "description": "Venues with a rate for this coin." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Newest data time of this item (ISO 8601 UTC)." } }, "required": [ "coin", "basis", "high", "low", "spreadApr", "spreadDaily", "minOpenInterestUsd", "venues", "updatedAt" ] }, "Movement": { "type": "object", "properties": { "id": { "type": "string", "description": "\"m\" on-chain movement, \"p\" Hyperliquid position change, \"t\" Hyperliquid trade print." }, "ts": { "type": "string", "format": "date-time", "description": "Block time (on-chain) or event time." }, "type": { "type": "string", "enum": [ "transfer", "exchange_in", "exchange_out", "exchange_exchange", "mint", "burn", "bridge", "dex_buy", "dex_sell", "perp_position", "big_trade" ], "description": "Type of the item (enum of this field)." }, "chain": { "type": "string", "description": "ethereum | arbitrum | base | bitcoin | hyperliquid." }, "asset": { "type": "string", "description": "Asset symbol (USDT, USDC, ETH, WETH, BTC, WBTC, …) or Hyperliquid coin." }, "amount": { "type": [ "number", "null" ], "description": "Units of the asset." }, "usd": { "type": [ "number", "null" ], "description": "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": { "type": [ "string", "null" ], "description": "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": { "type": "string", "description": "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": { "type": [ "string", "null" ], "description": "Context from our own records, e.g. \"largest USDC mint this week\"." }, "from": { "type": [ "object", "null" ], "properties": { "address": { "type": [ "string", "null" ], "description": "Wallet or contract address (EVM lowercase 0x…, or Bitcoin)." }, "label": { "type": [ "string", "null" ], "description": "Label with a cited source, else null (no sourced label)." }, "url": { "type": [ "string", "null" ], "description": "Explorer page." } }, "required": [ "address", "label", "url" ], "description": "Start of the window (ISO 8601 UTC) or the sending side of a movement." }, "to": { "type": [ "object", "null" ], "properties": { "address": { "type": [ "string", "null" ], "description": "Wallet or contract address (EVM lowercase 0x…, or Bitcoin)." }, "label": { "type": [ "string", "null" ], "description": "Display label: a public label with a cited source, else the self-chosen leaderboard name (unverified)." }, "url": { "type": [ "string", "null" ], "description": "Link (absolute URL)." } }, "required": [ "address", "label", "url" ], "description": "End of the window (ISO 8601 UTC) or the receiving side of a movement." }, "txUrl": { "type": [ "string", "null" ], "description": "Transaction on the public block explorer of its chain." }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Readable details (chain, amount, value basis, block, venue, label source …)." } }, "required": [ "id", "ts", "type", "chain", "asset", "amount", "usd", "priceSource", "title", "context", "from", "to", "txUrl", "details" ] }, "ExchangeFlows": { "type": "object", "properties": { "windowHours": { "type": "integer", "description": "Window in hours." }, "since": { "type": "string", "format": "date-time", "description": "Start of the window (full hour)." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "exchange": { "type": "string", "description": "Exchange name (as labelled from its own proof-of-reserves addresses)." }, "asset": { "type": "string", "description": "Asset symbol (stablecoins, ETH, BTC …)." }, "chains": { "type": "array", "items": { "type": "string" }, "description": "Chains involved." }, "inUsd": { "type": "number", "description": "Inflow (USD)." }, "outUsd": { "type": "number", "description": "Outflow (USD)." }, "netUsd": { "type": "number", "description": "In − out (USD)." }, "inAmount": { "type": "number", "description": "Units of the asset that flowed in (priced and unpriced)." }, "outAmount": { "type": "number", "description": "Units of the asset that flowed out." }, "inCount": { "type": "integer", "description": "Transfers in." }, "outCount": { "type": "integer", "description": "Transfers out." }, "unpricedInCount": { "type": "integer", "description": "Transfers in without a fresh price (not in any USD figure)." }, "unpricedOutCount": { "type": "integer", "description": "Transfers out without a fresh price." }, "unpricedInAmount": { "type": "number", "description": "Units of the unpriced inflows." }, "unpricedOutAmount": { "type": "number", "description": "Units of the unpriced outflows." } }, "required": [ "exchange", "asset", "chains", "inUsd", "outUsd", "netUsd", "inAmount", "outAmount", "inCount", "outCount", "unpricedInCount", "unpricedOutCount", "unpricedInAmount", "unpricedOutAmount" ] }, "description": "The rows of this view." }, "byExchange": { "type": "array", "items": { "type": "object", "properties": { "exchange": { "type": "string", "description": "Exchange name (as labelled from its own proof-of-reserves addresses)." }, "inUsd": { "type": "number", "description": "Inflow (USD)." }, "outUsd": { "type": "number", "description": "Outflow (USD)." }, "netUsd": { "type": "number", "description": "In − out (USD)." } }, "required": [ "exchange", "inUsd", "outUsd", "netUsd" ] }, "description": "Totals per exchange over all assets (priced transfers only)." }, "coverageFrom": { "type": [ "string", "null" ], "format": "date-time", "description": "First hour with data." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest hour with data." } }, "required": [ "windowHours", "since", "rows", "byExchange", "coverageFrom", "updatedAt" ] }, "TapePrint": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "coin": { "type": "string", "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "venue": { "$ref": "#/components/schemas/FlowVenue" }, "market": { "type": "string", "enum": [ "perp", "spot" ], "description": "perp = perpetual futures, spot = spot market." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Side of the taker." }, "px": { "type": "number", "description": "Volume-weighted price of the print." }, "usd": { "type": "number", "description": "Print size (USD)." }, "fills": { "type": "integer", "description": "Trades merged into the print." }, "taker": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{40}$", "description": "Hyperliquid address, lowercase." }, "whale": { "type": "boolean", "description": "The taker is a tracked Hyperliquid whale." } }, "required": [ "id", "ts", "coin", "venue", "market", "side", "px", "usd", "fills", "taker", "whale" ] }, "EventEnvelope": { "type": "object", "description": "Body of webhook deliveries and `data:` of stream events.", "properties": { "id": { "type": "string", "pattern": "^evt_(?:\\d+|test_[0-9a-f]+)$", "description": "\"evt_\": identical on retries; deduplicate on it." }, "type": { "type": "string", "enum": [ "whale_open", "whale_close", "whale_liquidated", "big_liquidation", "liq_cascade", "funding_extreme", "funding_flip", "oi_spike", "hack", "depeg", "tvl_drop", "cex_outflow", "whale_near_liq", "record", "smart_money", "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" ], "description": "Event kind or \"test\"." }, "created": { "type": "integer", "description": "Unix seconds of the event." }, "data": { "type": "object", "description": "One item of GET /radar/events.", "properties": { "id": { "type": "integer", "description": "Stable id of the item; on paginated feeds the order key together with ts." }, "ts": { "type": "string", "format": "date-time", "description": "Time of the event (ISO 8601 UTC)." }, "kind": { "type": "string", "enum": [ "whale_open", "whale_close", "whale_liquidated", "big_liquidation", "liq_cascade", "funding_extreme", "funding_flip", "oi_spike", "hack", "depeg", "tvl_drop", "cex_outflow", "whale_near_liq", "record", "smart_money", "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" ], "description": "Kind of the item (enum of this field)." }, "severity": { "$ref": "#/components/schemas/Severity" }, "coin": { "type": [ "string", "null" ], "description": "Coin name as on Hyperliquid (BTC, kPEPE, HIP-3 names like xyz:TSLA)." }, "title": { "type": "string", "description": "One-line factual title in our own words." }, "body": { "type": [ "string", "null" ], "description": "Details in our own words, or null." }, "data": { "description": "Kind-specific details or null." }, "source": { "type": [ "string", "null" ], "description": "Data source id or name of this item." }, "truncated": { "type": "boolean", "description": "true when an oversized event was shortened. Fetch it via GET /radar/events." } }, "required": [ "id", "ts", "kind", "severity", "coin", "title", "body", "data", "source" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The same moment as `created`, ISO 8601 UTC (API 1.14.0; absent only on retries of older deliveries)." } }, "required": [ "id", "type", "created", "data" ] }, "Me": { "type": "object", "properties": { "keyless": { "type": "boolean", "description": "true = keyless public access (X-Blockmetric-Access: public)." }, "key": { "type": [ "object", "null" ], "description": "The calling key; null with keyless access.", "properties": { "masked": { "type": "string", "description": "Prefix and last 4 characters (bm_live_…ABCD), never the key." }, "name": { "type": [ "string", "null" ], "description": "Your label of the key." }, "createdAt": { "type": "string", "format": "date-time", "description": "Created." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry; null = none." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last request with the key (updated at most once a minute)." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "api", "node" ] }, "description": "api = this data API, node = the node gateway." }, "ipAllowlist": { "type": "array", "items": { "type": "string" }, "description": "CIDR ranges the key is limited to; empty = any address." }, "allowedOrigins": { "type": "array", "items": { "type": "string" }, "description": "Browser origins that may use the key; empty = server use only." } }, "required": [ "masked", "name", "createdAt", "expiresAt", "lastUsedAt", "scopes", "ipAllowlist", "allowedOrigins" ] }, "plan": { "$ref": "#/components/schemas/Plan" }, "limits": { "type": "object", "description": "Limits of the plan.", "properties": { "perMinute": { "type": "integer", "description": "Requests per minute (account, all keys)." }, "perDay": { "type": "integer", "description": "Requests per UTC day." }, "webhookEndpoints": { "type": "integer", "description": "Webhook endpoints the plan includes." }, "streams": { "type": "integer", "description": "Concurrent live streams the plan includes." } }, "required": [ "perMinute", "perDay", "webhookEndpoints", "streams" ] }, "usage": { "type": "object", "description": "Requests of the account in the current minute and UTC day (this request is not counted).", "properties": { "minute": { "anyOf": [ { "$ref": "#/components/schemas/UsageWindow", "description": "The current one-minute window; null when unknown." }, { "type": "null" } ], "description": "The current one-minute window; null when unknown." }, "day": { "anyOf": [ { "$ref": "#/components/schemas/UsageWindow", "description": "The current UTC day; null when unknown." }, { "type": "null" } ], "description": "The current UTC day; null when unknown." } }, "required": [ "minute", "day" ] }, "overage": { "type": "object", "description": "Requests beyond the daily limit (billed per 1,000 calls up to the monthly cap).", "properties": { "available": { "type": "boolean", "description": "The plan can bill requests beyond the daily limit (API Dev, API Pro)." }, "enabled": { "type": "boolean", "description": "Overage is switched on for the account." }, "capUsd": { "type": [ "number", "null" ], "description": "Monthly cap of the overage cost in USD." }, "pricePer1kUsd": { "type": [ "number", "null" ], "description": "Price per 1,000 calls beyond the daily limit in USD." }, "monthCalls": { "type": "integer", "description": "Calls billed as overage this UTC month." }, "monthCostUsd": { "type": "number", "description": "Overage cost this UTC month (USD)." } }, "required": [ "available", "enabled", "capUsd", "pricePer1kUsd", "monthCalls", "monthCostUsd" ] }, "access": { "type": "object", "description": "Data scope of the plan.", "properties": { "historyDays": { "type": "integer", "description": "Days of history the plan reads." }, "delayMinutes": { "type": "integer", "description": "Feed delay in minutes (0 = real time)." }, "heatmapTimeframes": { "type": "array", "items": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "12h", "1d" ] }, "description": "Heatmap intervals of the plan." }, "liqMapCoins": { "type": [ "integer", "null" ], "description": "Coins with liquidation levels now (top by open interest); null = every coin." }, "commercial": { "type": "boolean", "description": "Whether the licence allows commercial use (see meta.license)." } }, "required": [ "historyDays", "delayMinutes", "heatmapTimeframes", "liqMapCoins", "commercial" ] }, "restrictedVenues": { "type": "array", "items": { "type": "string", "enum": [ "binance", "bybit", "okx" ] }, "description": "Exchanges whose raw rows the API withholds during the licence review." } }, "required": [ "keyless", "key", "plan", "limits", "usage", "overage", "access", "restrictedVenues" ] }, "UsageWindow": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Requests allowed in the window." }, "used": { "type": "integer", "description": "Requests used." }, "remaining": { "type": "integer", "description": "Requests left." }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the window resets." } }, "required": [ "limit", "used", "remaining", "resetsAt" ] }, "MarketsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FundingResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FundingRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "LiquidationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Liquidation" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "LiqMapResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LiqMap" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TopPositionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "WhaleFeedResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionEvent" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "WalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "RadarEventsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RadarEvent" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "StatsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Stats" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CoinsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coin" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "HeatmapResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Heatmap" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "HeatmapOpenInterestResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HeatmapOpenInterest" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "HeatmapWalletsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HeatmapWallets" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ScoreboardResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Scoreboard" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "LiquidationSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LiquidationSummary" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "LongShortResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LongShortRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "WhalesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhaleRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CandlesResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Candles" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "WhaleStopsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WhaleStops" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TradersResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Traders" }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "CohortsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cohorts" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "SmartMoneyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SmartMoney" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "OrderbookResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Orderbook" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FlowResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Flow" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TapeResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TapePrint" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "ScreenerResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScreenerRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "PredictedFundingResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PredictedFundingRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FundingSpreadsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FundingSpreadRow" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "SentimentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Sentiment" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "SecurityIncidentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityItem" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "SecurityWalletsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListedWallet" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "SecurityWalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListedWalletDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "MovementsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } }, "meta": { "$ref": "#/components/schemas/Meta", "description": "meta.nextCursor is always present on this endpoint (null on the last page)." } }, "required": [ "data", "meta" ] }, "ExchangeFlowsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExchangeFlows" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "MeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "StatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiStatus" }, "meta": { "type": "object", "properties": { "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "string" } }, "required": [ "updatedAt", "source" ] } }, "required": [ "data", "meta" ] } } } }