Contents
Authentication & limits
One header per request. Your plan sets how many requests you get per minute and per day, and how far back the data goes.
X-Blockmetric-Access: public: 10 requests a minute and 300 a day per address, 24 h of history. A free key gives you 10 a minute, 1,000 a day and 30 days of history.API keys
Create keys under Account › API keys. Every account includes a free personal key; the full key (bm_live_…) is shown once; we store only a hash.
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
"https://api.blockmetric.io/v1/markets"
# or
curl -s -H "x-api-key: $BLOCKMETRIC_API_KEY" "https://api.blockmetric.io/v1/markets"- Headers only, HTTPS only. A key in the URL (
?api_key=) is refused with400, because URLs end up in logs and browser history. Plain http answers403 https_required. - Typos fail fast. Keys end in a checksum, so a cut or mistyped key answers
401without a lookup, and secret scanners recognise leaked keys. - Name, expiry, IP allowlist, browser origins. Each key can get a name, an expiry date, an IP allowlist (CIDR) and (for browser widgets only) a list of allowed origins. Revoke a key (or all at once) on the account page if it leaks; it stops working immediately.
- Keys belong on your server. A browser request that carries a key is only served when the key lists that page's origin; otherwise it answers
403 origin_not_allowed. Server code (Node, Python, cURL) sends no Origin and is not affected. The rule prevents accidental embedding; it does not replace keeping the key secret.
Without a key
For a first test, notebooks and AI agents: send X-Blockmetric-Access: public instead of a key.
- Data
- The free tier with 24 h of history (a free key: 30 days).
- Limits
- 10 requests a minute and 300 a day per address.
- Licence
- Personal, non-commercial use with the credit "Data by Blockmetric" (
meta.license.id=public).
Rate limits
Per account: all keys share them. Minutes are fixed one-minute windows; the day is the UTC day.
| Plan | Price | Per minute | Per day | History | Licence | Realtime |
|---|---|---|---|---|---|---|
| No key | $0 | 10 | 300 | 24 h | Public | - |
| Free | $0 | 10 | 1,000 | 30 days | personal use | - |
| Pro | $29/mo | 20 | 5,000 | 365 days | personal use | - |
| Desk | $79/mo | 30 | 10,000 | 1095 days | personal use | - |
| API Dev | $49/mo | 60 | 50,000 | 365 days | internal use (1 organisation) | 2 webhooks |
| API Pro | $249/mo | 300 | 500,000 | 1095 days | display in your product | 2 streams · 10 webhooks |
Beyond the daily limit, API Dev and API Pro can switch on billed overage (API Dev $0.5 per 1,000), (API Pro $0.3 per 1,000) under Account › Plan & billing, never above the monthly cap you set; the per-minute limit always stays hard. Compare plans
Desk trial: During the trial, the API key (20/min, 5,000/day), the history depth (1 year), the order-flow depth (7 days) and wallet CSV exports run at Pro level. Everything else is Desk from day one; the first payment, or Start Desk now, unlocks the rest.
Rate-limit and tracing headers
Every response tells you where you stand. Read the headers instead of guessing.
| Header | Meaning |
|---|---|
X-Request-Id | Unique id of this response (also error.request_id). Quote it when contacting support. |
X-Client-Request-Id | 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. |
X-Blockmetric-Api-Version | Version of the v1 contract that served the response (OpenAPI info.version). |
X-RateLimit-Limit | Requests allowed per minute for the account. |
X-RateLimit-Remaining | Requests left in the current minute. |
X-RateLimit-Reset | Unix seconds when the current minute window ends. |
X-RateLimit-Limit-Day | Requests allowed per UTC day for the account. |
X-RateLimit-Remaining-Day | Requests left today (UTC); 0 with overage on means further calls are billed. |
X-RateLimit-Reset-Day | Unix seconds when the UTC day ends. |
RateLimit-Policy | Both quotas in the IETF draft format (draft-ietf-httpapi-ratelimit-headers), e.g. "minute";q=60;w=60, "day";q=100000;w=86400. |
RateLimit | Remaining requests and seconds to the reset per window, IETF draft format, e.g. "minute";r=59;t=42, "day";r=99990;t=50000. |
X-Blockmetric-Overage | "billed" when this request was beyond the daily limit and billed as overage (API Dev / API Pro with overage on). |
X-Blockmetric-Key-Expires | Expiry of the key (ISO 8601), sent during its last 14 days. Create a new key on /account/api in time. |
Retry-After | Seconds to wait before retrying (429). |
ETag | Strong validator of the body; send it as If-None-Match to get 304 Not Modified when nothing changed. |
Deprecation | Only on deprecated endpoints or parameters: "@<unix seconds>" (RFC 9745). |
Sunset | Only on deprecated endpoints with a removal date: HTTP date (RFC 8594). |
Link | Only together with Deprecation: <url of the changelog entry>; rel="deprecation" (RFC 9745). With format=csv / ndjson also <next page>; rel="next" and <licence terms>; rel="license" (RFC 8288). |
X-Blockmetric-Next-Cursor | format=csv / ndjson only: meta.nextCursor (pass it as cursor); absent on the last page. |
X-Blockmetric-Next-After | format=csv / ndjson only: meta.nextAfter of feeds with forward polling. |
X-Blockmetric-Updated-At | format=csv / ndjson only: meta.updatedAt, the newest data timestamp. |
X-Blockmetric-Warnings | format=csv / ndjson only: meta.warnings as code:param pairs, e.g. history:from, clamped:limit (the JSON format has the messages). |
X-Blockmetric-Restricted | format=csv / ndjson only: meta.restricted, the venues the licence gate withheld. |
X-Blockmetric-License | format=csv / ndjson only: meta.license.id, the licence the rows are served under (attribution duties as in meta.license). |
Handling 429
Wait Retry-After seconds and try again. 304 Not Modified and refused 429s are explained in the error catalogue.
# -i prints the headers: X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on a 429
curl -si -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
"https://api.blockmetric.io/v1/liquidations/summary?hours=24" | grep -iE "^(HTTP|x-ratelimit|retry-after)"Poll less, not faster: revalidate with If-None-Match, page with cursors, or let us push events to you with webhooks and the live stream.
Code snippets in these docs are licensed under MIT-0: copy them into your own code without attribution. The SDKs, CLI and MCP server will be, once published, Apache-2.0; the name Blockmetric is not licensed (forks must be renamed). Data from the API is governed by the API terms; third-party exchange data by the exchange’s terms.