Open API

The same Ethereum snapshot used by the ethwatch dashboard, exposed as read-only JSON with source status intact.

Data honesty: every figure carries a provenance status. unavailable means the source failed, not zero. Null values are never replaced with estimates or zeroes.

Free access

The free tier allows 1 request per second per key. Register an email address, open the verification link within 30 minutes, and copy the key when it appears. It is shown once and cannot be recovered.

curl -X POST https://api.ethwatch.org/v1/keys \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

Use the key as a bearer credential. The ?key= query parameter is also accepted for browser testing, but bearer authentication avoids putting credentials in browser history.

Endpoints

GET /

Redirect to this documentation.

curl -I https://api.ethwatch.org/

GET /v1/health

Public health and snapshot age in seconds.

curl https://api.ethwatch.org/v1/health

GET /openapi.json

Public OpenAPI 3.1 description.

curl https://api.ethwatch.org/openapi.json

POST /v1/keys

Request a verification email. Registration is IP-rate-limited.

curl -X POST https://api.ethwatch.org/v1/keys -H 'content-type: application/json' -d '{"email":"you@example.com"}'

GET /v1/keys/verify?token=…

Open the link from the email. Tokens expire after 30 minutes and work once.

curl 'https://api.ethwatch.org/v1/keys/verify?token=TOKEN_FROM_EMAIL'

GET /v1/snapshot

The complete dashboard document, including meta.provenance.

curl https://api.ethwatch.org/v1/snapshot -H 'Authorization: Bearer YOUR_API_KEY'

GET /v1/sources

The source registry generated from the indexer's source of truth at build time.

curl https://api.ethwatch.org/v1/sources -H 'Authorization: Bearer YOUR_API_KEY'

GET /v1/{section}

One section plus its exact provenance object. Sections: price, supply, issuance, gas, staking, l2, holdings, and network.

curl https://api.ethwatch.org/v1/price -H 'Authorization: Bearer YOUR_API_KEY'

Each section has its own endpoint:

curl https://api.ethwatch.org/v1/price -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/supply -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/issuance -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/gas -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/staking -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/l2 -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/holdings -H 'Authorization: Bearer YOUR_API_KEY'
curl https://api.ethwatch.org/v1/network -H 'Authorization: Bearer YOUR_API_KEY'

Response shape

Section responses keep the value and provenance separate. Values may be null and remain null.

{
  "generatedAt": "2026-08-28T00:00:00.000Z",
  "data": { "...": "section fields" },
  "provenance": { "status": "live", "source": "...", "detail": "..." }
}

Rate-limit headers

The service also has a 300 requests/second global backstop to protect the shared snapshot origin.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the per-key window.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Unix timestamp when the oldest request leaves the window.
`X-Snapshot-Generated`	The snapshot's exact `generatedAt` value.
`Retry-After`	Seconds to wait after a 429 response.

Errors

Status	Meaning
400	Invalid email, request body, or verification token.
401	The API key is missing or unknown.
404	The endpoint or requested section does not exist.
429	A per-key, global, or registration-IP limit was reached.
503	The snapshot or rate limiter is unavailable.

Evidence

Read the full methodology, or inspect evidence by section: price, supply, issuance, gas, staking, layer 2, holdings, and network.