> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Official BlockDB SDK for Python — install from PyPI, async-first with a sync wrapper, API key auth and cursor-based pagination built in.

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](https://pypi.org/project/blockdb/)
* **Source (open source):** [github.com/blockdb-io/blockdb-python-api-sdk](https://github.com/blockdb-io/blockdb-python-api-sdk)

## Installation

```bash theme={null}
pip install blockdb
```

## Quick examples

<CodeGroup>
  ```python Async (recommended) theme={null}
  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())
  ```

  ```python Sync wrapper theme={null}
  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}")
  ```
</CodeGroup>

## Prices example

```python theme={null}
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:

<CodeGroup>
  ```python Manual paging theme={null}
  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
  ```

  ```python async_pages helper (all pages) theme={null}
  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})")
  ```
</CodeGroup>

## Configuration reference

```python theme={null}
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](https://dashboard.blockdb.io). See [Authorization](/api-reference/overview/authorization) for `BLOCKDB_API_KEY` and best practices.