Python SDK - BlockDB Docs

The BlockDB Python SDK supports Python 3.x and covers all EVM API endpoints. The primary client is async (built on httpx); a synchronous wrapper is included for scripts and notebooks.

Where it’s available

PyPI: blockdb
Source (open source): github.com/blockdb-io/blockdb-python-api-sdk

Installation

pip install blockdb

Quick examples

import asyncio
import os
from blockdb import BlockDbClient
from blockdb.evm.primitives import BlocksRequest

async def main():
    async with BlockDbClient(
        api_key=os.environ["BLOCKDB_API_KEY"],
    ) as client:
        page = await client.evm.primitives.get_blocks(
            BlocksRequest(
                chain_id=1,
                from_block=20_000_000,
                to_block=20_000_100,
                limit=100,
            )
        )
        for block in page.data:
            print(block.block_number, block.timestamp_utc)

asyncio.run(main())

import os
from blockdb import SyncBlockDbClient

with SyncBlockDbClient(
    api_key=os.environ["BLOCKDB_API_KEY"],
) as client:
    page = client.evm.primitives.get_blocks(
        {"chain_id": 1, "from_block": 20_000_000, "to_block": 20_000_100}
    )
    print(f"{page.count} blocks, next cursor: {page.cursor}")

Prices example

import os
from blockdb import BlockDbClient

async with BlockDbClient(api_key=os.environ["BLOCKDB_API_KEY"]) as client:
    candles = await client.evm.prices.get_crypto_ohlc({
        "chain_id": 1,
        "base_token_address":  "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",  # WETH
        "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",  # USDC
        "from_block": 21_000_000,
        "to_block":   21_010_000,
    })
    for c in candles.data:
        print(c.open_timestamp, c.open, c.high, c.low, c.close)

Pagination

Every endpoint returns a PagedResponse[T] with a cursor field. Use async_pages to iterate all pages automatically:

import os
from blockdb import BlockDbClient

async with BlockDbClient(api_key=os.environ["BLOCKDB_API_KEY"]) as client:
    cursor = None
    while True:
        page = await client.evm.primitives.get_blocks(
            {"chain_id": 1, "from_block": 18_000_000, "to_block": 19_000_000, "cursor": cursor}
        )
        process(page.data)
        cursor = page.cursor
        if not page.has_more:
            break

import os
from blockdb import BlockDbClient, async_pages

async with BlockDbClient(api_key=os.environ["BLOCKDB_API_KEY"]) as client:
    async for page in async_pages(
        client.evm.primitives.get_blocks,
        {"chain_id": 1, "from_block": 18_000_000, "to_block": 19_000_000},
    ):
        print(f"Got {page.count} blocks (cursor={page.cursor})")

Configuration reference

import os
from blockdb import BlockDbClient
from blockdb._config import ClientConfig, RetryPolicy

client = BlockDbClient(
    api_key=os.environ["BLOCKDB_API_KEY"],
    config=ClientConfig(
        base_url="https://api.blockdb.io/v1",  # default
        timeout=30.0,
        connect_timeout=10.0,
        retry_policy=RetryPolicy(),
        max_requests_per_second=None,  # no limit by default
    ),
)

Create and rotate keys in dashboard.blockdb.io. See Authorization for BLOCKDB_API_KEY and best practices.

Last modified on April 22, 2026