Skip to main content

​
What this page is for

This page is written for LLMs and automated agents that generate API requests, SDK snippets, or integration code for BlockDB.

​
Hard rules (avoid 90% of mistakes)

  • Base URL: https://api.blockdb.io/v1
  • Auth: Send Authorization: Bearer <API_KEY> on every request.
  • Request shape: Filters go in the JSON body (no query params for filters).
  • Method: Almost all endpoints are POST with a JSON body (the Usage endpoint is GET).
  • Pagination: Responses are envelope-shaped with data, cursor, and count.
  • Determinism: Prefer block ranges for deterministic results; time ranges are supported but are converted to blocks server-side.

​
Choosing the right endpoint

  • Use the EVM API families under /api-reference/evm/* for chain data.
  • Use the Enumerations pages (Chain, Digital Exchange, Pool Type, Dataset ID) instead of guessing numeric IDs.
  • For a single page view of everything available, use the Endpoints Overview page: /api-reference/endpoints/overview.

​
Request template (copy/paste)

Most EVM endpoints follow the same pattern: 
{
  "chain_id": 1,
  "from_block": 19000000,
  "to_block": 19001000,
  "limit": 250,
  "cursor": null
}
Common filters you should expect:
  • chain_id (required)
  • Range filters: (from_block, to_block) or (from_timestamp, to_timestamp) (often mutually exclusive)
  • Selectors: pool_uids, pool_addresses, exchange_ids, pool_type_ids, token addresses, etc.
  • Pagination: limit + cursor

​
Pagination rules

  • If cursor is non-null, call the same endpoint again with that cursor to get the next page.
  • Stop when cursor is null or count is 0.
  • For large exports, prefer narrow ranges (time or block) over huge limit values.

​
Rate limiting & retries

  • Respect 429 responses: back off and retry.
  • Treat 5xx errors as retryable unless the response says otherwise.
  • Keep retries bounded (max attempts + exponential backoff).

​
Lineage & verification (provenance-aware workflows)

If you need auditability:
  • Use _tracing_id fields returned by datasets.
  • Use the Lineage API (/api-reference/evm/lineage/overview) to trace how a row was derived.
  • Use the Verification API (/api-reference/evm/verification/overview) to recompute proofs like receipt roots or logs bloom filters.

​
Good LLM behavior

  • Ask for missing inputs (e.g., which chain, which token addresses, which time range).
  • Prefer enumerations over hardcoded IDs.
  • Never fabricate pool UIDs or token addresses.
  • When unsure about the right endpoint, start from /api-reference/endpoints/overview.