Cursor

---
description: How to call the BlockDB on-chain data API
alwaysApply: false
---

# BlockDB API

When the user asks for Ethereum / EVM on-chain data (blocks, transactions, logs,
transfers, swaps, pools, reserves, prices, TVL, yields), call the BlockDB REST API.

## Hard rules
- Base URL: `https://api.blockdb.io/v1`
- Auth: every request sends `Authorization: Bearer ${BLOCKDB_API_KEY}` (read from env, never hardcode).
- Method: `POST` with `Content-Type: application/json`. All filters go in the JSON body, not query params. (Exception: `GET /usage`.)
- Response envelope: `{ "data": [...], "cursor": "<string|null>", "page_count": <number> }`.
- Pagination: if `cursor` is non-null, resend the same body with that `cursor`. Stop when `cursor` is null.
- Determinism: prefer `from_block` / `to_block` over timestamps.
- Required: `chain_id` (Ethereum = 1). Never invent chain_id, exchange_id, pool_type_id, or addresses — resolve them from the docs.

## Request template
{ "chain_id": 1, "from_block": 19000000, "to_block": 19001000, "limit": 250, "cursor": null }

## When unsure
Fetch the relevant page from https://docs.blockdb.io before generating a request:
- Endpoint index: /api-reference/evm/overview
- Enumerations (chain, exchange, pool type): /api-reference/enumerations/overview
- Dataset → table mapping: /data-catalog/evm/dataset-index

import polars as pl
df = pl.read_parquet("hf://datasets/blockdb/ethereum-dex-swaps/year=2024/")