Authentication

Overview

All API requests must include your API key in the x-api-key HTTP header. Keys are issued from your Blockworks Research account and are tied to your organization/plan.

Topic	TL;DR
Header	`x-api-key: YOUR_API_KEY`
Where to get it	Blockworks Research → User Dropdown → Account Management → API
Scope	Works across all documented endpoints unless noted otherwise
Rotation	Create a new key, update your services, then revoke the old key
Errors	Missing/invalid → `401 Unauthorized`, insufficient access → `403 Forbidden`

Quick start

curl -H "x-api-key: YOUR_API_KEY"   "https://api.blockworks.com/v1/metrics?project=ethereum&limit=1"

const res = await fetch("https://api.blockworks.com/v1/metrics?project=ethereum&limit=1", {
  headers: { "x-api-key": "YOUR_API_KEY" }
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = await res.json()

import os, requests

resp = requests.get(
  "https://api.blockworks.com/v1/metrics",
  headers={"x-api-key": "YOUR_API_KEY"},
  params={"project": "ethereum", "limit": 1},
  timeout=30
)
resp.raise_for_status()
data = resp.json()

Sending the header

Always send x-api-key on every request.
Use HTTPS only.
Prefer environment variables or a secure secrets manager; never hardcode keys in code or commit history.

Example with Axios (Node)

import axios from "axios"

const api = axios.create({
  baseURL: "https://api.blockworks.com",
  headers: { "x-api-key": "YOUR_API_KEY" },
  timeout: 30_000
})

const { data } = await api.get("/v1/assets", { params: { limit: 20 } })

Key management best practices

Least privilege (if you use multiple keys per environment/team, give the narrowest access).
Separate keys per environment: dev, staging, prod.
Rotate regularly and on any suspected exposure. Safe rotation flow:
1. Create a new key.
2. Deploy config with the new key.
3. Verify traffic and logs.
4. Revoke the old key.
Store securely: cloud secrets manager (e.g., AWS Secrets Manager, GCP Secret Manager, 1Password) or your CI/CD secret store.
Audit usage from your account dashboard (failed requests, rate-limit spikes, unusual origins).

Common errors

Status	Type	Why it happens	How to fix
`401 Unauthorized`	`missing_api_key`	Header not present or malformed	Add `x-api-key` with a valid key
`401 Unauthorized`	`invalid_api_key`	Unknown or revoked key	Use an active key or rotate
`403 Forbidden`	`insufficient_scope`	Key lacks access to the requested resource	Request access or use a key with the right plan/scope
`429 Too Many Requests`	`rate_limited`	Exceeded your plan limits	Backoff/retry with jitter, consider higher tier
`5xx`	`internal_error`	Transient service issue	Retry with exponential backoff and idempotency where applicable

Error body shape

{
    "message": "Unauthorized",
    "statusCode": 401
}

Security checklist

Do not embed keys in client-side apps (browsers, mobile). Proxy through your backend.
Restrict egress on your servers if possible (allowlist api.blockworks.com).
Add rate limiting and retries with jitter to your client.
Log request_id from responses for support/debugging.
Consider key per service (ingesters, web, batch) to isolate exposure.

FAQ

Can I use multiple keys? Yes. Many teams keep separate keys per environment or workload. Api keys for the Blockworks API are team-scoped. Each user on your team will be able to generate and remove keys. Usage is aggregated across all keys on your team. Where do I find or revoke keys? In your blockworks research settings under API Keys.

Introduction

Assets

Chart Data

Token Transparency

Market Stats

Metrics

Metrics: Chains

Metrics: Projects

Metrics: ETFs

Metrics: Treasuries

Overview

Quick start

Sending the header

Example with Axios (Node)

Key management best practices

Common errors

Error body shape

Security checklist

FAQ

​Overview

​Quick start

​Sending the header

​Example with Axios (Node)

​Key management best practices

​Common errors

​Error body shape

​Security checklist

​FAQ

Overview

Quick start

Sending the header

Example with Axios (Node)

Key management best practices

Common errors

Error body shape

Security checklist

FAQ