Authentication

Blockworks authenticates requests with an API key sent in a request header. There is no OAuth flow, no token exchange, and no session state. Every request carries the key. One key covers every product. The same key authenticates the Data API, Monitoring, and the MCP Server. Datashare access is granted to your warehouse account rather than by key. See Datashares.

Get an API key

Create and manage keys at app.blockworks.com/account/api. Keys are shown once at creation, so store yours in a secret manager or environment variable.

Using your key

Pass the key in the X-Blockworks-API-Key header on every request to https://api.blockworks.com:

curl 'https://api.blockworks.com/query/ping' \
  --header "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"

For a full first request in curl, Python, and JavaScript, see the Data API quickstart or the Monitoring quickstart.

The header name is X-Blockworks-API-Key. Header names are case-insensitive, so x-blockworks-api-key works identically. The legacy x-messari-api-key header is still accepted for existing integrations; new code should send X-Blockworks-API-Key.

Access tiers

Not every dataset requires the same level of access. Each model in the catalog declares an access tier, and the API enforces it per request:

Tier	Who can query it	Without the required access
`public`	Anyone, including unauthenticated requests.	never refused (an invalid key is still `403 Forbidden`)
`unpaid`	Any request that carries a valid API key, on any plan.	`401 this model requires authentication`
`paid`	A valid key on a paid plan (Lite, Pro or Enterprise).	`401` without a key, `403 this model requires a paid subscription` with a free-plan key
`permissive`	A valid key holding the model’s specific permission (`access.permissionSlug`).	`401` without a key, `403` otherwise

Models restricted to internal users do not appear in the public catalog or in this reference. Paid is the default tier of the reference, so reference pages only call out the exceptions (public models and models that need a specific permission). You can read the tier of any model from access.tier in the catalog endpoints. See Errors for the exact messages.

Rate limits

Each account gets one allowance, shared by every endpoint it calls. The allowance depends on your plan:

Plan	Allowance
No key or Free	200 requests per minute
Lite, Pro and Enterprise	600 requests per minute
Trial	25 requests per hour

Every response reports where you stand in the current window:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the window.
`X-RateLimit-Remaining`	Requests left in the window.
`X-RateLimit-Reset`	When the window ends and the allowance refills, as a Unix timestamp in seconds.

A request over the limit gets 429 Too Many Requests with a Retry-After header giving the whole number of seconds to wait before the next request will succeed:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": "Too Many Requests", "data": null }

Wait for Retry-After before you retry, and send one request at a time while you wait.

Keep your key secret. Never commit it to version control, embed it in a client-side bundle, or paste it into a shared document or support ticket. Requests made with your key count against your account.

Handling keys safely

Server-side only

Call the API from your backend. A key shipped to a browser or mobile app is a public key.

Environment variables

Load the key from the environment or a secrets manager rather than hardcoding it.

Rotate regularly

Regenerate your key periodically, and immediately if you suspect it has leaked.

Verify your setup

/query/ping is a lightweight endpoint for confirming your client is wired up correctly. The request above returns:

{
  "error": null,
  "data": { "message": "pong" }
}

Welcome

Feedback

Get an API key

Using your key

Access tiers

Rate limits

Handling keys safely

Server-side only

Environment variables

Rotate regularly

Verify your setup

​Get an API key

​Using your key

​Access tiers

​Rate limits

​Handling keys safely

Server-side only

Environment variables

Rotate regularly

​Verify your setup

Get an API key

Using your key

Access tiers

Rate limits

Handling keys safely

Verify your setup