# Health
Source: https://docs.blockdb.io/api-reference/account-and-usage/health

GET https://api.blockdb.io/v1/health
Lightweight liveness check that returns API availability.

## Overview

Returns a minimal JSON payload indicating that the BlockDB API is reachable and serving requests. Use this endpoint for uptime monitoring, load balancer health probes, and quick connectivity checks.

<Info>
  This endpoint is intended to be inexpensive and safe to poll. It does not return account or usage data.
</Info>

## Parameters

No query parameters or request body.

## Response Fields

<ResponseField name="status" type="string">
  Always `"ok"` when the service is healthy.
</ResponseField>

### See Also

* [Usage & Limits](/api-reference/account-and-usage/usage) — Plan, shared CU, and shared `rate_limit_rps` for your account
* [Authorization](/api-reference/overview/authorization) — API key usage and auth

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.blockdb.io/v1/health"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.blockdb.io/v1/health")
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/health");
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "ok"
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Account & Usage Overview
Source: https://docs.blockdb.io/api-reference/account-and-usage/overview

Health check, usage, compute units, and shared account rate and CU limits.

## Overview

Account & Usage endpoints help you confirm API availability and monitor consumption so you can:

* Verify that the service is up (`/health`) before or during deploys
* See your plan, compute unit (CU) usage, remaining balance, and reset time (`/usage`)
* Read your configured requests-per-second limit for client-side throttling
* Validate that automation is behaving as expected (no runaway queries)

### Endpoint Matrix

| Endpoint                                                 | Summary                                             |
| -------------------------------------------------------- | --------------------------------------------------- |
| [`GET /health`](/api-reference/account-and-usage/health) | Liveness check (`{"status":"ok"}`)                  |
| [`GET /usage`](/api-reference/account-and-usage/usage)   | Plan, CU usage, `cu_reset_at`, and `rate_limit_rps` |

## Key Concepts

* **Subscription plan**: The `plan` field on [`/usage`](/api-reference/account-and-usage/usage) reflects your current tier.
* **Compute units (CU)**: Each API call consumes a fixed number of CUs by endpoint family; `cu_used`, `cu_limit`, and `cu_remaining` track your monthly allowance.
* **Reset**: `cu_reset_at` is when the CU counter rolls over for the next billing period.
* **Rate limits**: `rate_limit_rps` is the account-wide RPS ceiling **shared by all API keys** (not per-key). See [Rate limiting](/api-reference/overview/rate-limiting).

## Best Practices

* Poll [`/usage`](/api-reference/account-and-usage/usage) on a schedule to watch `cu_remaining` and avoid surprises near `cu_reset_at`.
* Use [`/health`](/api-reference/account-and-usage/health) for load balancer or uptime checks without sending an API key when your setup allows it.
* Use efficient filtering and ranges on data endpoints, and cursor-based pagination for large pulls.

## See Also

* [Pricing](/pricing/home) — BlockDB subscription tiers
* [Rate Limiting](/api-reference/overview/rate-limiting) — RPS limits and quotas
* [Authorization](/api-reference/overview/authorization) — API key usage and auth


# Usage & Limits
Source: https://docs.blockdb.io/api-reference/account-and-usage/usage

GET https://api.blockdb.io/v1/usage
Retrieve your subscription plan, compute unit (CU) balance, billing reset time, and configured RPS limit.

## Overview

Retrieves your current subscription plan, compute unit (CU) usage for the billing period, remaining allowance, when the CU counter resets, and your account’s configured requests-per-second ceiling. **CU and RPS limits are shared across every API key on the account**—see [Rate limiting](/api-reference/overview/rate-limiting). Use this endpoint to stay within quota and to align client throttling with your plan.

<Info>
  This endpoint is free to query and does not consume compute units.
</Info>

## Parameters

This endpoint does not require a request body. You may authenticate with any active key; the response describes **your account**, not a per-key slice of usage or RPS.

## Response Fields

<ResponseField name="plan" type="string">
  Your subscription plan identifier (for example `growth`).
</ResponseField>

<ResponseField name="cu_used" type="number">
  Compute units consumed in the current billing period.
</ResponseField>

<ResponseField name="cu_limit" type="number">
  Total compute units included in your plan for the current billing period.
</ResponseField>

<ResponseField name="cu_remaining" type="number">
  Compute units left before you hit `cu_limit` (`cu_limit` minus `cu_used`).
</ResponseField>

<ResponseField name="cu_reset_at" type="string">
  When the CU counter resets for the next billing period (ISO-8601 UTC).
</ResponseField>

<ResponseField name="rate_limit_rps" type="number">
  Configured maximum requests per second for **your account**. All keys share this same RPS budget; it is not split per key.
</ResponseField>

### Best Practices

<Tip>
  Query this endpoint periodically (for example daily) to monitor consumption and avoid unexpected throttling near the end of a billing period.
</Tip>

<Tip>
  Compare `cu_remaining` with expected workload so you can upgrade or reduce query volume before hitting `cu_limit`.
</Tip>

<Warning>
  While this endpoint does not consume CUs, automated polling should still use a reasonable interval so you do not hit management-endpoint rate limits.
</Warning>

### See Also

* [Health](/api-reference/account-and-usage/health) — API liveness check
* [Pricing](/pricing/home) — BlockDB subscription plans
* [Rate Limiting](/api-reference/overview/rate-limiting) — Understanding RPS limits and quotas
* [Authorization](/api-reference/overview/authorization) — API key management

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.blockdb.io/v1/usage" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      "https://api.blockdb.io/v1/usage",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/usage", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "plan": "growth",
    "cu_used": 0,
    "cu_limit": 4100000,
    "cu_remaining": 4100000,
    "cu_reset_at": "2026-05-22T11:53:12.000Z",
    "rate_limit_rps": 1000
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Asset Class
Source: https://docs.blockdb.io/api-reference/enumerations/asset-class

Asset class identifiers mapped to pricing endpoints.

## AssetClass Enumeration

Defines the asset classes that can appear in price request `base` and `quote` descriptors as well as discovery responses. The `type` field inside asset descriptors must match one of the following values.

| Value    | Description                            | Notes                                                                 |
| -------- | -------------------------------------- | --------------------------------------------------------------------- |
| `erc20`  | Fungible ERC-20 token on an EVM chain. | Require `address` (EIP-55 checksum).                                  |
| `fiat`   | Fiat currency.                         | Require ISO 4217 `code` (e.g., `USD`).                                |
| `native` | Native gas token for a chain.          | Provide `symbol`; optional `wrapped_address` for the wrapped variant. |
| `index`  | Synthetic/composite index.             | Provide `symbol` referencing BlockDB index ID.                        |

### Usage Notes

* Additional asset classes may be introduced over time; clients should treat unknown values as unsupported.
* Asset descriptors may include supplementary metadata (e.g., `decimals`) but only the fields listed above are required for price
  endpoints.


# Chain
Source: https://docs.blockdb.io/api-reference/enumerations/chain

Supported EVM chain IDs compatible with ChainList.

An enumeration of supported Ethereum chain IDs. Compatible with [ChainList](https://chainlist.org/). Operational coverage and rollout status for these networks are summarized on the [Data Catalog Coverage](/data-catalog/overview/coverage) page.

***

### Values

| Value   | Description       | Status           |
| ------- | ----------------- | ---------------- |
| `1`     | Ethereum Mainnet  | ✅ Supported      |
| `10`    | Optimism          | 🔵 Investigation |
| `56`    | BNB Chain         | 🔵 Investigation |
| `130`   | Unichain          | 🔵 Investigation |
| `137`   | Polygon           | 🔵 Investigation |
| `146`   | Sonic             | 🔵 Investigation |
| `5000`  | Mantle            | 🔵 Investigation |
| `8453`  | Base              | 🔵 Investigation |
| `42161` | Arbitrum          | 🔵 Investigation |
| `43114` | Avalanche C-Chain | 🔵 Investigation |
| `59144` | Linea             | 🔵 Investigation |

<Callout icon="lightbulb">
  Need a chain prioritized? Contact **[support@blockdb.io](mailto:support@blockdb.io)** directly and we will help scope timelines and requirements.
</Callout>


# Dataset ID
Source: https://docs.blockdb.io/api-reference/enumerations/dataset-id

Dataset identifiers for BlockDB export catalogs.

## DatasetId Enumeration

Defines the canonical dataset identifiers used across Historic API and WebSocket payloads (e.g., the `dataset` / `dataset_id` field). Each identifier maps to a documented REST endpoint and Postgres table in `blockdb_evm`. Prefix indicates the functional domain:

* `01xx` — base chain primitives (blocks, transactions, logs, internal traces, contracts, function results)
* `02xx` — token and pool metadata (ERC-20/721/1155, pools, fee terms)
* `03xx` — reserves, swap prints, swap fees, transfers, flash loans
* `04xx` — token-to-token OHLC, per-pool VWAP time buckets, pool yields (`0411`)
* `05xx` — cross-pool token-to-token VWAP (aggregated across venues)
* `06xx` — token-to-fiat (USD) VWAP
* `07xx` — pool TVL in USD
* `08xx` — arbitrage path definitions (`0801`) and path status (`0802`; same DDL family as `0801`)
* `09xx` — arbitrage opportunities

| Value  | Table                                                    | Description                                                                                                                             | Notes                                                                                                        |
| ------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `0101` | `blockdb_evm.b0101_blocks_v1`                            | Canonical block headers and integrity metadata.                                                                                         | [`POST /evm/raw/blocks`](/api-reference/evm/primitives/blocks)                                               |
| `0102` | `blockdb_evm.b0102_transactions_v1`                      | Executed transactions with gas, status, and calldata.                                                                                   | [`POST /evm/raw/transactions`](/api-reference/evm/primitives/transactions)                                   |
| `0103` | `blockdb_evm.b0103_logs_v1`                              | Event logs emitted by smart contracts.                                                                                                  | [`POST /evm/raw/logs`](/api-reference/evm/primitives/logs)                                                   |
| `0111` | `blockdb_evm.b0111_internal_transactions_v1`             | Internal transactions (call traces).                                                                                                    | [`POST /evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions)                 |
| `0121` | `blockdb_evm.b0121_contracts_v1`                         | Contract deployments (CREATE/CREATE2), keyed by `contract_id`.                                                                          | [`POST /evm/raw/contracts`](/api-reference/evm/primitives/contracts)                                         |
| `0122` | `blockdb_evm.b0122_function_results_v1`                  | Contract call return values versioned by block.                                                                                         | [`POST /evm/raw/function-results`](/api-reference/evm/primitives/function-results)                           |
| `0201` | `blockdb_evm.b0201_erc20_tokens_v1`                      | ERC-20 token metadata.                                                                                                                  | [`POST /evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20)                                |
| `0202` | `blockdb_evm.b0202_erc721_tokens_v1`                     | ERC-721 collection metadata.                                                                                                            | [`POST /evm/entities/tokens/erc721`](/api-reference/evm/entities/tokens-erc721)                              |
| `0203` | `blockdb_evm.b0203_erc1155_tokens_v1`                    | ERC-1155 contract metadata.                                                                                                             | [`POST /evm/entities/tokens/erc1155`](/api-reference/evm/entities/tokens-erc1155)                            |
| `0211` | `blockdb_evm.b0211_liquidity_pools_v1`                   | Liquidity pool registry.                                                                                                                | [`POST /evm/entities/pools`](/api-reference/evm/entities/pools)                                              |
| `0212` | `blockdb_evm.b0212_liquidity_pools_fee_terms_v1`         | Versioned pool fee terms.                                                                                                               | [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms)                                |
| `0301` | `blockdb_evm.b0301_liquidity_pools_reserves_v1`          | Pool reserve / state snapshots. Companion details: `b0301_liquidity_pools_reserves_details_v1` (join on `snapshot_id` = `_tracing_id`). | [`POST /evm/reserves`](/api-reference/evm/reserves/reserves)                                                 |
| `0302` | `blockdb_evm.b0302_token_to_token_prices_swap_prints_v1` | Executed swap prints (realized prices).                                                                                                 | [`POST /evm/prices/spot/crypto/prints`](/api-reference/evm/prices/crypto/prices-spot-prints)                 |
| `0303` | `blockdb_evm.b0303_liquidity_pools_swap_fees_v1`         | Per-swap fee accounting.                                                                                                                | [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees)                                                 |
| `0304` | `blockdb_evm.b0304_token_transfers_v1`                   | Token transfers (native, ERC-20/721/1155).                                                                                              | [`POST /evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers)                        |
| `0305` | `blockdb_evm.b0305_flash_loan_prints_v1`                 | Flash loan borrow/repay prints.                                                                                                         | [`POST /evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints)                           |
| `0404` | `blockdb_evm.b0404_token_to_token_prices_ohlc_v1`        | Time-bucketed OHLC per pool and direction.                                                                                              | [`POST /evm/prices/spot/crypto/ohlc`](/api-reference/evm/prices/crypto/prices-spot-ohlc)                     |
| `0405` | `blockdb_evm.b0405_token_to_token_vwap_v1`               | Time-bucketed token-to-token VWAP.                                                                                                      | [`POST /evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap)                     |
| `0411` | `blockdb_evm.b0411_liquidity_pools_yields_v1`            | Pool yield / ROI predictions.                                                                                                           | [`POST /evm/yields`](/api-reference/evm/yields/yields)                                                       |
| `0505` | `blockdb_evm.b0505_token_to_token_cross_pool_vwap_v1`    | Cross-venue token-to-token VWAP (all pools aggregated).                                                                                 | [`POST /evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) |
| `0605` | `blockdb_evm.b0605_token_to_fiat_vwap`                   | Token-to-USD VWAP time buckets.                                                                                                         | [`POST /evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat)                    |
| `0701` | `blockdb_evm.b0701_liquidity_pools_tvl_usd_v1`           | Pool TVL snapshots in USD.                                                                                                              | [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd)                                                            |
| `0801` | `blockdb_evm.b0801_arb_paths_v1`                         | Arbitrage path definitions (topology).                                                                                                  | [`POST /evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                                              |
| `0802` | `blockdb_evm.b0801_arb_path_status_v1`                   | Path active/inactive status events. Same DDL family as `0801`.                                                                          | [`POST /evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)                                  |
| `0901` | `blockdb_evm.b0901_arb_opportunities_v1`                 | Arbitrage opportunities per path and position.                                                                                          | [`POST /evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities)                              |

### Usage Notes

* For a full tabular index (same IDs and tables), see [Dataset index](/data-catalog/evm/dataset-index).
* Responses that expose a `dataset` field use one of the identifiers above (or the full table name, e.g. `blockdb_evm.b0201_erc20_tokens_v1`).
* New datasets follow the same prefix scheme; clients should tolerate unknown IDs to remain forward compatible.
* Use this enumeration to drive UI labels and access control lists rather than hardcoding endpoint prefixes.


# Digital Exchange
Source: https://docs.blockdb.io/api-reference/enumerations/digital-exchange

Enumerates decentralized exchange (DEX) protocol identifiers used across price feeds and pool metadata.

An enumeration of supported decentralized exchange protocol IDs. These identifiers map to AMM protocols and DEX implementations across supported EVM chains. Rollout narrative and lifecycle details remain on the [Data Catalog Coverage](/data-catalog/overview/coverage) page.

***

### Values

| Value | Description    | Notes                                | Status           |
| ----- | -------------- | ------------------------------------ | ---------------- |
| `2`   | Uniswap V2     | Constant product (x·y=k).            | ✅ Supported      |
| `3`   | Uniswap V3     | Concentrated liquidity.              | ✅ Supported      |
| `4`   | Uniswap V4     | Hook-enabled architecture.           | ✅ Supported      |
| `12`  | Balancer V2    | Weighted/stable pools.               | 🔵 Investigation |
| `13`  | Balancer V3    | Next-generation Balancer pools.      | 🔵 Investigation |
| `22`  | SushiSwap V2   | Fork of Uniswap V2.                  | ✅ Supported      |
| `23`  | SushiSwap V3   | Concentrated liquidity.              | ✅ Supported      |
| `32`  | PancakeSwap V2 | Constant product AMM.                | ✅ Supported      |
| `33`  | PancakeSwap V3 | Concentrated liquidity.              | ✅ Supported      |
| `61`  | Maverick V1    | Maverick V1 decentralized exchange.  | 🔵 Investigation |
| `62`  | Maverick V2    | Maverick V2 decentralized exchange.  | 🔵 Investigation |
| `81`  | ShibaSwap V1   | ShibaSwap V1 decentralized exchange. | ✅ Supported      |
| `82`  | ShibaSwap V2   | ShibaSwap V2 decentralized exchange. | ✅ Supported      |

### Additional DEX protocols (roadmap)

The protocols below appear in the [Data Catalog Coverage](/data-catalog/overview/coverage) roadmap. `exchange_id` values are listed in the table above only once they are part of this public API enumeration.

| Protocol                 | Status           |
| ------------------------ | ---------------- |
| **Curve**                | 🔵 Investigation |
| **Joe V2**               | 🔵 Investigation |
| **Joe V2.1**             | 🔵 Investigation |
| **Joe V2.2**             | 🔵 Investigation |
| **BaseSwap**             | 🔵 Investigation |
| **Aerodrome Slipstream** | 🔵 Investigation |
| **Aerodrome V1**         | 🔵 Investigation |
| **Velodrome V1**         | 🔵 Investigation |
| **Velodrome V2**         | 🔵 Investigation |
| **Velodrome V3**         | 🔵 Investigation |
| **PulseX V1**            | 🔵 Investigation |
| **PulseX V2**            | 🔵 Investigation |

### Usage Notes

* Exchange IDs map to protocol implementations, not individual pool addresses. Use these identifiers when filtering by `exchange_id` in reserves and pricing endpoints.
* Status here matches the coverage table; see [Data Catalog Coverage](/data-catalog/overview/coverage) for how protocols roll out across networks.
* Additional protocols may be added over time; clients should gracefully handle unknown exchange IDs.

<Callout icon="lightbulb">
  Planning a new DEX integration or need a protocol prioritized? Email **[support@blockdb.io](mailto:support@blockdb.io)** to talk through scope and timelines with the team.
</Callout>


# Fiat Currency
Source: https://docs.blockdb.io/api-reference/enumerations/fiat-currency

Fiat codes available for quote currency conversions.

## FiatCurrency Enumeration

Defines the ISO 4217 fiat codes that can be referenced in price descriptors, quotes, and conversions.

| Value | Description          | Notes                               |
| ----- | -------------------- | ----------------------------------- |
| `USD` | United States Dollar | ISO 4217 code `USD`; default quote. |

### Usage Notes

* Additional fiat codes may be added over time; unknown values should be rejected gracefully.
* Fiat descriptors may include supplementary metadata (e.g., display `symbol`), but only the `code` is required.


# Market Kind
Source: https://docs.blockdb.io/api-reference/enumerations/market-kind

Market classification values for centralized exchange data.

## MarketKind Enumeration

Identifies the market surface targeted by price endpoints and discovery entries.

| Value  | Description                                                                | Notes           |
| ------ | -------------------------------------------------------------------------- | --------------- |
| `spot` | Real-time and historical spot markets derived from on-chain DEX liquidity. | Default surface |

### Usage Notes

* Future releases may introduce additional market kinds (e.g., `derivative`, `options`).
* Requests specifying unsupported values return `400 Bad Request`.


# Enumerations Overview
Source: https://docs.blockdb.io/api-reference/enumerations/overview

Reference tables for chain IDs, asset classes, exchange types, and other canonical identifiers.

## Overview

Enumerations provide canonical reference data used across BlockDB API requests and responses. These identifiers ensure consistent data classification and enable filtering across datasets. All enumeration values are stable and versioned independently from dataset schemas.

### Enumeration Reference

| Enumeration                                                        | Description                                                           | Use Cases                                                           |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`Chain`](/api-reference/enumerations/chain)                       | Supported EVM chain IDs compatible with ChainList                     | Filter datasets by network, specify `chain_id` in all requests      |
| [`Digital Exchange`](/api-reference/enumerations/digital-exchange) | DEX protocol identifiers for pools and price feeds                    | Filter reserves and pricing data by exchange type                   |
| [`Dataset ID`](/api-reference/enumerations/dataset-id)             | Canonical dataset identifiers mapping to API endpoints                | Reference datasets in lineage and catalog queries                   |
| [`Pool Type`](/api-reference/enumerations/pool-type)               | AMM pool archetype classifications                                    | Filter pools and reserves by liquidity model                        |
| [`Transfer Type`](/api-reference/enumerations/transfer-type)       | Token transfer mechanism codes (native tx, internal, ERC-20/721/1155) | Interpret and filter `transfer_type` on the token transfers dataset |
| [`Asset Class`](/api-reference/enumerations/asset-class)           | Asset type identifiers (ERC-20, fiat, native, index)                  | Construct price request descriptors                                 |
| [`Fiat Currency`](/api-reference/enumerations/fiat-currency)       | ISO 4217 fiat currency codes                                          | Specify quote currencies in pricing endpoints                       |
| [`Market Kind`](/api-reference/enumerations/market-kind)           | Market classification (spot, derivative, etc.)                        | Scope pricing queries to specific market surfaces                   |

### Parameter Conventions

* Enumeration values are case-sensitive and must match exactly as documented
* Use numeric IDs for chain, exchange, pool type, and transfer type enumerations
* Use string codes for asset class, fiat currency, and market kind
* All enumeration values are immutable within a major version

### Usage Guidance

* **Cache enumerations client-side** — values change infrequently and can be cached for extended periods
* **Validate before requests** — check that enumeration values exist before constructing API requests to avoid `400 Bad Request` errors
* **Reference in filters** — use enumeration IDs in request body filters (e.g., `exchange_ids`, `pool_type_ids`) rather than hardcoding values
* **Monitor updates** — subscribe to [Release Notes](/release-notes/home) for new enumeration values or deprecations

### See Also

* [Chain](/api-reference/enumerations/chain) — EVM network identifiers
* [Digital Exchange](/api-reference/enumerations/digital-exchange) — DEX protocol identifiers
* [Dataset ID](/api-reference/enumerations/dataset-id) — Dataset catalog mapping
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications
* [Transfer Type](/api-reference/enumerations/transfer-type) — Token transfer mechanism codes
* [Asset Class](/api-reference/enumerations/asset-class) — Asset type system
* [Fiat Currency](/api-reference/enumerations/fiat-currency) — Currency codes
* [Market Kind](/api-reference/enumerations/market-kind) — Market classifications


# Pool Type
Source: https://docs.blockdb.io/api-reference/enumerations/pool-type

Recognized AMM pool archetypes across supported chains.

Integer codes identifying automated market maker pool archetypes.

***

### Values

| Value  | Description                 | Notes                                                                                                                   |
| ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `201`  | Uniswap V2 pool             | `dex_type_id=2` · flat fee `0.30%` (`total_fee=0.003`)                                                                  |
| `301`  | Uniswap V3 pool (0.01%)     | `dex_type_id=3` · tick spacing · `total_fee=0.0001`                                                                     |
| `302`  | Uniswap V3 pool (0.05%)     | `dex_type_id=3` · tick spacing · `total_fee=0.0005`                                                                     |
| `303`  | Uniswap V3 pool (0.30%)     | `dex_type_id=3` · tick spacing · `total_fee=0.003`                                                                      |
| `304`  | Uniswap V3 pool (1.00%)     | `dex_type_id=3` · tick spacing · `total_fee=0.01`                                                                       |
| `2201` | SushiSwap V2 pool           | `dex_type_id=22` · `total_fee=0.003` (example split: `user_fee=0.0025`, `protocol_fee=0.0005`)                          |
| `3201` | PancakeSwap V2 pool         | `dex_type_id=32` · `total_fee=0.0025` (example split: `user_fee=0.0017`, `protocol_fee=0.000225`, `extra_fee=0.000575`) |
| `3301` | PancakeSwap V3 pool (0.01%) | `dex_type_id=33` · tick spacing · `total_fee=0.0001`                                                                    |
| `3302` | PancakeSwap V3 pool (0.05%) | `dex_type_id=33` · tick spacing · `total_fee=0.0005`                                                                    |
| `3303` | PancakeSwap V3 pool (0.25%) | `dex_type_id=33` · tick spacing · `total_fee=0.0025`                                                                    |
| `3304` | PancakeSwap V3 pool (1.00%) | `dex_type_id=33` · tick spacing · `total_fee=0.01`                                                                      |
| `8101` | ShibaSwap V1 pool           | `dex_type_id=81` · flat fee `0.30%` (`total_fee=0.003`)                                                                 |


# Arbitrage Opportunities
Source: https://docs.blockdb.io/api-reference/evm/arbitrage/arb-opportunities

POST https://api.blockdb.io/v1/evm/arb/opportunities
Query arbitrage opportunity snapshots (dataset 0901): per-hop amounts, token profit, and USD profit.

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0901 - Arbitrage Opportunities`](/data-catalog/evm/arbitrage/arb-opportunities)
* **Description:** Opportunities computed for active paths at a specific `(block_number, tx_index, log_index)`; ties to `path_id` and `is_reversed`.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Opportunities-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0901_arb_opportunities_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Opportunities-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0901_arb_opportunities_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Range filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  Provide **either** a block range **or** a time range **or** filter by `path_ids`.\
  Do not mix block and timestamp ranges in one request.
</Warning>

#### Direct selectors

<ParamField type="string[]">
  Filter by 32-byte `path_id` values (hex, no `0x` prefix).
</ParamField>

#### Pagination

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor from a previous response.
</ParamField>

## Response fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Echo of `path_ids`, pagination, etc.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Opportunity records matching the request.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Observation block.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the observation.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="data.path_id" type="string">
  32-byte path id (hex, no `0x`).
</ResponseField>

<ResponseField name="data.is_reversed" type="boolean">
  `true` if the path was evaluated in the reversed direction.
</ResponseField>

<ResponseField name="data.pool_uids" type="string[]">
  Pool UIDs in evaluated (directional) order (hex).
</ResponseField>

<ResponseField name="data.token_path" type="string[]">
  Token addresses in evaluated order (hex).
</ResponseField>

<ResponseField name="data.amounts" type="string[]">
  Per-hop amounts as decimal strings, aligned with `token_path`.
</ResponseField>

<ResponseField name="data.profit_in_tokens" type="string">
  Estimated profit in `token_path[0]` units.
</ResponseField>

<ResponseField name="data.token_vwap_usd" type="string">
  USD price of `token_path[0]`.
</ResponseField>

<ResponseField name="data.profit_in_usd" type="string">
  Estimated profit in USD.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row tracing id (hex, no `0x`).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Parent tracing ids.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of rows in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/arb/opportunities" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/arb/opportunities");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/arb/opportunities", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/arb/opportunities",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={"chain_id": 1, "from_block": 21000000, "to_block": 21001000, "limit": 25}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/arb/opportunities", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "from_block": 21000000,
      "to_block": 21001000,
      "limit": 25
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/arb/opportunities", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "path_ids": [],
        "limit": 25,
        "cursor": null
      }
    },
    "data": [
      {
        "block_number": 21000500,
        "block_time": "2025-11-11T12:00:00Z",
        "tx_index": 8,
        "log_index": 4,
        "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
        "is_reversed": false,
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
          "11b815acc87f6f89741a636d1ebfcea40876f8f0000000000000000000000000"
        ],
        "token_path": [
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
        ],
        "amounts": [
          "1000000000000000000",
          "3500000000",
          "1000500000000000000"
        ],
        "profit_in_tokens": "50000000000000000",
        "token_vwap_usd": "3200.50",
        "profit_in_usd": "160.025",
        "_tracing_id": "0901c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0801c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T12:00:05Z",
        "_updated_at": "2025-11-11T12:00:05Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Arbitrage Path Status
Source: https://docs.blockdb.io/api-reference/evm/arbitrage/arb-path-status

POST https://api.blockdb.io/v1/evm/arb/path-status
Query path active/inactive status events per path_id (dataset 0802).

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0802 - Arb Path Status`](/data-catalog/evm/arbitrage/arb-paths#arb-path-status-b0801_arb_path_status_v1)
* **Description:** Path status events (`b0801_arb_path_status_v1`): active/inactive transitions keyed by `(path_id, block_number, tx_index, log_index)`; `trigger_pool_uid` identifies the pool whose TVL/state change produced the event.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0801_arb_path_status_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0801_arb_path_status_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Range filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  Provide **either** a block range **or** a time range **or** filter by `path_ids`.\
  Do not mix block and timestamp ranges in one request.
</Warning>

#### Direct selectors

<ParamField type="string[]">
  Filter by 32-byte `path_id` values (hex, no `0x` prefix). Cross-reference [Arbitrage paths](/data-catalog/evm/arbitrage/arb-paths) for path definitions.
</ParamField>

<ParamField type="boolean">
  When set, return only rows where the path became active (`true`) or inactive (`false`).
</ParamField>

#### Pagination

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor from a previous response.
</ParamField>

## Response fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Echo of `path_ids`, `is_active`, pagination, etc.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Path status events matching the request.
</ResponseField>

<ResponseField name="data.path_id" type="string">
  32-byte path id (hex, no `0x`).
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block of the status event.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the event row.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="data.is_active" type="boolean">
  Whether the path is active after this event.
</ResponseField>

<ResponseField name="data.trigger_pool_uid" type="string">
  32-byte pool UID whose state change triggered the status update (hex, no `0x`).
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row tracing id (hex, no `0x`).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Parent tracing ids.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp (ISO-8601).
</ResponseField>

#### Envelope

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of rows in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/arb/path-status" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/arb/path-status");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/arb/path-status", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/arb/path-status",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={"chain_id": 1, "from_block": 21000000, "to_block": 21001000, "limit": 25}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/arb/path-status", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "from_block": 21000000,
      "to_block": 21001000,
      "limit": 25
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/arb/path-status", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "path_ids": [],
        "limit": 25,
        "cursor": null
      }
    },
    "data": [
      {
        "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
        "block_number": 21000800,
        "block_time": "2025-11-11T14:00:00Z",
        "tx_index": 5,
        "log_index": 2,
        "is_active": true,
        "trigger_pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "_tracing_id": "0802c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0801c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T14:00:01.000Z",
        "_updated_at": "2025-11-11T14:00:01.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Arbitrage Paths
Source: https://docs.blockdb.io/api-reference/evm/arbitrage/arb-paths

POST https://api.blockdb.io/v1/evm/arb/paths
Query arbitrage path definitions: pool UID cycle and token cycle per path_id (dataset 0801).

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0801 - Arbitrage Paths`](/data-catalog/evm/arbitrage/arb-paths)
* **Description:** Returns arbitrage path rows. Binary fields are returned as hex strings (no `0x` prefix) in JSON.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0701_arb_paths_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0701_arb_paths_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Range filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  Provide **either** a block range **or** a time range **or** filter by `path_ids` (direct selectors).\
  Do not mix block and timestamp ranges in one request. Invalid combinations return HTTP 400.
</Warning>

#### Direct selectors

<ParamField type="string[]">
  Filter by 32-byte `path_id` values (hex string, no `0x` prefix).
</ParamField>

#### Pagination

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor from a previous response.
</ParamField>

## Response fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (`path_ids`, pagination, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Path definition records matching the request.
</ResponseField>

<ResponseField name="data.path_id" type="string">
  32-byte path identifier (hex, no `0x`).
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block where the path was first observed.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of that block.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="data.pool_uids" type="string[]">
  Pool UIDs in canonical cycle order (hex, 32-byte each).
</ResponseField>

<ResponseField name="data.token_cycle" type="string[]">
  Token addresses in canonical cycle order (hex, 20-byte each), e.g. (A,B,A) or (A,B,C,A).
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row tracing id (hex, no `0x`).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Parent tracing ids.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of rows in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/arb/paths" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/arb/paths");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":21000000,\"to_block\":21001000,\"limit\":25}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/arb/paths", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/arb/paths",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={"chain_id": 1, "from_block": 21000000, "to_block": 21001000, "limit": 25}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/arb/paths", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "from_block": 21000000,
      "to_block": 21001000,
      "limit": 25
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 21000000,
    "to_block": 21001000,
    "limit": 25
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/arb/paths", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 21000000,
        "to_block": 21001000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "path_ids": [],
        "limit": 25,
        "cursor": null
      }
    },
    "data": [
      {
        "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
        "block_number": 21000500,
        "block_time": "2025-11-11T12:00:00Z",
        "tx_index": 3,
        "log_index": 12,
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
          "11b815acc87f6f89741a636d1ebfcea40876f8f0000000000000000000000000"
        ],
        "token_cycle": [
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
        ],
        "_tracing_id": "0801c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0301c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T12:00:05Z",
        "_updated_at": "2025-11-11T12:00:05Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Arbitrage Overview
Source: https://docs.blockdb.io/api-reference/evm/arbitrage/overview

Query arbitrage path topology, path status changes, and opportunity snapshots.

## Overview

Arbitrage datasets describe cyclic routes across pools ([`0801`](/data-catalog/evm/arbitrage/arb-paths)), activation events for those routes ([`0802`](/data-catalog/evm/arbitrage/arb-paths#arb-path-status-b0801_arb_path_status_v1)), and evaluated profit snapshots at concrete chain positions ([`0901`](/data-catalog/evm/arbitrage/arb-opportunities)).

### Endpoint matrix

| Endpoint                                                                        | Summary                                                  | Dataset ID |
| ------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| [`POST /evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                 | Path definitions (`path_id`, `pool_uids`, `token_cycle`) | `0801`     |
| [`POST /evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)     | Active/inactive status events per `path_id`              | `0802`     |
| [`POST /evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities) | Profit and token amounts per path and position           | `0901`     |

Dataset **`0802`** (path status) is documented alongside **`0801`** on the [arbitrage paths](/data-catalog/evm/arbitrage/arb-paths) catalog page.

### Related

* [Dataset ID](/api-reference/enumerations/dataset-id)
* [Arbitrage catalog](/data-catalog/evm/arbitrage/arb-paths)


# Pools · Fee Terms
Source: https://docs.blockdb.io/api-reference/evm/entities/fee-terms

POST https://api.blockdb.io/v1/evm/entities/pools/fee-terms
Read versioned AMM pool fee configuration (total fee and fee-split terms) for joinable pool economics.

## Overview

* **Dataset ID:** [`0212 - Liquidity Pool Fee Terms`](/data-catalog/evm/entities/liquidity-pools-fee-terms)
* **Description:** Retrieves versioned fee terms for liquidity pools, including the total swap fee fraction (e.g., `0.003`) and optional split fractions across LP/user, protocol, and extra recipients.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Fee-Terms-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0212_liquidity_pools_fee_terms_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Fee-Terms-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0212_liquidity_pools_fee_terms_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="number[]">
  Filter fee terms by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by BlockDB pool identifiers (`uid` from `/evm/entities/pools`).
</ParamField>

<ParamField type="string[]">
  Filter by pool contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by protocol-specific pool identifiers (e.g., Uniswap V4 `pool_id`).
</ParamField>

<ParamField type="number[]">
  Filter by AMM archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (selectors, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of pool fee-terms records matching the request.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier (`uid` from `/evm/entities/pools`).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height where the fee-terms record is anchored.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the `blocks` table for easier aggregation.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index of the parent transaction within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Position of the log within the transaction.
</ResponseField>

<ResponseField name="data.total_fee" type="string | null">
  Total fee fraction (e.g., `0.003` = 0.30%). Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.user_fee" type="string | null">
  Absolute fee fraction allocated to LPs/users (same units as `total_fee`). Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.protocol_fee" type="string | null">
  Absolute fee fraction allocated to protocol/treasury (same units as `total_fee`). Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.extra_fee" type="string | null">
  Absolute fee fraction allocated to extra destinations (burn, staking, etc.) (same units as `total_fee`). Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/entities/pools/fee-terms" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19010000,
    "pool_addresses": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
    ],
    "limit": 250
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19010000,\"pool_addresses\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f564\"],\"limit\":250}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/entities/pools/fee-terms");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);
      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19010000,\"pool_addresses\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f564\"],\"limit\":250}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/entities/pools/fee-terms", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/entities/pools/fee-terms",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1,
   'from_block': 19000000,
   'to_block': 19010000,
   'pool_addresses': ['88e6a0c2ddd26feeb64f039a2c41296fcb3f564'],
   'limit': 250}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/entities/pools/fee-terms", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19010000,
    "pool_addresses": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
    ],
    "limit": 250
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19010000,
    "pool_addresses": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
    ],
    "limit": 250
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/entities/pools/fee-terms", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 19000000,
        "to_block": 19010000
      },
      "resolved_window": {
        "from_block": 19000000,
        "to_block": 19010000
      },
      "filters": {
        "pool_addresses": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
        ],
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 19001234,
        "block_time": "2025-12-20T12:34:56Z",
        "tx_index": 7,
        "log_index": 12,
        "total_fee": "0.003000000000000000",
        "user_fee": "0.003000000000000000",
        "protocol_fee": "0.000000000000000000",
        "extra_fee": "0.000000000000000000",
        "_tracing_id": "0204c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-12-20T12:35:01Z",
        "_updated_at": "2025-12-20T12:35:01Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Tokens & Liquidity Overview
Source: https://docs.blockdb.io/api-reference/evm/entities/overview

Discover tokens and liquidity pools with standardized metadata and identifiers.

## Overview

The Tokens & Liquidity suite provides access to token registries and automated market maker (AMM) pool metadata. These endpoints deliver standardized identifiers and classification data that enable consistent cross-dataset joins and filtering. All records include lineage fields linking back to on-chain creation events.

### Endpoint Matrix

| Endpoint                                                                          | Summary                          | Dataset ID | Typical Latency |
| --------------------------------------------------------------------------------- | -------------------------------- | ---------- | --------------- |
| [`POST /evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20)     | ERC-20 token registry            | `0201`     | \< 200 ms       |
| [`POST /evm/entities/tokens/erc721`](/api-reference/evm/entities/tokens-erc721)   | ERC-721 collection registry      | `0202`     | \< 200 ms       |
| [`POST /evm/entities/tokens/erc1155`](/api-reference/evm/entities/tokens-erc1155) | ERC-1155 contract registry       | `0203`     | \< 200 ms       |
| [`POST /evm/entities/pools`](/api-reference/evm/entities/pools)                   | AMM pool registry                | `0211`     | \< 200 ms       |
| [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms)     | Pool fee configuration over time | `0212`     | \< 200 ms       |

### Parameter Conventions

<ParamField type="string">
  ERC-20 contract address filter (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  BlockDB pool identifier for direct pool lookups.
</ParamField>

<ParamField type="string[]">
  Pool contract addresses for AMM pools.
</ParamField>

<ParamField type="number">
  Starting block number (inclusive) for creation-time filtering.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for creation-time filtering.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="number[]">
  Pool type filters. Use [Pool Type enumeration](/api-reference/enumerations/pool-type) values.
</ParamField>

### Usage Guidance

* **Start with pools** — Use `/evm/entities/pools` to discover available liquidity before querying reserves
* **Join with reserves** — Link pool metadata to reserve snapshots via `pool_uid` for complete liquidity analysis
* **Use token addresses** — the ERC-20 endpoint accepts contract addresses for direct lookups
* **Filter by creation time** — Use block/time ranges to find newly created tokens or pools
* **Cache token metadata** — Token names, symbols, and decimals are immutable; cache aggressively

### Common Patterns

**Find all ERC-20 tokens created in a time range:**

```json theme={null}
{
  "chain_id": 1,
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z"
}
```

**Lookup specific pool:**

```json theme={null}
{
  "chain_id": 1,
  "pool_addresses": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
  ]
}
```

**Filter pools by type:**

```json theme={null}
{
  "chain_id": 1,
  "pool_type_ids": [
    201,
    301,
    302,
    303,
    304
  ],
  "from_block": 18000000
}
```

### Dataset Relationships

* **Tokens → Pools**: Join ERC-20 tokens to pools via token addresses in pool metadata
* **Pools → Reserves**: Link pool metadata to reserve snapshots using `pool_uid`
* **Pools → Fee Terms**: Join pool metadata to fee terms using `pool_uid` for pool economics
* **Tokens → Prices**: Use token addresses in pricing endpoints to get market data

### See Also

* [`POST /evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20) — ERC-20 token registry
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — AMM pool registry
* [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms) — Pool fee configuration
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Pool reserve snapshots
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications
* [Digital Exchange](/api-reference/enumerations/digital-exchange) — DEX protocol identifiers


# Pools
Source: https://docs.blockdb.io/api-reference/evm/entities/pools

POST https://api.blockdb.io/v1/evm/entities/pools
List AMM pools with reserves, fee tiers, and routing hints.

## Overview

* **Dataset ID:** [`0211 - Liquidity Pools`](/data-catalog/evm/entities/liquidity-pools)
* **Description:** Canonical list of pools; child time-series tables FK to blockdb\_evm.b0211\_liquidity\_pools\_v1(pool\_uid).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0211_liquidity_pools_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0211_liquidity_pools_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="string">
  Specific pool contract address to return (hex string, 20 bytes, no `0x` prefix). May be used on its own, without a block or time range.
</ParamField>

<ParamField type="string[]">
  Internal BlockDB pool ids to return (each a 32-byte hex string, no `0x` prefix). May be used on its own, without a block or time range.
</ParamField>

<ParamField type="number[]">
  Filter snapshots by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="number[]">
  Filter pools by archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of pool objects. Each row matches the linked dataset.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  Internal BlockDB pool id (32-byte hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block number where the pool was first recognized.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Zero-based log index within the transaction.
</ResponseField>

<ResponseField name="data.factory" type="string">
  Factory or pool-manager contract address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.tokens" type="string[]">
  Token contract addresses that compose the pool (each hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.contract_id" type="string | null">
  Incarnation ID for v2/v3 pools: 20B address + 4B creation block + 2B tx\_index (hex-encoded). NULL for v4-style pools.
</ResponseField>

<ResponseField name="data.contract_address" type="string | null">
  On-chain pool contract address when applicable (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.pool_id" type="string | null">
  Protocol-specific pool id when applicable (for example Uniswap V4), hex string without `0x`.
</ResponseField>

<ResponseField name="data.pairnum" type="number | null">
  Ordinal for the pair within the exchange, when applicable.
</ResponseField>

<ResponseField name="data.asset_managers" type="string[] | null">
  Asset manager contract addresses for Balancer-style pools (hex strings), or `null`.
</ResponseField>

<ResponseField name="data.amp" type="number | null">
  Amplification parameter for stable pools, when applicable.
</ResponseField>

<ResponseField name="data.weights" type="number[] | null">
  Token weights for weighted pools, when applicable.
</ResponseField>

<ResponseField name="data.tick_spacing" type="number | null">
  Tick spacing for concentrated-liquidity pools, when applicable.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents (hex strings).
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/entities/pools" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "exchange_ids": [
      2,
      3
    ],
    "pool_type_ids": [
      201,
      302,
      3303
    ],
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"exchange_ids\":[2,3],\"pool_type_ids\":[201,302,3303],\"contract_address\":\"1234567890abcdef1234567890abcdef12345678\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/entities/pools");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"exchange_ids\":[2,3],\"pool_type_ids\":[201,302,3303],\"contract_address\":\"1234567890abcdef1234567890abcdef12345678\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/entities/pools", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/entities/pools",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'contract_address': '1234567890abcdef1234567890abcdef12345678',
   'chain_id': 1,
   'exchange_ids': [2, 3],
   'from_block': 12345678,
   'from_timestamp': '2025-10-29T00:00:00Z',
   'pool_type_ids': [201, 302, 3303],
   'to_block': 12345999,
   'to_timestamp': '2025-11-11T00:00:00Z'}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/entities/pools", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "exchange_ids": [
      2,
      3
    ],
    "pool_type_ids": [
      201,
      302,
      3303
    ],
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "exchange_ids": [
      2,
      3
    ],
    "pool_type_ids": [
      201,
      302,
      3303
    ],
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/entities/pools", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "contract_address": "1234567890abcdef1234567890abcdef12345678",
        "pool_uids": null,
        "exchange_ids": [
          1,
          2
        ],
        "pool_type_ids": [
          1,
          2,
          4
        ]
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 2,
        "block_number": 567890,
        "block_time": "2018-07-07T12:34:56.000Z",
        "tx_index": 4,
        "log_index": 2,
        "factory": "1f98431c8ad98523631ae4a59f267346ea31f984",
        "contract_id": "88e6a0c2ddd26feeb64f039a2c41296fcb3f564000000000000",
        "tokens": [
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        ],
        "contract_address": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
        "pool_id": null,
        "pairnum": 42,
        "asset_managers": null,
        "amp": null,
        "weights": [
          0.5,
          0.5
        ],
        "tick_spacing": null,
        "_tracing_id": "0211000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103000000000000000000000000000000000001",
          "0103000000000000000000000000000000000002"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Tokens · ERC-1155
Source: https://docs.blockdb.io/api-reference/evm/entities/tokens-erc1155

POST https://api.blockdb.io/v1/evm/entities/tokens/erc1155
Discover ERC-1155 Multi Token contracts with metadata and provenance fields.

## Overview

* **Dataset ID:** [`0203 - ERC-1155 Tokens`](/data-catalog/evm/entities/erc1155-tokens)
* **Description:** Catalog of ERC-1155 Multi Token contracts (EIP-1155); one contract can have many token types.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC1155-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0203_erc1155_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC1155-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0203_erc1155_tokens_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or an explicit contract address filter.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Contract Address Filter

<ParamField type="string">
  Specific ERC-1155 token contract address to return (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (contract addresses, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element matches the linked dataset (no `chain_id` column — use `meta.chain_id`).
</ResponseField>

<ResponseField name="data.contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex). Disambiguates redeployed contracts at the same address.
</ResponseField>

<ResponseField name="data.contract_address" type="string">
  The Ethereum contract address of the ERC-1155 multi-token contract.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block number of the contract recognition event.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the blocks table for easier selection and grouping.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the genesis block.
</ResponseField>

<ResponseField name="data.name" type="string | null">
  Contract name from `name()` (optional in EIP-1155).
</ResponseField>

<ResponseField name="data.symbol" type="string | null">
  Contract symbol from `symbol()` (optional in EIP-1155).
</ResponseField>

<ResponseField name="data.decimals" type="number | null">
  Contract decimals from `decimals()` (optional in EIP-1155).
</ResponseField>

<ResponseField name="data.uri" type="string | null">
  URI from `uri(uint256)` (optional ERC1155Metadata\_URI). Clients replace `{id}` with token ID in hex (64 chars).
</ResponseField>

<ResponseField name="data.supports_metadata_uri" type="boolean | null">
  Whether the contract supports the ERC1155Metadata\_URI extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp, e.g. `"2025-11-11T18:42:15.123Z"`.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp in the same format.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/entities/tokens/erc1155" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "contract_address": "495f947276749ce646f68ac8c248420045cb7b5e"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"contract_address\":\"495f947276749ce646f68ac8c248420045cb7b5e\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/entities/tokens/erc1155");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"contract_address\":\"495f947276749ce646f68ac8c248420045cb7b5e\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/entities/tokens/erc1155", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/entities/tokens/erc1155",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          'chain_id': 1,
          'from_block': 12345678,
          'to_block': 12345999,
          'from_timestamp': '2025-10-29T00:00:00Z',
          'to_timestamp': '2025-11-11T00:00:00Z',
          'contract_address': '495f947276749ce646f68ac8c248420045cb7b5e'
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/entities/tokens/erc1155", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      from_timestamp: "2025-10-29T00:00:00Z",
      to_timestamp: "2025-11-11T00:00:00Z",
      contract_address: "495f947276749ce646f68ac8c248420045cb7b5e"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "contract_address": "495f947276749ce646f68ac8c248420045cb7b5e"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/entities/tokens/erc1155", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "contract_address": "495f947276749ce646f68ac8c248420045cb7b5e"
      }
    },
    "data": [
      {
        "contract_id": "495f947276749ce646f68ac8c248420045cb7b5e000000000000",
        "contract_address": "495f947276749ce646f68ac8c248420045cb7b5e",
        "block_number": 11579209,
        "block_time": "2021-10-15T12:00:00Z",
        "tx_index": 42,
        "name": "OpenSea Shared Storefront",
        "symbol": "OPENSTORE",
        "decimals": null,
        "uri": "https://api.opensea.io/api/v1/metadata/{id}",
        "supports_metadata_uri": true,
        "_tracing_id": "0203000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Tokens · ERC-20
Source: https://docs.blockdb.io/api-reference/evm/entities/tokens-erc20

POST https://api.blockdb.io/v1/evm/entities/tokens/erc20
Discover ERC-20 tokens with metadata, supply, and compliance fields.

## Overview

* **Dataset ID:** [`0201 - ERC-20 Tokens`](/data-catalog/evm/entities/erc20-tokens)
* **Description:** Catalog of ERC-20 token contracts (EIP-20).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or an explicit contract address filter.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Contract Address Filter

<ParamField type="string">
  Specific ERC-20 token contract address to return (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (contract addresses, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of token objects.
</ResponseField>

<ResponseField name="data.contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex). Disambiguates redeployed contracts at the same address.
</ResponseField>

<ResponseField name="data.contract_address" type="string">
  The Ethereum contract address of the token.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block number where the token record was first recognized.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the `blocks` table for easier selection and grouping.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the genesis block.
</ResponseField>

<ResponseField name="data.name" type="string | null">
  Token name from `name()` (optional in EIP-20).
</ResponseField>

<ResponseField name="data.symbol" type="string | null">
  Token symbol from `symbol()` (optional in EIP-20).
</ResponseField>

<ResponseField name="data.decimals" type="number | null">
  Token decimals from `decimals()` (optional in EIP-20).
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp, e.g. `"2025-11-11T18:42:15.123Z"`.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp in the same format.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/entities/tokens/erc20" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"contract_address\":\"1234567890abcdef1234567890abcdef12345678\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/entities/tokens/erc20");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"contract_address\":\"1234567890abcdef1234567890abcdef12345678\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/entities/tokens/erc20", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/entities/tokens/erc20",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'contract_address': '1234567890abcdef1234567890abcdef12345678',
   'chain_id': 1,
   'from_block': 12345678,
   'from_timestamp': '2025-10-29T00:00:00Z',
   'to_block': 12345999,
   'to_timestamp': '2025-11-11T00:00:00Z'}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/entities/tokens/erc20", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "contract_address": "1234567890abcdef1234567890abcdef12345678"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/entities/tokens/erc20", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "contract_address": "1234567890abcdef1234567890abcdef12345678"
      }
    },
    "data": [
      {
        "contract_id": "0000000000000000000000000000000000000001000000000000",
        "contract_address": "0000000000000000000000000000000000000001",
        "block_number": 567890,
        "block_time": "2018-07-07T12:34:56Z",
        "tx_index": 4,
        "name": "Token Name",
        "symbol": "TOKEN",
        "decimals": 18,
        "_tracing_id": "0201000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103000000000000000000000000000000000001",
          "0103000000000000000000000000000000000002"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Tokens · ERC-721
Source: https://docs.blockdb.io/api-reference/evm/entities/tokens-erc721

POST https://api.blockdb.io/v1/evm/entities/tokens/erc721
Discover ERC-721 (NFT) token collections with metadata and provenance fields.

## Overview

* **Dataset ID:** [`0202 - ERC-721 Tokens`](/data-catalog/evm/entities/erc721-tokens)
* **Description:** Catalog of ERC-721 NFT collection contracts (EIP-721).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC721-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0202_erc721_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC721-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0202_erc721_tokens_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or an explicit contract address filter.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Contract Address Filter

<ParamField type="string">
  Specific ERC-721 token contract address to return (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (contract addresses, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element matches the linked dataset (no `chain_id` column — use `meta.chain_id`).
</ResponseField>

<ResponseField name="data.contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex). Disambiguates redeployed contracts at the same address.
</ResponseField>

<ResponseField name="data.contract_address" type="string">
  The Ethereum contract address of the token collection.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block number of the collection-creation event.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the blocks table for easier selection and grouping.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the genesis block.
</ResponseField>

<ResponseField name="data.name" type="string | null">
  Collection name from `name()` (ERC721Metadata, optional).
</ResponseField>

<ResponseField name="data.symbol" type="string | null">
  Collection symbol from `symbol()` (ERC721Metadata, optional).
</ResponseField>

<ResponseField name="data.token_uri" type="string | null">
  Representative token URI or base URI for collection metadata (ERC721Metadata), if any.
</ResponseField>

<ResponseField name="data.supports_metadata" type="boolean | null">
  Whether the contract supports the ERC721Metadata extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="data.supports_enumerable" type="boolean | null">
  Whether the contract supports the ERC721Enumerable extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp, e.g. `"2025-11-11T18:42:15.123Z"`.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp in the same format.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/entities/tokens/erc721" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "contract_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"contract_address\":\"bc4ca0eda7647a8ab7c2061c2e118a18a936f13d\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/entities/tokens/erc721");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"contract_address\":\"bc4ca0eda7647a8ab7c2061c2e118a18a936f13d\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/entities/tokens/erc721", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/entities/tokens/erc721",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          'chain_id': 1,
          'from_block': 12345678,
          'to_block': 12345999,
          'from_timestamp': '2025-10-29T00:00:00Z',
          'to_timestamp': '2025-11-11T00:00:00Z',
          'contract_address': 'bc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/entities/tokens/erc721", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      from_timestamp: "2025-10-29T00:00:00Z",
      to_timestamp: "2025-11-11T00:00:00Z",
      contract_address: "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "contract_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/entities/tokens/erc721", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "contract_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
      }
    },
    "data": [
      {
        "contract_id": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d000000000000",
        "contract_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "block_number": 12287507,
        "block_time": "2021-04-22T23:43:17Z",
        "tx_index": 114,
        "name": "BoredApeYachtClub",
        "symbol": "BAYC",
        "token_uri": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/",
        "supports_metadata": true,
        "supports_enumerable": true,
        "_tracing_id": "0202000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer collections or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Flash Loan Prints
Source: https://docs.blockdb.io/api-reference/evm/flash-loans/flash-loan-prints

POST https://api.blockdb.io/v1/evm/flash-loans/prints
Read flash loan borrow/repay events (dataset 0305) with raw amounts and pool or vault attribution.

## Overview

* **Dataset ID:** [`0305 - Flash Loan Prints`](/data-catalog/evm/flash-loans/flash-loan-prints)
* **Description:** One row per borrowed token per on-chain flash loan event (V2-style flash swap, V3 Flash event, Balancer V2 Vault, etc.). `pool_uid` is NULL for vault-level events not tied to a single pool.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Flash-Loan-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0305_flash_loan_prints_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Flash-Loan-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0305_flash_loan_prints_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Range filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

<Warning>
  Provide **either** a block range **or** a time range **or** direct selectors (`pool_uids`, `flash_loan_source_addresses`, and/or `token_addresses`).\
  Do not mix block and timestamp ranges. Invalid combinations return HTTP 400.
</Warning>

#### Direct selectors

<ParamField type="string[]">
  Filter to pool UIDs (32-byte hex, no `0x`). Omitted or null `pool_uid` rows (vault-level) require other selectors if you need them.
</ParamField>

<ParamField type="string[]">
  Emitter contracts (20-byte hex, no `0x`): pool or vault that emitted the event.
</ParamField>

<ParamField type="string[]">
  Borrowed token addresses (20-byte hex, no `0x`).
</ParamField>

#### Pagination

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor from a previous response.
</ParamField>

#### Decimals-Adjusted Amounts

<ParamField type="boolean">
  Off by default. When set to `true`, the response includes `data.amount_borrowed`, `data.amount_repaid`, and `data.fee_amount` (decimals-adjusted, may be `null`) alongside the raw integer fields. Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency, so it is opt-in; when omitted or `false`, those fields are returned as `null` and only the always-present `*_raw` fields are populated.
</ParamField>

## Response fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Echo of selectors and pagination from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Flash loan print records matching the request.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height of the event.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the block.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="data.pool_uid" type="string | null">
  32-byte internal pool id (hex), or `null` for vault-level flash loans.
</ResponseField>

<ResponseField name="data.exchange_id" type="number | null">
  Present when `pool_uid` is set; otherwise `null`.
</ResponseField>

<ResponseField name="data.type_id" type="number | null">
  Pool type id when `pool_uid` is set; otherwise `null`.
</ResponseField>

<ResponseField name="data.flash_loan_source" type="string">
  20-byte address of the contract that emitted the event (hex, no `0x`).
</ResponseField>

<ResponseField name="data.token" type="string">
  20-byte ERC-20 token borrowed in this row (hex, no `0x`).
</ResponseField>

<ResponseField name="data.amount_borrowed_raw" type="string">
  Raw amount borrowed as a `uint256` integer in the borrowed token's smallest denomination. String-encoded.
</ResponseField>

<ResponseField name="data.amount_borrowed" type="string | null">
  Decimals-adjusted form of `amount_borrowed_raw` (resolved against `token`). `null` when decimals are unknown or `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.amount_repaid_raw" type="string">
  Raw amount repaid (borrowed + fee) as a `uint256` integer in the borrowed token's smallest denomination.
</ResponseField>

<ResponseField name="data.amount_repaid" type="string | null">
  Decimals-adjusted form of `amount_repaid_raw`. Same null semantics as `amount_borrowed`.
</ResponseField>

<ResponseField name="data.fee_amount_raw" type="string">
  Raw fee: `amount_repaid_raw − amount_borrowed_raw`, in the borrowed token's smallest denomination.
</ResponseField>

<ResponseField name="data.fee_amount" type="string | null">
  Decimals-adjusted form of `fee_amount_raw`. Same null semantics as `amount_borrowed`.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row tracing id (hex, no `0x`).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Parent tracing ids.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp (ISO-8601).
</ResponseField>

#### Envelope

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of rows in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/flash-loans/prints" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19000100,
    "limit": 50
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19000100,\"limit\":50}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/flash-loans/prints");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19000100,\"limit\":50}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/flash-loans/prints", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/flash-loans/prints",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={"chain_id": 1, "from_block": 19000000, "to_block": 19000100, "limit": 50}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/flash-loans/prints", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "from_block": 19000000,
      "to_block": 19000100,
      "limit": 50
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19000100,
    "limit": 50
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/flash-loans/prints", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 19000000,
        "to_block": 19000100,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 19000000,
        "to_block": 19000100,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "pool_uids": [],
        "flash_loan_source_addresses": [],
        "token_addresses": [],
        "limit": 50,
        "cursor": null
      }
    },
    "data": [
      {
        "block_number": 19000050,
        "block_time": "2025-11-11T10:00:00Z",
        "tx_index": 12,
        "log_index": 3,
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "flash_loan_source": "88e6a0c2ddd26feeb64f039a2c41296fcb3f564",
        "token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "amount_borrowed_raw": "1000000000000000000",
        "amount_borrowed": "1",
        "amount_repaid_raw": "1003000000000000000",
        "amount_repaid": "1.003",
        "fee_amount_raw": "3000000000000000",
        "fee_amount": "0.003",
        "_tracing_id": "0305c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T10:00:05Z",
        "_updated_at": "2025-11-11T10:00:05Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Flash Loans Overview
Source: https://docs.blockdb.io/api-reference/evm/flash-loans/overview

Query flash loan borrow and repay prints across DEX pools and vault-level sources.

## Overview

Flash loan datasets capture on-chain flash loan events: amounts borrowed and repaid, fee, and attribution to a pool (`pool_uid`) or vault contract (`flash_loan_source` when `pool_uid` is null).

### Endpoint matrix

| Endpoint                                                                           | Summary                                                          | Dataset ID |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------- |
| [`POST /evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints) | Per-event flash loan prints (one row per borrowed token per log) | `0305`     |

### Related

* [Data catalog: Flash loan prints](/data-catalog/evm/flash-loans/flash-loan-prints)
* [Dataset ID](/api-reference/enumerations/dataset-id)


# Lineage Overview
Source: https://docs.blockdb.io/api-reference/evm/lineage/overview

Understand lineage traversal patterns before hitting record endpoints.

## Overview

The lineage suite lets you reconstruct how a BlockDB record was produced. Each endpoint focuses on a specific slice of the lineage graph so you can tune limits, caching, and latency budgets independently.

### Endpoint Matrix

| Endpoint                                                          | Summary                                                  | Default Limit | Typical Latency |
| ----------------------------------------------------------------- | -------------------------------------------------------- | ------------- | --------------- |
| [`POST /evm/lineage/record`](/api-reference/evm/lineage/record)   | Fetch the latest copy of a record by tracing identifier. | `1`           | \< 200 ms       |
| [`POST /evm/lineage/parents`](/api-reference/evm/lineage/parents) | Traverse the dependency graph of parent records.         | `128` nodes   | up to 1 s       |

### Parameter Conventions

<ParamField type="number">
  Chain identifier to disambiguate networks. Refer to the [Chain](/api-reference/enumerations/chain) enumeration for supported values.
</ParamField>

<ParamField type="string">
  Selector for lineage requests (hex string (no `0x` prefix)). Matches values emitted in `_tracing_id` fields.
</ParamField>

<ParamField type="string">
  Pagination cursor returned from prior responses; persist per endpoint when traversing large graphs.
</ParamField>

<ParamField type="number">
  Maximum number of records to return per page; lower values help manage payload size on expansive graphs.
</ParamField>

### Usage Guidance

* Start with `/evm/lineage/record` to confirm that a `tracing_id` exists before requesting heavier expansions. A missing record comes back as `200 OK` with `"data": null`, so check `data` rather than the status code.
* Apply conservative `limit` settings when exploring new datasets; payload size grows with artifact volume and graph breadth.
* Cache lineage responses client-side where possible—records are immutable once written.
* Monitor `truncation_reason` (when present) to detect when depth or fan-out limits stop traversal.

### See Also

* [`POST /evm/lineage/record`](/api-reference/evm/lineage/record)
* [`POST /evm/lineage/parents`](/api-reference/evm/lineage/parents)


# Lineage Parents
Source: https://docs.blockdb.io/api-reference/evm/lineage/parents

POST https://api.blockdb.io/v1/evm/lineage/parents
Traverse upstream dependencies for any traced record.

## Overview

Traverses the upstream dependency graph of the supplied record. Each node includes relationship metadata so you can follow the chain of derivations to a configurable depth.

## Parameters

<ParamField type="number">
  Target EVM network.
</ParamField>

<ParamField type="string">
  Anchor record whose parents should be returned, provided as a hex string (no `0x` prefix).
</ParamField>

#### Traversal Controls

<ParamField type="number">
  Number of hops to follow. `1` returns direct parents, `2` includes grandparents, etc. Requests exceeding the configured maximum are truncated with a `truncation_reason`.
</ParamField>

<ParamField type="boolean">
  When `true`, each returned node is hydrated with its full `record` (the same payload the [record endpoint](/api-reference/evm/lineage/record) returns). Only the nodes on the returned page are hydrated. Leave `false` to keep traversal responses small.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor returned from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.tracing_id" type="string">
  Tracing identifier for the record whose parents are returned.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element represents a parent node that matches the requested depth and relationship filters.
</ResponseField>

<ResponseField name="data.dataset" type="string">
  Dataset namespace for the parent record.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Lineage identifier for the parent record (hex string, no `0x` prefix). Feed this back into other lineage endpoints to continue traversal.
</ResponseField>

<ResponseField name="data.child_tracing_id" type="string">
  Tracing identifier of the record one hop closer to the queried record that this node is a direct parent of. For `depth: 1` nodes this equals `meta.tracing_id`. Combine with `relationship` to rebuild the lineage tree edge by edge (this node is the `<relationship>` of `child_tracing_id`).
</ResponseField>

<ResponseField name="data.relationship" type="string">
  How this node relates to its `child_tracing_id` (e.g., `source_log`, `pool_metadata`, `dependency`).
</ResponseField>

<ResponseField name="data.depth" type="number">
  Hop count from the original record (`1` for direct parents).
</ResponseField>

<ResponseField name="data.record" type="object">
  Full row for the node, in the same shape as the [record endpoint](/api-reference/evm/lineage/record)'s `data.record`. Present only when the request sets `include_record: true`; omitted otherwise.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor for fetching additional parents.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of parent nodes returned in `data`.
</ResponseField>

<ResponseField name="truncation_reason" type="string | null">
  Non-null when the server stopped traversal due to max depth, fan-out limits, or other safety guards.
</ResponseField>

### Next Steps

* Fetch each parent's full record via [`/evm/lineage/record`](/api-reference/evm/lineage/record).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/lineage/parents" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "tracing_id": "0301000000000000000000000000000000000001",
    "max_depth": 3,
    "cursor": null,
    "limit": 128
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/lineage/parents");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/lineage/parents", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/lineage/parents",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1,
   'cursor': None,
   'limit': 128,
   'max_depth': 3,
   'tracing_id': '0301000000000000000000000000000000000001'}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/lineage/parents", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "tracing_id": "0301000000000000000000000000000000000001",
    "max_depth": 3,
    "cursor": null,
    "limit": 128
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "tracing_id": "0301000000000000000000000000000000000001",
    "max_depth": 3,
    "cursor": null,
    "limit": 128
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/lineage/parents", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "tracing_id": "0301000000000000000000000000000000000001"
    },
    "data": [
      {
        "dataset": "blockdb_evm.0103_logs_v1",
        "_tracing_id": "0103000000000000000000000000000000000001",
        "child_tracing_id": "0301000000000000000000000000000000000001",
        "relationship": "source_log",
        "depth": 1
      },
      {
        "dataset": "blockdb_evm.0211_liquidity_pools_v1",
        "_tracing_id": "0211000000000000000000000000000000000002",
        "child_tracing_id": "0301000000000000000000000000000000000001",
        "relationship": "pool_metadata",
        "depth": 1
      },
      {
        "dataset": "blockdb_evm.0102_transactions_v1",
        "_tracing_id": "0102000000000000000000000000000000000003",
        "child_tracing_id": "0103000000000000000000000000000000000001",
        "relationship": "source_transaction",
        "depth": 2
      }
    ],
    "cursor": "next_cursor",
    "page_count": 3,
    "truncation_reason": null
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Lineage Record
Source: https://docs.blockdb.io/api-reference/evm/lineage/record

POST https://api.blockdb.io/v1/evm/lineage/record
Fetch canonical records directly by tracing identifier.

## Overview

Retrieves the canonical BlockDB representation of a single record, keyed by its lineage identifier. This is the lightweight entry point before requesting heavier parent expansions.

## Parameters

<ParamField type="number">
  EVM network identifier. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  Lineage identifier for the target record (hex string, no `0x` prefix). The legacy `_tracing_id` key is still accepted.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.tracing_id" type="string">
  Tracing identifier for the record whose artifacts are returned.
</ResponseField>

#### Data

<ResponseField name="data" type="object | null">
  Envelope containing the record payload. `null` when no record matches the supplied `tracing_id` (the response is still `200 OK`, not `404`).
</ResponseField>

<Note>
  A lookup that finds no matching record returns `200 OK` with `"data": null` (with `meta` still echoed), consistent with how list endpoints return an empty range. A `404`/`400` is only returned for malformed requests (missing `chain_id`, missing/short `tracing_id`, or an unknown dataset-id prefix).
</Note>

<ResponseField name="data.dataset" type="string">
  Dataset namespace that owns the record (e.g., `0201_tokens-erc20`).
</ResponseField>

<ResponseField name="data.record" type="object">
  Snapshot of the dataset-specific fields for this record. Binary columns (addresses, hashes, tracing ids) are returned as bare lowercase hex — no `0x` and no Postgres `\x` prefix. Common metadata includes:
</ResponseField>

<ResponseField name="data.record.chain_id" type="number">
  Network identifier copied from the envelope.
</ResponseField>

<ResponseField name="data.record.address" type="string">
  Dataset-specific primary key (illustrated here with a token contract address).
</ResponseField>

<ResponseField name="data.record.block_number" type="number">
  Canonical block height where the record last changed.
</ResponseField>

<ResponseField name="data.record.block_time" type="string">
  ISO-8601 timestamp for the block that produced the record state.
</ResponseField>

<ResponseField name="data.record.tx_index" type="number">
  Transaction position for provenance auditing when applicable.
</ResponseField>

<ResponseField name="data.record.log_index" type="number">
  Log position for provenance auditing when applicable.
</ResponseField>

<ResponseField name="data.record._tracing_id" type="string">
  Internal variant of `tracing_id`.
</ResponseField>

<ResponseField name="data.record._parent_tracing_ids" type="string[]">
  Internal variant mirrored for completeness.
</ResponseField>

<ResponseField name="data.record._created_at" type="string">
  Internal created-at timestamp.
</ResponseField>

<ResponseField name="data.record._updated_at" type="string">
  Internal updated-at timestamp.
</ResponseField>

* **`name`**, **`symbol`**, **`decimals`**\
  Dataset fields shown for the ERC-20 example. Actual shape varies per dataset—consult the dataset's schema docs.

### Next Steps

* Chain into [`/evm/lineage/parents`](/api-reference/evm/lineage/parents) to traverse upstream derived records.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/lineage/record" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "tracing_id": "0201000000000000000000000000000000000001"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"tracing_id\":\"0201000000000000000000000000000000000001\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/lineage/record");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"tracing_id\":\"0201000000000000000000000000000000000001\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/lineage/record", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/lineage/record",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1, 'tracing_id': '0201000000000000000000000000000000000001'}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/lineage/record", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "tracing_id": "0201000000000000000000000000000000000001"
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "tracing_id": "0201000000000000000000000000000000000001"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/lineage/record", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "tracing_id": "0201000000000000000000000000000000000001"
    },
    "data": {
      "dataset": "blockdb_evm.b0201_erc20_tokens_v1",
      "record": {
        "chain_id": 1,
        "address": "0000000000000000000000000000000000000001",
        "name": "Token Name",
        "symbol": "TOKEN",
        "decimals": 18,
        "block_number": 567890,
        "block_time": "2018-07-07T12:34:56Z",
        "tx_index": 4,
        "log_index": 2,
        "_tracing_id": "0201000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103000000000000000000000000000000000001",
          "0103000000000000000000000000000000000002"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    }
  }
  ```

  ```json 200 (not found) theme={null}
  {
    "meta": {
      "chain_id": 1,
      "tracing_id": "0201000000000000000000000000000000000001"
    },
    "data": null
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Endpoints Overview
Source: https://docs.blockdb.io/api-reference/evm/overview

Index of BlockDB EVM REST endpoints, paths, and dataset IDs.

## How to use this page

* Click through to full parameter and response documentation per endpoint.
* Dataset IDs match [Dataset ID](/api-reference/enumerations/dataset-id) and WebSocket `dataset_id` values.

## Quick reference

| Category        | Endpoint                                                                                                     | Summary                        | Dataset ID |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------ | ---------- |
| Account & Usage | [`GET /usage`](/api-reference/account-and-usage/usage)                                                       | Usage and rate limits          | —          |
| Lineage         | [`POST /evm/lineage/record`](/api-reference/evm/lineage/record)                                              | Record by tracing id           | —          |
| Lineage         | [`POST /evm/lineage/parents`](/api-reference/evm/lineage/parents)                                            | Parent dependency graph        | —          |
| Verification    | [`POST /evm/verify/receipt-root`](/api-reference/evm/verification/verify-receipt-root)                       | Receipt trie root check        | —          |
| Verification    | [`POST /evm/verify/logs-bloom`](/api-reference/evm/verification/verify-logs-bloom)                           | Logs bloom filter check        | —          |
| Primitives      | [`POST /evm/raw/blocks-summary`](/api-reference/evm/primitives/blocks-summary)                               | Block range aggregates         | —          |
| Primitives      | [`POST /evm/raw/blocks`](/api-reference/evm/primitives/blocks)                                               | Block headers                  | `0101`     |
| Primitives      | [`POST /evm/raw/transactions`](/api-reference/evm/primitives/transactions)                                   | Transactions                   | `0102`     |
| Primitives      | [`POST /evm/raw/logs`](/api-reference/evm/primitives/logs)                                                   | Event logs                     | `0103`     |
| Primitives      | [`POST /evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions)                 | Call traces                    | `0111`     |
| Primitives      | [`POST /evm/raw/contracts`](/api-reference/evm/primitives/contracts)                                         | Contract deployments           | `0121`     |
| Primitives      | [`POST /evm/raw/function-results`](/api-reference/evm/primitives/function-results)                           | Function call results          | `0122`     |
| JSON-RPC        | [`POST /evm/rpc`](/api-reference/evm/rpc/overview)                                                           | Proxied JSON-RPC calls         | —          |
| Entities        | [`POST /evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20)                                | ERC-20 registry                | `0201`     |
| Entities        | [`POST /evm/entities/tokens/erc721`](/api-reference/evm/entities/tokens-erc721)                              | ERC-721 registry               | `0202`     |
| Entities        | [`POST /evm/entities/tokens/erc1155`](/api-reference/evm/entities/tokens-erc1155)                            | ERC-1155 registry              | `0203`     |
| Entities        | [`POST /evm/entities/pools`](/api-reference/evm/entities/pools)                                              | Liquidity pools                | `0211`     |
| Entities        | [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms)                                | Pool fee terms                 | `0212`     |
| Reserves        | [`POST /evm/reserves`](/api-reference/evm/reserves/reserves)                                                 | Pool reserves (+ details join) | `0301`     |
| Prices          | [`POST /evm/prices/spot/crypto/prints`](/api-reference/evm/prices/crypto/prices-spot-prints)                 | Swap prints                    | `0302`     |
| Swaps           | [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees)                                                 | Swap fees                      | `0303`     |
| Transfers       | [`POST /evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers)                        | Token transfers                | `0304`     |
| Flash loans     | [`POST /evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints)                           | Flash loan prints              | `0305`     |
| Prices          | [`POST /evm/prices/spot/crypto/ohlc`](/api-reference/evm/prices/crypto/prices-spot-ohlc)                     | Token-to-token OHLC            | `0404`     |
| Prices          | [`POST /evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap)                     | Token-to-token VWAP            | `0405`     |
| Prices          | [`POST /evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) | Cross-pool VWAP (all venues)   | `0505`     |
| Prices          | [`POST /evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat)                    | Token-to-USD VWAP              | `0605`     |
| Yields          | [`POST /evm/yields`](/api-reference/evm/yields/yields)                                                       | Pool yields                    | `0411`     |
| TVL             | [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd)                                                            | Pool TVL USD                   | `0701`     |
| Arbitrage       | [`POST /evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                                              | Arb path definitions           | `0801`     |
| Arbitrage       | [`POST /evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)                                  | Arb path status                | `0802`     |
| Arbitrage       | [`POST /evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities)                              | Arb opportunities              | `0901`     |

## Where to start

* Raw ledger data: [Primitives](/api-reference/evm/primitives/overview). Block aggregates: [Blocks summary](/api-reference/evm/primitives/blocks-summary). Provenance: [Lineage](/api-reference/evm/lineage/overview). Integrity checks: [Verification](/api-reference/evm/verification/overview). Node passthrough: [JSON-RPC](/api-reference/evm/rpc/overview).
* Tokens and pools: [Entities](/api-reference/evm/entities/overview).
* Pricing: [Prices](/api-reference/evm/prices/overview).
* Delivery and keys: [Authorization](/api-reference/overview/authorization).


# Pricing Suite · Crypto Overview
Source: https://docs.blockdb.io/api-reference/evm/prices/crypto/overview

Swap prints, OHLC bars, and VWAP windows for ERC-20 pairs on EVM chains.

## Overview

Crypto spot endpoints read datasets **`0302`** ([swap prints](/data-catalog/evm/prices/token-to-token-prices-swap-prints)), **`0404`** ([OHLC](/data-catalog/evm/prices/token-to-token-prices-ohlc)), and **`0405`** ([VWAP](/data-catalog/evm/prices/token-to-token-vwap)). Buckets use `bucket_seconds` ∈  as documented in those catalogs.

### Endpoint matrix

| Endpoint                                                                                                     | Summary                  | Dataset ID |
| ------------------------------------------------------------------------------------------------------------ | ------------------------ | ---------- |
| [`POST /evm/prices/spot/crypto/prints`](/api-reference/evm/prices/crypto/prices-spot-prints)                 | Realized swap executions | `0302`     |
| [`POST /evm/prices/spot/crypto/ohlc`](/api-reference/evm/prices/crypto/prices-spot-ohlc)                     | OHLC bars                | `0404`     |
| [`POST /evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap)                     | VWAP bars (per pool)     | `0405`     |
| [`POST /evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) | VWAP bars (cross-pool)   | `0505`     |

### Conventions

<ParamField type="number">Target EVM chain.</ParamField>

Use `pool_uids`, `token_in` / `token_out` (or equivalent address fields per endpoint), `exchange_ids`, and time or block ranges as documented on each page. Binary address and id fields are hex strings without `0x` in JSON.

### Pagination

[Pagination & Limits](/api-reference/overview/pagination-and-limits).

### See also

* [Dataset ID](/api-reference/enumerations/dataset-id)
* [Token-to-token OHLC catalog](/data-catalog/evm/prices/token-to-token-prices-ohlc)


# Prices · Spot OHLC
Source: https://docs.blockdb.io/api-reference/evm/prices/crypto/prices-spot-ohlc

POST https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc
Pull time-bucketed OHLC bars from executed swap prices per pool.

## Overview

* **Dataset ID:** [`0404 - Token-to-Token OHLC`](/data-catalog/evm/prices/token-to-token-prices-ohlc)
* **Description:** Time-bucketed OHLC bars (1m..1d) per pool and token pair direction.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-OHLC-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0404_token_to_token_prices_ohlc_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-OHLC-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0404_token_to_token_prices_ohlc_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block (inclusive). Block ranges use **strict containment**: only buckets whose entire span maps to blocks within `[from_block, to_block]` are returned, so each bar aggregates only blocks inside your range. The partial bucket that merely contains `from_block` (and also spans earlier blocks) is excluded. A range narrower than one `bucket_seconds` returns no bars. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block (inclusive). The partial bucket that contains `to_block` (and also spans later blocks) is excluded — only buckets ending at or before `to_block`'s timestamp are returned. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Window start (ISO-8601, inclusive). Used directly as `bucket_start >= from_timestamp`. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Window end (ISO-8601, inclusive). Buckets with `bucket_end <= to_timestamp` are included. Use with `from_timestamp`.
</ParamField>

<Warning>
  Provide **either** a block range (`from_block` + `to_block`) **or** a time range (`from_timestamp` + `to_timestamp`), not both. Omitting both is HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Filter by exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

<ParamField type="string[]">
  Restrict to specific BlockDB pool identifiers.
</ParamField>

#### Candle Controls

<ParamField type="number">
  Candle width in seconds. Allowed values: `60`, `300`, `900`, `1800`, `3600`, `14400`, `86400`.
</ParamField>

<ParamField type="boolean">
  Gap-fill: one row per pool per bucket in the requested window. Gap buckets LOCF the last `close` (flat candle: open=high=low=close), with zero volumes and `trades_count=0`.

  Eligible pools have at least one bar for this pair and `bucket_seconds` on or before the window end (same `0404` table). LOCF seeds from the last bar before the window start when available, then from in-window bars.

  Works with a timestamp or block range (blocks resolve to timestamps, then align to bucket boundaries).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.base_token_address" type="string">
  ERC-20 contract address of the base asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.quote_token_address" type="string">
  ERC-20 contract address of the quote asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  OHLC candles matching the request; each object uses the same field names as [`0404`](/data-catalog/evm/prices/token-to-token-prices-ohlc). When `dense=true`, one row is returned per pool per bucket for every bucket in the requested window.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier for the candle.
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  Inclusive UTC start of the candle bucket (ISO-8601).
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  Exclusive UTC end of the candle bucket (ISO-8601). Equal to `bucket_start + bucket_seconds`.
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  Bucket width in seconds: `60`, `300`, `900`, `1800`, `3600`, `14400`, or `86400`.
</ResponseField>

<ResponseField name="data.open" type="string | null">
  Opening price for the bucket (`quote_token_address` per 1 `base_token_address`, decimals-adjusted). `null` only when no prior bar exists for this pool, pair, and `bucket_seconds` before the window ends.
</ResponseField>

<ResponseField name="data.high" type="string | null">
  Highest price within the bucket. `null` under the same condition as `open`.
</ResponseField>

<ResponseField name="data.low" type="string | null">
  Lowest price within the bucket. `null` under the same condition as `open`.
</ResponseField>

<ResponseField name="data.close" type="string | null">
  Closing price for the bucket. In dense mode, gap buckets LOCF the last `close` (including pre-window bars). `null` only when no LOCF seed exists.
</ResponseField>

<ResponseField name="data.volume_base_raw" type="string">
  Sum of raw UInt256 `amountIn` values. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.volume_base" type="string | null">
  Decimal-adjusted base (`base_token_address`) volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.volume_quote_raw" type="string">
  Sum of raw UInt256 `amountOut` values. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.volume_quote" type="string | null">
  Decimal-adjusted quote (`quote_token_address`) volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.trades_count" type="number">
  Trade count in the bucket. `0` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_number" type="number | null">
  First block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_number" type="number | null">
  Last block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_timestamp" type="string | null">
  Timestamp of the first block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_timestamp" type="string | null">
  Timestamp of the last block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_block_count" type="number | null">
  Block count in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data._tracing_id" type="string | null">
  BlockDB tracing ID (hex, no `0x` prefix). `null` for synthetic gap-fill rows when `dense=true`.
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  Tracing IDs of contributing swap prints; optional. `null` for gap-fill rows and by default.
</ResponseField>

<ResponseField name="data._created_at" type="string | null">
  Record creation timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

<ResponseField name="data._updated_at" type="string | null">
  Record update timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of candles returned in this page.
</ResponseField>

### Usage Notes

* Pair direction is `meta.base_token_address` → `meta.quote_token_address` (`token_in` → `token_out`). Row objects do not repeat token addresses.
* For USD-denominated VWAP buckets, use [`/evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat) instead of this endpoint.
* Each row is one pool's candle for one bucket. Use `pool_uids` or `exchange_ids` to narrow results.
* `dense=true` works with a timestamp or block range.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_timestamp": "2025-11-11T00:00:00Z",
    "to_timestamp": "2025-11-11T01:00:00Z",
    "exchange_ids": [1, 2],
    "bucket_seconds": 60,
    "dense": false,
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_timestamp\":\"2025-11-11T00:00:00Z\",\"to_timestamp\":\"2025-11-11T01:00:00Z\",\"exchange_ids\":[1,2],\"bucket_seconds\":60,\"dense\":false,\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_timestamp\":\"2025-11-11T00:00:00Z\",\"to_timestamp\":\"2025-11-11T01:00:00Z\",\"exchange_ids\":[1,2],\"bucket_seconds\":60,\"dense\":false,\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  payload = {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "from_timestamp": "2025-11-11T00:00:00Z",
      "to_timestamp": "2025-11-11T01:00:00Z",
      "exchange_ids": [1, 2],
      "bucket_seconds": 60,
      "dense": False,
      "limit": 200,
      "cursor": None
  }

  response = requests.post(
      "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json=payload
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_timestamp": "2025-11-11T00:00:00Z",
    "to_timestamp": "2025-11-11T01:00:00Z",
    "exchange_ids": [1, 2],
    "bucket_seconds": 60,
    "dense": false,
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_timestamp": "2025-11-11T00:00:00Z",
    "to_timestamp": "2025-11-11T01:00:00Z",
    "exchange_ids": [1, 2],
    "bucket_seconds": 60,
    "dense": false,
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "request_window": {
        "from_block": null,
        "to_block": null,
        "from_timestamp": "2025-11-11T00:00:00Z",
        "to_timestamp": "2025-11-11T01:00:00Z"
      },
      "resolved_window": {
        "from_block": null,
        "to_block": null,
        "from_timestamp": "2025-11-11T00:00:00Z",
        "to_timestamp": "2025-11-11T01:00:00Z"
      },
      "filters": {
        "exchange_ids": [1, 2],
        "pool_uids": null,
        "bucket_seconds": 60,
        "dense": false
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "bucket_start": "2025-11-11T00:00:00.000Z",
        "bucket_end": "2025-11-11T00:01:00.000Z",
        "bucket_seconds": 60,
        "open": "3010.112233445566778899",
        "high": "3033.998877665544332211",
        "low": "3008.001122334455667788",
        "close": "3025.219821481234567890",
        "volume_base_raw": "420000000000000000000",
        "volume_base": "420.000000000000000000",
        "volume_quote_raw": "1269000000000",
        "volume_quote": "1269000.000000000000000000",
        "trades_count": 128,
        "block_bucket_first_block_number": null,
        "block_bucket_last_block_number": null,
        "block_bucket_first_block_timestamp": null,
        "block_bucket_last_block_timestamp": null,
        "block_bucket_block_count": null,
        "_tracing_id": "0404000000000000000000000000000000000001",
        "_parent_tracing_ids": null,
        "_created_at": "2025-11-11T01:00:05.000Z",
        "_updated_at": "2025-11-11T01:00:05.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Prices · Spot Prints
Source: https://docs.blockdb.io/api-reference/evm/prices/crypto/prices-spot-prints

POST https://api.blockdb.io/v1/evm/prices/spot/crypto/prints
Retrieve executed swap prints (realized token_in → token_out price & sizes) from on-chain swap events.

## Overview

* **Dataset ID:** [`0302 - Token-to-Token Swap Prints`](/data-catalog/evm/prices/token-to-token-prices-swap-prints)
* **Description:** Executed swap prints (realized token\_in → token\_out price & sizes) per on-chain swap event.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0302_token_to_token_prices_swap_prints_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0302_token_to_token_prices_swap_prints_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Filter by exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

<ParamField type="string[]">
  Restrict to specific BlockDB pool identifiers.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

#### Decimals-Adjusted Amounts

<ParamField type="boolean">
  Off by default. When set to `true`, the response includes `data.amount_in` and `data.amount_out` (decimals-adjusted, may be `null`) alongside the raw integer fields. Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency, so it is opt-in; when omitted or `false`, those fields are returned as `null` and only the always-present `*_raw` fields are populated.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.base_token_address" type="string">
  ERC-20 contract address of the base asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.quote_token_address" type="string">
  ERC-20 contract address of the quote asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Swap print records matching the request.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier where the swap occurred.
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height where the swap event was observed.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the block containing the swap.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Zero-based log index within the transaction.
</ResponseField>

<ResponseField name="data.token_in" type="string">
  20-byte address of the input token (direction of trade).
</ResponseField>

<ResponseField name="data.token_out" type="string">
  20-byte address of the output token for this swap direction.
</ResponseField>

<ResponseField name="data.amount_in_raw" type="string">
  Amount of `token_in` executed in the swap, as a raw integer in the token's smallest denomination. String-encoded to preserve `uint256` precision.
</ResponseField>

<ResponseField name="data.amount_in" type="string | null">
  Decimals-adjusted form of `amount_in_raw` (`amount_in_raw / 10^decimals`). `null` when the input token's decimals are unknown or when `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.amount_out_raw" type="string">
  Amount of `token_out` received in the swap, as a raw integer in the token's smallest denomination. String-encoded to preserve `uint256` precision.
</ResponseField>

<ResponseField name="data.amount_out" type="string | null">
  Decimals-adjusted form of `amount_out_raw`. `null` when the output token's decimals are unknown or when `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.exec_price" type="string | null">
  Realized execution price: `token_out` per 1 `token_in` (decimals-adjusted). May be `null`.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Tracing identifier for the swap print record (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Parent lineage references (hex strings, no `0x` prefix).
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of swap print entries returned.
</ResponseField>

### Usage Notes

* Swap prints represent historical execution outcomes, not forward-looking quotes
* Each print corresponds to a single on-chain swap event with directional pair information
* Use `exec_price` to analyze realized slippage and execution quality
* Filter by `pool_uids` to compare execution prices across different AMM pools
* The `token_in` and `token_out` fields define the swap direction; reverse the pair to see the opposite direction

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/prints" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [
      1,
      2
    ],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "limit": 250,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[2,3],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"limit\":250,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/prices/spot/crypto/prints");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[2,3],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"limit\":250,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/prices/spot/crypto/prints", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/prices/spot/crypto/prints",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "from_block": 18930000,
          "to_block": 18939999,
          "exchange_ids": [2, 3],
          "pool_uids": [
              "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
          ],
          "limit": 250,
          "cursor": None
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/prices/spot/crypto/prints", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [
      1,
      2
    ],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "limit": 250,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [
      1,
      2
    ],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "limit": 250,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/prices/spot/crypto/prints", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "request_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "exchange_ids": [
          1,
          2
        ],
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ]
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 18930123,
        "block_time": "2025-11-11T18:15:30.000Z",
        "tx_index": 5,
        "log_index": 12,
        "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "amount_in_raw": "10000000000000000000",
        "amount_in": "10",
        "amount_out_raw": "30241122334455667788990",
        "amount_out": "30241.12233445566778899",
        "exec_price": "3024.112233445566778899",
        "_tracing_id": "0302000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0203000000000000000000000000000000000000"
        ],
        "_created_at": "2025-11-11T18:15:35.000Z",
        "_updated_at": "2025-11-11T18:15:35.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Prices · VWAP
Source: https://docs.blockdb.io/api-reference/evm/prices/crypto/prices-spot-vwap

POST https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap
Compute VWAP windows across specified asset-class pairs.

## Overview

* **Dataset ID:** [`0405 - Token-to-Token VWAP`](/data-catalog/evm/prices/token-to-token-vwap)
* **Description:** Volume-weighted average price (1m..1d) per pool and token pair direction.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0405_token_to_token_vwap_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0405_token_to_token_vwap_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block (inclusive). Block ranges use **strict containment**: only buckets whose entire span maps to blocks within `[from_block, to_block]` are returned, so each bar aggregates only blocks inside your range. The partial bucket that merely contains `from_block` (and also spans earlier blocks) is excluded. A range narrower than one `bucket_seconds` returns no bars. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block (inclusive). The partial bucket that contains `to_block` (and also spans later blocks) is excluded — only buckets ending at or before `to_block`'s timestamp are returned. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Window start (ISO-8601, inclusive). Used directly as `bucket_start >= from_timestamp`. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Window end (ISO-8601, inclusive). Buckets with `bucket_end <= to_timestamp` are included. Use with `from_timestamp`.
</ParamField>

<Warning>
  Provide **either** a block range (`from_block` + `to_block`) **or** a time range (`from_timestamp` + `to_timestamp`), not both. Omitting both is HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Filter by exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

<ParamField type="string[]">
  Restrict to specific BlockDB pool identifiers.
</ParamField>

#### Bucket Controls

<ParamField type="number">
  Bucket width in seconds. Allowed values: `60`, `300`, `900`, `1800`, `3600`, `14400`, `86400`.
</ParamField>

<ParamField type="boolean">
  Gap-fill: one row per pool per bucket in the requested window. Gap buckets LOCF the last `price_vwap`, with zero volumes and `trade_count=0`.

  Eligible pools have at least one bar for this pair and `bucket_seconds` on or before the window end (same `0405` table). LOCF seeds from the last bar before the window start when available, then from in-window bars.

  Works with a timestamp or block range (blocks resolve to timestamps, then align to bucket boundaries).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.base_token_address" type="string">
  ERC-20 contract address of the base asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.quote_token_address" type="string">
  ERC-20 contract address of the quote asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  VWAP aggregates matching the request; each object uses the same field names as [`0405`](/data-catalog/evm/prices/token-to-token-vwap).
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  Inclusive UTC start of the VWAP bucket (ISO-8601).
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  Exclusive UTC end of the VWAP bucket (ISO-8601). Equal to `bucket_start + bucket_seconds`.
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  Bucket width in seconds: `60`, `300`, `900`, `1800`, `3600`, `14400`, or `86400`.
</ResponseField>

<ResponseField name="data.token_in" type="string">
  Input token address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.token_out" type="string">
  Output token address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.price_vwap" type="string | null">
  VWAP (`token_out` per 1 `token_in`, decimals-adjusted). `null` only when no prior bar exists for this pool, pair, and `bucket_seconds` before the window ends. In dense mode, gap buckets LOCF the last price (including pre-window bars).
</ResponseField>

<ResponseField name="data.total_volume_in_raw" type="string">
  Sum of raw UInt256 `amountIn` values. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.total_volume_in" type="string | null">
  Decimal-adjusted `token_in` volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.total_volume_out_raw" type="string">
  Sum of raw UInt256 `amountOut` values. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.total_volume_out" type="string | null">
  Decimal-adjusted `token_out` volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.trade_count" type="number">
  Number of swaps in the bucket. `0` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_number" type="number | null">
  First block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_number" type="number | null">
  Last block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_timestamp" type="string | null">
  Timestamp of the first block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_timestamp" type="string | null">
  Timestamp of the last block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_block_count" type="number | null">
  Block count in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data._tracing_id" type="string | null">
  BlockDB tracing ID (hex, no `0x` prefix). `null` for synthetic gap-fill rows when `dense=true`.
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  Tracing IDs of contributing swap prints; optional. `null` for gap-fill rows and by default.
</ResponseField>

<ResponseField name="data._created_at" type="string | null">
  Record creation timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

<ResponseField name="data._updated_at" type="string | null">
  Record update timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of VWAP entries returned in this page.
</ResponseField>

### Usage Notes

* For USD VWAP buckets, use [`/evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat) (`0605`).
* For **cross-pool VWAP** (aggregated across venues/pools), use [`POST /evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) (`0505`).
* `dense=true` works with a timestamp or block range.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [1, 2],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "bucket_seconds": 3600,
    "dense": false,
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[1,2],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"bucket_seconds\":3600,\"dense\":false,\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[1,2],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"bucket_seconds\":3600,\"dense\":false,\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "from_block": 18930000,
          "to_block": 18939999,
          "exchange_ids": [1, 2],
          "pool_uids": [
              "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
          ],
          "bucket_seconds": 3600,
          "dense": False,
          "limit": 200,
          "cursor": None
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [1, 2],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "bucket_seconds": 3600,
    "dense": false,
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [1, 2],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "bucket_seconds": 3600,
    "dense": false,
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "request_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": "2024-01-11T13:00:00Z",
        "to_timestamp": "2024-01-12T22:00:00Z"
      },
      "filters": {
        "exchange_ids": [1, 2],
        "pool_uids": ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"],
        "bucket_seconds": 3600,
        "dense": false
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "bucket_start": "2025-11-11T18:00:00.000Z",
        "bucket_end": "2025-11-11T19:00:00.000Z",
        "bucket_seconds": 3600,
        "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "price_vwap": "3024.112233445566778899",
        "total_volume_in_raw": "580000000000000000000",
        "total_volume_in": "580.000000000000000000",
        "total_volume_out_raw": "1750000000000",
        "total_volume_out": "1750000.000000000000000000",
        "trade_count": 142,
        "block_bucket_first_block_number": null,
        "block_bucket_last_block_number": null,
        "block_bucket_first_block_timestamp": null,
        "block_bucket_last_block_timestamp": null,
        "block_bucket_block_count": null,
        "_tracing_id": "0405000000000000000000000000000000000001",
        "_parent_tracing_ids": null,
        "_created_at": "2025-11-11T19:00:05.000Z",
        "_updated_at": "2025-11-11T19:00:05.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Prices · Cross-Pool VWAP
Source: https://docs.blockdb.io/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate

POST https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate
Compute cross-pool (cross-venue) VWAP windows aggregated across all pools and exchanges.

## Overview

* **Dataset ID:** [`0505 - Token-to-Token Cross-Pool VWAP`](/data-catalog/evm/prices/token-to-token-cross-pool-vwap)
* **Description:** Cross-venue VWAP bars (1m..1d) per token pair direction, aggregated from per-pool VWAP (`0405`) across all pools and exchanges.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-Cross-Pool-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0505_token_to_token_cross_pool_vwap_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-Cross-Pool-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0505_token_to_token_cross_pool_vwap_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block (inclusive). Block ranges use **strict containment**: only buckets whose entire span maps to blocks within `[from_block, to_block]` are returned, so each bar aggregates only blocks inside your range. The partial bucket that merely contains `from_block` (and also spans earlier blocks) is excluded. A range narrower than one `bucket_seconds` returns no bars. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block (inclusive). The partial bucket that contains `to_block` (and also spans later blocks) is excluded — only buckets ending at or before `to_block`'s timestamp are returned. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Window start (ISO-8601, inclusive). Used directly as `bucket_start >= from_timestamp`. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Window end (ISO-8601, inclusive). Buckets with `bucket_end <= to_timestamp` are included. Use with `from_timestamp`.
</ParamField>

<Warning>
  Provide **either** a block range (`from_block` + `to_block`) **or** a time range (`from_timestamp` + `to_timestamp`), not both. Omitting both is HTTP 400.
</Warning>

#### Bucket Controls

<ParamField type="number">
  Bucket width in seconds. Allowed values: `60`, `300`, `900`, `1800`, `3600`, `14400`, `86400`.
</ParamField>

<ParamField type="boolean">
  Gap-fill: one row per bucket in the requested window. Gap buckets LOCF the last `price_vwap`, with zero volumes, `trade_count=0`, and `pool_count=0`.

  LOCF seeds from the last cross-pool bar before the window start when available, then from in-window bars (same `0505` table).

  Works with a timestamp or block range (blocks resolve to timestamps, then align to bucket boundaries).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.base_token_address" type="string">
  ERC-20 contract address of the base asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.quote_token_address" type="string">
  ERC-20 contract address of the quote asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Cross-pool VWAP aggregates matching the request; each object uses the same field names as [`0505`](/data-catalog/evm/prices/token-to-token-cross-pool-vwap).
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  Inclusive UTC start of the VWAP bucket (ISO-8601).
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  Exclusive UTC end of the VWAP bucket (ISO-8601). Equal to `bucket_start + bucket_seconds`.
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  Bucket width in seconds: `60`, `300`, `900`, `1800`, `3600`, `14400`, or `86400`.
</ResponseField>

<ResponseField name="data.token_in" type="string">
  Input token address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.token_out" type="string">
  Output token address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.price_vwap" type="string | null">
  Cross-venue VWAP (`quote_token_address` per 1 `base_token_address`, decimals-adjusted). `null` only when no prior bar exists for this pair and `bucket_seconds` before the window ends. In dense mode, gap buckets LOCF the last price (including pre-window bars).
</ResponseField>

<ResponseField name="data.total_volume_in_raw" type="string">
  Sum of raw UInt256 `amountIn` values across all contributing pools. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.total_volume_in" type="string | null">
  Decimal-adjusted `token_in` volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.total_volume_out_raw" type="string">
  Sum of raw UInt256 `amountOut` values across all contributing pools. `"0"` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.total_volume_out" type="string | null">
  Decimal-adjusted `token_out` volume. `null` when token decimals are unknown. `"0"` for carry-forward buckets in dense mode when decimals are known.
</ResponseField>

<ResponseField name="data.trade_count" type="number">
  Total swaps across all contributing pools. `0` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.pool_count" type="number">
  Distinct pools that contributed to the bucket. `0` for carry-forward buckets in dense mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_number" type="number | null">
  First block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_number" type="number | null">
  Last block number in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_first_block_timestamp" type="string | null">
  Timestamp of the first block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_last_block_timestamp" type="string | null">
  Timestamp of the last block in the chain-wide bucket (ISO-8601). Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data.block_bucket_block_count" type="number | null">
  Block count in the chain-wide bucket. Populated when `dense=true`; `null` in sparse mode.
</ResponseField>

<ResponseField name="data._tracing_id" type="string | null">
  BlockDB tracing ID (hex, no `0x` prefix). `null` for synthetic gap-fill rows when `dense=true`.
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  Tracing IDs of contributing per-pool VWAP (`0405`) bars; optional. `null` for gap-fill rows and by default.
</ResponseField>

<ResponseField name="data._created_at" type="string | null">
  Record creation timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

<ResponseField name="data._updated_at" type="string | null">
  Record update timestamp (ISO-8601). `null` for gap-fill rows.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of VWAP entries returned in this page.
</ResponseField>

### Usage Notes

* For per-pool VWAP, use [`POST /evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap) (`0405`).
* For USD VWAP buckets, use [`POST /evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat) (`0605`).
* `dense=true` works with a timestamp or block range.
* Responses are read from the pre-aggregated cross-pool dataset (`0505`).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "bucket_seconds": 3600,
    "dense": false,
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"bucket_seconds\":3600,\"dense\":false,\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_token_address\":\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"from_block\":18930000,\"to_block\":18939999,\"bucket_seconds\":3600,\"dense\":false,\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "from_block": 18930000,
          "to_block": 18939999,
          "bucket_seconds": 3600,
          "dense": False,
          "limit": 200,
          "cursor": None
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "from_block": 18930000,
      "to_block": 18939999,
      "bucket_seconds": 3600,
      "dense": false,
      "limit": 200,
      "cursor": null
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "from_block": 18930000,
    "to_block": 18939999,
    "bucket_seconds": 3600,
    "dense": false,
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "request_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": "2024-01-11T13:00:00Z",
        "to_timestamp": "2024-01-12T22:00:00Z"
      },
      "filters": {
        "bucket_seconds": 3600,
        "dense": false
      }
    },
    "data": [
      {
        "bucket_start": "2025-11-11T18:00:00.000Z",
        "bucket_end": "2025-11-11T19:00:00.000Z",
        "bucket_seconds": 3600,
        "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "price_vwap": "3024.112233445566778899",
        "total_volume_in_raw": "580000000000000000000",
        "total_volume_in": "580.000000000000000000",
        "total_volume_out_raw": "1750000000000",
        "total_volume_out": "1750000.000000000000000000",
        "trade_count": 142,
        "pool_count": 23,
        "block_bucket_first_block_number": null,
        "block_bucket_last_block_number": null,
        "block_bucket_first_block_timestamp": null,
        "block_bucket_last_block_timestamp": null,
        "block_bucket_block_count": null,
        "_tracing_id": "0505000000000000000000000000000000000001",
        "_parent_tracing_ids": null,
        "_created_at": "2025-11-11T19:00:05.000Z",
        "_updated_at": "2025-11-11T19:00:05.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Pricing Suite · Fiat Overview
Source: https://docs.blockdb.io/api-reference/evm/prices/fiat/overview

Token-to-USD VWAP in fixed time buckets.

## Overview

The fiat VWAP endpoint reflects dataset **`0605`** — [Token-to-fiat VWAP](/data-catalog/evm/prices/token-to-fiat-vwap): USD price per ERC-20 token with lineage anchors and stablecoin-anchored routing metadata (`hops`, `sources_count`).

### Endpoint matrix

| Endpoint                                                                                  | Summary                   | Dataset ID |
| ----------------------------------------------------------------------------------------- | ------------------------- | ---------- |
| [`POST /evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat) | Token-to-USD VWAP buckets | `0605`     |

### Parameters

<ParamField type="number">Target EVM chain.</ParamField>

<ParamField type="string">ERC-20 address filter (hex, no `0x`), when applicable.</ParamField>

Use block or time range filters per [Pagination & Limits](/api-reference/overview/pagination-and-limits) patterns on the VWAP page.

### See also

* [Token-to-fiat VWAP catalog](/data-catalog/evm/prices/token-to-fiat-vwap)
* [Fiat Currency](/api-reference/enumerations/fiat-currency)


# Prices · VWAP (Fiat)
Source: https://docs.blockdb.io/api-reference/evm/prices/fiat/prices-spot-vwap-fiat

POST https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap
Compute fiat-denominated VWAP windows across specified asset pairs.

## Overview

* **Dataset ID:** [`0605 - Token-to-Fiat VWAP (USD)`](/data-catalog/evm/prices/token-to-fiat-vwap)
* **Description:** Token-to-USD VWAP (1m..1d) per token, derived from cross-pool token-to-token VWAP (dataset 0505) via stablecoin anchoring.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-To-Fiat-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0605_token_to_fiat_vwap_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-To-Fiat-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0605_token_to_fiat_vwap_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Fiat currency code for the quote leg.
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block (inclusive). Block ranges use **strict containment**: only buckets whose entire span maps to blocks within `[from_block, to_block]` are returned, so each bar aggregates only blocks inside your range. The partial bucket that merely contains `from_block` is excluded. A range narrower than one `bucket_seconds` returns no bars. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block (inclusive). The partial bucket that contains `to_block` (and also spans later blocks) is excluded — only buckets ending at or before `to_block`'s timestamp are returned. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Filter by exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

<ParamField type="string[]">
  Restrict to specific BlockDB pool identifiers.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.base_token_address" type="string">
  ERC-20 contract address of the base asset, echoed from the request.
</ResponseField>

<ResponseField name="meta.quote_currency_code" type="string">
  Fiat currency code for the quote leg, echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters applied to the query (exchange IDs, pool UIDs).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Fiat VWAP rows matching the request.
</ResponseField>

<ResponseField name="data.first_block_number" type="number">
  On-chain lineage anchor: block of the first contributing event in the bucket window.
</ResponseField>

<ResponseField name="data.first_block_time" type="string">
  Time of the first contributing event (ISO-8601).
</ResponseField>

<ResponseField name="data.first_tx_index" type="number">
  Transaction index of the first contributing event.
</ResponseField>

<ResponseField name="data.first_log_index" type="number">
  Log index of the first contributing event.
</ResponseField>

<ResponseField name="data.last_block_number" type="number">
  On-chain lineage anchor: block of the last contributing event in the bucket window.
</ResponseField>

<ResponseField name="data.last_block_time" type="string">
  Time of the last contributing event (ISO-8601).
</ResponseField>

<ResponseField name="data.last_tx_index" type="number">
  Transaction index of the last contributing event.
</ResponseField>

<ResponseField name="data.last_log_index" type="number">
  Log index of the last contributing event.
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  Inclusive UTC start of the VWAP bucket (ISO-8601).
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  Bucket width in seconds; one of `60`, `300`, `900`, `1800`, `3600`, `14400`, `86400`.
</ResponseField>

<ResponseField name="data.token_address" type="string">
  ERC-20 token address (hex, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.price_usd" type="string">
  VWAP in USD for the bucket. Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.total_notional_usd" type="string">
  Notional USD volume used in the VWAP weighting. Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.hops" type="number">
  Minimum hop count from the stablecoin anchor along `b0505` edges.
</ResponseField>

<ResponseField name="data.sources_count" type="number">
  Number of cross-pool pair edges (`b0505` rows) used in the hop chain.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  BlockDB tracing ID for the row (hex string, no `0x` prefix); unique per row.
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Tracing IDs of contributing `b0505` VWAP lineage (each hex string without `0x`).
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of VWAP entries returned.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_currency_code": "USD",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [
      1,
      2
    ],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_currency_code\":\"USD\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[2,3],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type": "application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"base_token_address\":\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"quote_currency_code\":\"USD\",\"from_block\":18930000,\"to_block\":18939999,\"exchange_ids\":[2,3],\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap", payload);
          response.EnsureSuccessStatusCode();

          Console.WriteLine(await response.Content.ReadAsStringAsync());
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  payload = {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_currency_code": "USD",
      "from_block": 18930000,
      "to_block": 18939999,
      "exchange_ids": [2, 3],
      "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ]
  }

  response = requests.post(
      "https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json=payload
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      chain_id: 1,
      base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      quote_currency_code: "USD",
      from_block: 18930000,
      to_block: 18939999,
      exchange_ids: [2, 3],
      pool_uids: [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      limit: 200,
      cursor: null
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_currency_code": "USD",
    "from_block": 18930000,
    "to_block": 18939999,
    "exchange_ids": [
      1,
      2
    ],
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/prices/spot/fiat/vwap", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote_currency_code": "USD",
      "request_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18930000,
        "to_block": 18939999,
        "from_timestamp": "2024-01-11T13:00:00Z",
        "to_timestamp": "2024-01-12T22:00:00Z"
      },
      "filters": {
        "exchange_ids": [
          1,
          2
        ],
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ]
      }
    },
    "data": [
      {
        "first_block_number": 18930000,
        "first_block_time": "2025-11-11T18:00:11.000Z",
        "first_tx_index": 12,
        "first_log_index": 5,
        "last_block_number": 18939999,
        "last_block_time": "2025-11-11T18:59:48.000Z",
        "last_tx_index": 44,
        "last_log_index": 2,
        "bucket_start": "2025-11-11T18:00:00.000Z",
        "bucket_seconds": 3600,
        "token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "price_usd": "3024.112233445566778899",
        "total_notional_usd": "1750000.000000000000000000",
        "hops": 2,
        "sources_count": 4,
        "_tracing_id": "0605000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0505000000000000000000000000000000000001",
          "0505000000000000000000000000000000000002"
        ],
        "_created_at": "2025-11-11T19:00:05.000Z",
        "_updated_at": "2025-11-11T19:00:05.000Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Blocks
Source: https://docs.blockdb.io/api-reference/evm/primitives/blocks

POST https://api.blockdb.io/v1/evm/raw/blocks
Retrieve canonical EVM blocks with provenance and integrity metadata.

## Overview

* **Dataset ID:** [`0101 - Blocks`](/data-catalog/evm/primitives/blocks)
* **Description:** Canonical block headers with BlockDB integrity metadata.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or explicit selectors.\
  Providing more than one option (e.g., both ranges or ranges plus selectors) results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Explicit set of block numbers. Mutually exclusive with `block_hashes`.
</ParamField>

<ParamField type="string[]">
  Explicit set of block hashes (hex string, 32 bytes, no `0x` prefix). Mutually exclusive with `block_numbers`.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (contract addresses, block numbers, limit).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of block objects.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Sequential block height.
</ResponseField>

<ResponseField name="data.block_hash" type="string">
  Keccak-256 hash of the block header (32 bytes, hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data.parent_block_hash" type="string">
  Keccak-256 hash of the parent block (32 bytes, hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data.receipt_root" type="string">
  Merkle root of transaction receipts (32 bytes).
</ResponseField>

<ResponseField name="data.miner" type="string">
  Fee recipient / coinbase address (20 bytes).
</ResponseField>

<ResponseField name="data.gas_limit" type="number">
  Block gas limit.
</ResponseField>

<ResponseField name="data.extra_data" type="string">
  Extra data payload supplied by the miner (`<= 32` bytes, hex-encoded).
</ResponseField>

<ResponseField name="data.size" type="number">
  Block size in bytes.
</ResponseField>

<ResponseField name="data.timestamp_utc" type="string">
  Timestamp when the block was mined.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Tracing identifier for the canonical block record (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._computed_receipt_root" type="string">
  Recomputed receipts root for BlockDB integrity checks.
</ResponseField>

<ResponseField name="data._computed_receipt_timestamp_utc" type="string">
  Timestamp when the receipts root was (re)computed.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "block_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"block_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/blocks");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"block_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/blocks", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/blocks",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
   'block_numbers': [12345678, 12345679],
  'chain_id': 1,
  'from_block': 12345678,
  'from_timestamp': '2025-10-29T00:00:00Z',
  'to_block': 12345999,
  'to_timestamp': '2025-11-11T00:00:00Z',
  'limit': 200,
  'cursor': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/blocks", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "block_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "block_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/blocks", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "block_numbers": [
          12345678,
          12345679
        ],
        "block_hashes": [
          "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
        ]
      }
    },
    "data": [
      {
        "block_number": 12345678,
        "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
        "parent_block_hash": "f78e26c5959a94d6a62ed3837f5dcecf0d3761bf0a502e12a08fd7bc44c8568d",
        "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
        "miner": "0000000000000000000000000000000000000000",
        "gas_limit": 30000000,
        "extra_data": "636c61737369635f657468657265756d",
        "size": 124836,
        "timestamp_utc": "2025-11-11T18:42:15.123Z",
        "_tracing_id": "010200000000000000000000000000000000",
        "_computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
        "_computed_receipt_timestamp_utc": "2025-11-11T18:43:00.000Z",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Blocks Summary
Source: https://docs.blockdb.io/api-reference/evm/primitives/blocks-summary

POST https://api.blockdb.io/v1/evm/raw/blocks-summary
Aggregate throughput, fee, and usage metrics over block or time ranges.

## Overview

* **Dataset ID:** [`0101 - Blocks`](/data-catalog/evm/primitives/blocks)
* **Description:** Aggregated block metrics (gas, throughput, fees) over a range; derived from `blockdb_evm.b0101_blocks_v1`. This endpoint returns aggregated buckets, not raw block rows.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range or a time range.\
  Providing both results in HTTP 400.\
  Providing neither results in HTTP 400.
</Warning>

#### Aggregation Controls

<ParamField type="boolean">
  Adds a 10-bucket histogram for effective gas price distribution when `true`.
</ParamField>

<ParamField type="string">
  Temporal grouping of the summary. Supported values: `"total"`, `"hour"`, `"day"`.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Other request knobs echoed back (fee histogram flag, bucket granularity).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Buckets summarising the requested range. One element when `bucket_granularity` is `"total"`.
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  ISO-8601 timestamp marking the start of the aggregation window.
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  ISO-8601 timestamp marking the end of the aggregation window.
</ResponseField>

<ResponseField name="data.bucket_granularity" type="string">
  Granularity echoed from the request.
</ResponseField>

<ResponseField name="data.block_count" type="number">
  Total number of canonical blocks in the bucket.
</ResponseField>

<ResponseField name="data.min_block_number" type="number">
  Smallest block number covered in the bucket.
</ResponseField>

<ResponseField name="data.max_block_number" type="number">
  Largest block number covered in the bucket.
</ResponseField>

<ResponseField name="data.tx_count" type="number">
  Total transactions in the bucket.
</ResponseField>

<ResponseField name="data.successful_tx_count" type="number">
  Successful transactions in the bucket.
</ResponseField>

<ResponseField name="data.failed_tx_count" type="number">
  Failed transactions in the bucket.
</ResponseField>

<ResponseField name="data.unique_senders" type="number">
  Distinct sender addresses observed.
</ResponseField>

<ResponseField name="data.unique_recipients" type="number">
  Distinct recipient addresses observed.
</ResponseField>

<ResponseField name="data.gas_used" type="string">
  Sum of gas used (wei) across all blocks in the bucket.
</ResponseField>

<ResponseField name="data.gas_limit" type="string">
  Sum of gas limits (wei) across all blocks in the bucket.
</ResponseField>

<ResponseField name="data.base_fee_per_gas_min" type="string">
  Minimum base fee per gas (wei).
</ResponseField>

<ResponseField name="data.base_fee_per_gas_max" type="string">
  Maximum base fee per gas (wei).
</ResponseField>

<ResponseField name="data.base_fee_per_gas_avg" type="string">
  Average base fee per gas (wei).
</ResponseField>

<ResponseField name="data.priority_fee_per_gas_avg" type="string">
  Average priority fee per gas (wei) for successful transactions. Nullable on unsupported chains.
</ResponseField>

<ResponseField name="data.burned_fees" type="string">
  Total ETH burned via base fee (wei).
</ResponseField>

<ResponseField name="data.net_issuance" type="string">
  Protocol-level issuance minus burned fees for the bucket (wei).
</ResponseField>

<ResponseField name="data.fee_histogram" type="object[]">
  Ten buckets covering the 0-100 percentile range when `include_fee_histogram` is `true`.
</ResponseField>

<ResponseField name="data.fee_histogram[].bucket_index" type="number">
  Zero-based bucket index (0-9).
</ResponseField>

<ResponseField name="data.fee_histogram[].max_effective_gas_price" type="string">
  Upper bound (exclusive) of the fee bucket (wei).
</ResponseField>

<ResponseField name="data.fee_histogram[].tx_count" type="number">
  Transactions in the fee bucket.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor for additional buckets when the range exceeds service limits.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of bucket elements in `data`.
</ResponseField>

## Use Cases

* Feed dashboards with pre-aggregated throughput metrics without ETL.
* Detect fee regime shifts by polling hourly buckets.
* Estimate unique user counts per epoch to complement raw transaction exports.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/blocks-summary" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 18900000,
    "to_block": 18900999,
    "from_timestamp": null,
    "to_timestamp": null,
    "include_fee_histogram": true,
    "bucket_granularity": "hour"
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":18900000,\"to_block\":18900999,\"from_timestamp\":null,\"to_timestamp\":null,\"include_fee_histogram\":true,\"bucket_granularity\":\"hour\"}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/blocks-summary");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":18900000,\"to_block\":18900999,\"from_timestamp\":null,\"to_timestamp\":null,\"include_fee_histogram\":true,\"bucket_granularity\":\"hour\"}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/blocks-summary", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/blocks-summary",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'bucket_granularity': 'hour',
   'chain_id': 1,
   'from_block': 18900000,
   'from_timestamp': None,
   'include_fee_histogram': True,
   'to_block': 18900999,
   'to_timestamp': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/blocks-summary", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 18900000,
    "to_block": 18900999,
    "from_timestamp": null,
    "to_timestamp": null,
    "include_fee_histogram": true,
    "bucket_granularity": "hour"
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 18900000,
    "to_block": 18900999,
    "from_timestamp": null,
    "to_timestamp": null,
    "include_fee_histogram": true,
    "bucket_granularity": "hour"
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/blocks-summary", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 18900000,
        "to_block": 18900999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18900000,
        "to_block": 18900999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "include_fee_histogram": true,
        "bucket_granularity": "hour"
      }
    },
    "data": [
      {
        "bucket_start": "2025-11-11T00:00:00Z",
        "bucket_end": "2025-11-11T00:59:59Z",
        "bucket_granularity": "hour",
        "block_count": 300,
        "min_block_number": 18900000,
        "max_block_number": 18900299,
        "tx_count": 420000,
        "successful_tx_count": 405000,
        "failed_tx_count": 15000,
        "unique_senders": 128456,
        "unique_recipients": 98234,
        "gas_used": "9203456789000",
        "gas_limit": "9300000000000",
        "base_fee_per_gas_min": "2100000000",
        "base_fee_per_gas_max": "2300000000",
        "base_fee_per_gas_avg": "2195000000",
        "priority_fee_per_gas_avg": "1500000000",
        "burned_fees": "1932000000000000000",
        "net_issuance": "-1300000000000000000",
        "fee_histogram": [
          {
            "bucket_index": 0,
            "max_effective_gas_price": "500000000",
            "tx_count": 42000
          }
        ]
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Contracts
Source: https://docs.blockdb.io/api-reference/evm/primitives/contracts

POST https://api.blockdb.io/v1/evm/raw/contracts
Access canonical contract metadata and deployment info for smart contracts discovered via CREATE/CREATE2 internal transactions.

## Overview

* **Dataset ID:** [`0121 - Contracts`](/data-catalog/evm/primitives/contracts)
* **Description:** Smart contracts discovered via CREATE/CREATE2 internal transactions. Uses `contract_id` (26 bytes = address + creation\_block + tx\_index) as primary key to support metamorphic contracts (e.g. CREATE-SELFDESTRUCT-CREATE2 in the same block).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Contracts-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0121_contracts_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Contracts-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0121_contracts_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive with direct selectors)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, `block_numbers`, or `contract_addresses`.\
  Providing both range selectors and explicit selectors results in HTTP 400.\
  Providing none also results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="string[]">
  Filter by specific deployed contract addresses (hex string, 20 bytes, no `0x` prefix). Up to 256 addresses per request.
</ParamField>

<ParamField type="number[]">
  Explicit list of block heights to fetch contract deployments from. Mutually exclusive with the range filters.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (contract addresses, block numbers, limit).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element mirrors the table columns (chain implied by `meta.chain_id`).
</ResponseField>

<ResponseField name="data.contract_id" type="string">
  Unique contract incarnation ID (hex string, 26 bytes, no `0x` prefix): 20 bytes address + 4 bytes creation block + 2 bytes tx\_index. Use for metamorphic disambiguation and to join with function-results.
</ResponseField>

<ResponseField name="data.contract_address" type="string">
  Deployed contract address (hex string, 20 bytes, no `0x` prefix). Use for address-based lookups.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height containing the contract creation.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  ISO-8601 UTC timestamp of the creation block, joined from the blocks dataset.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index of the deployment transaction within the block.
</ResponseField>

<ResponseField name="data.trace_address" type="string">
  Position in the call tree (e.g., `"0"`, `"0.0"`, `"0.1.2"`).
</ResponseField>

<ResponseField name="data.creator_address" type="string">
  Address that deployed the contract (msg.sender of CREATE/CREATE2). Hex string, 20 bytes, no `0x` prefix.
</ResponseField>

<ResponseField name="data.creation_call_type" type="string">
  Type of creation: `CREATE` or `CREATE2`.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Internal tracing identifier for lineage tracking (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Timestamp when BlockDB materialized the record.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Timestamp of the latest update to the record.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor to continue the query.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records in the current page.
</ResponseField>

## Use Cases

* Look up the canonical creation block for a contract address before hydrating additional metadata.
* Backfill on-chain analyses that require the deployment timestamp or transaction location.
* Seed lineage exploration using `_tracing_id` to pivot into `/evm/logs` and `/evm/transactions`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/contracts" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "block_numbers": [
      18934001,
      18934222
    ],
    "from_block": 18933000,
    "to_block": 18936000,
    "from_timestamp": null,
    "to_timestamp": null,
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"contract_addresses\":[\"1234567890abcdef1234567890abcdef12345678\"],\"block_numbers\":[18934001,18934222],\"from_block\":18933000,\"to_block\":18936000,\"from_timestamp\":null,\"to_timestamp\":null,\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/contracts");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"contract_addresses\":[\"1234567890abcdef1234567890abcdef12345678\"],\"block_numbers\":[18934001,18934222],\"from_block\":18933000,\"to_block\":18936000,\"from_timestamp\":null,\"to_timestamp\":null,\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/contracts", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/contracts",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_numbers': [18934001, 18934222],
   'chain_id': 1,
   'contract_addresses': ['1234567890abcdef1234567890abcdef12345678'],
   'cursor': None,
   'from_block': 18933000,
   'from_timestamp': None,
   'limit': 200,
   'to_block': 18936000,
   'to_timestamp': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/contracts", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "block_numbers": [
      18934001,
      18934222
    ],
    "from_block": 18933000,
    "to_block": 18936000,
    "from_timestamp": null,
    "to_timestamp": null,
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "block_numbers": [
      18934001,
      18934222
    ],
    "from_block": 18933000,
    "to_block": 18936000,
    "from_timestamp": null,
    "to_timestamp": null,
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/contracts", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 18933000,
        "to_block": 18936000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18933000,
        "to_block": 18936000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "contract_addresses": [
          "1234567890abcdef1234567890abcdef12345678"
        ],
        "block_numbers": [
          18934001,
          18934222
        ]
      }
    },
    "data": [
      {
        "contract_id": "1234567890abcdef1234567890abcdef1234567800121a0700",
        "contract_address": "1234567890abcdef1234567890abcdef12345678",
        "block_number": 18934221,
        "block_time": "2024-04-01T12:34:56Z",
        "tx_index": 7,
        "trace_address": "0",
        "creator_address": "0000000000000000000000000000000000000000",
        "creation_call_type": "CREATE2",
        "_tracing_id": "0121000000000000000000000000000000000001",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Function Results
Source: https://docs.blockdb.io/api-reference/evm/primitives/function-results

POST https://api.blockdb.io/v1/evm/raw/function-results
Read cached function execution outputs enriched with traces and gas usage.

## Overview

* **Dataset ID:** [`0122 - Function Results`](/data-catalog/evm/primitives/function-results)
* **Description:** On-chain function call return values versioned by block. Uses `contract_id` (26 bytes) to support metamorphic contracts; primary key is `(contract_id, block_number, call_data)`.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Function-Results-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0122_function_results_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Function-Results-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0122_function_results_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  Every request must include a **bounding window** — either a block range (`from_block`/`to_block`) or a time range (`from_timestamp`/`to_timestamp`). The two ranges are mutually exclusive.\
  `contract_addresses` and `signature_hashes` are **refinement filters only** and must be combined with a block or time range; they cannot be used on their own. function\_results is a very large partitioned table, and selectors are low-selectivity (a single hot selector such as `transfer()` matches a huge fraction of rows), so an unbounded selector scan would time out.\
  Providing no bounding window results in HTTP 400.
</Warning>

#### Refinement Filters

<ParamField type="string[]">
  Filter by 20-byte contract addresses (hex string, no `0x` prefix). Resolved to matching `contract_id` incarnations. Up to 256 entries. Requires a block or time range.
</ParamField>

<ParamField type="string[]">
  4-byte function selectors (8 hex characters, no `0x` prefix). Use to scope calls to specific function signatures. Requires a block or time range.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor returned from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (contract addresses, signature hashes, latest\_only, limit).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Function result records ordered by `(contract_id, block_number DESC)` unless `latest_only` is `true`. Each row matches the linked dataset; the first 20 bytes of `contract_id` are the deployed address — there is no separate `contract_address` field in the payload.
</ResponseField>

<ResponseField name="data.contract_id" type="string">
  Contract incarnation ID (hex string, 26 bytes, no `0x` prefix): 20 bytes address + 4 bytes creation block + 2 bytes tx index. Use to join with contracts or for metamorphic disambiguation.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Snapshot block height when the value was observed.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block time for the snapshot (ISO-8601).
</ResponseField>

<ResponseField name="data.call_data" type="string">
  Hex-encoded calldata sent to the contract. For simple getter functions, this is usually just the selector.
</ResponseField>

<ResponseField name="data.signature_hash" type="string">
  4-byte function selector (hex).
</ResponseField>

<ResponseField name="data.result" type="string | null">
  Hex-encoded return payload, or `null`. Decode using the ABI corresponding to `signature_hash`.
</ResponseField>

<ResponseField name="data.timestamp_utc" type="string">
  Observation timestamp (ISO-8601), aligned with the snapshot.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Internal lineage identifier (hex string, no `0x` prefix) for cross-referencing with lineage endpoints.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Pagination cursor to continue the query.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in this page.
</ResponseField>

## Use Cases

* Refresh oracle or configuration caches with latest per-block values.
* Detect contract parameter changes by diffing consecutive results.
* Seed lineage exploration by pairing selectors with their upstream transactions and logs.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/function-results" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "signature_hashes": [
      "0902f1ac"
    ],
    "from_block": 18934000,
    "to_block": 18935000,
    "from_timestamp": null,
    "to_timestamp": null,
    "latest_only": false,
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"contract_addresses\":[\"1234567890abcdef1234567890abcdef12345678\"],\"signature_hashes\":[\"0902f1ac\"],\"from_block\":18934000,\"to_block\":18935000,\"from_timestamp\":null,\"to_timestamp\":null,\"latest_only\":false,\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/function-results");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"contract_addresses\":[\"1234567890abcdef1234567890abcdef12345678\"],\"signature_hashes\":[\"0902f1ac\"],\"from_block\":18934000,\"to_block\":18935000,\"from_timestamp\":null,\"to_timestamp\":null,\"latest_only\":false,\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/function-results", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/function-results",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1,
   'contract_addresses': ['1234567890abcdef1234567890abcdef12345678'],
   'cursor': None,
   'from_block': 18934000,
   'from_timestamp': None,
   'latest_only': False,
   'limit': 200,
   'signature_hashes': ['0902f1ac'],
   'to_block': 18935000,
   'to_timestamp': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/function-results", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "signature_hashes": [
      "0902f1ac"
    ],
    "from_block": 18934000,
    "to_block": 18935000,
    "from_timestamp": null,
    "to_timestamp": null,
    "latest_only": false,
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "contract_addresses": [
      "1234567890abcdef1234567890abcdef12345678"
    ],
    "signature_hashes": [
      "0902f1ac"
    ],
    "from_block": 18934000,
    "to_block": 18935000,
    "from_timestamp": null,
    "to_timestamp": null,
    "latest_only": false,
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/function-results", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 18934000,
        "to_block": 18935000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 18934000,
        "to_block": 18935000,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "contract_addresses": [
          "1234567890abcdef1234567890abcdef12345678"
        ],
        "signature_hashes": [
          "0902f1ac"
        ],
        "latest_only": false
      }
    },
    "data": [
      {
        "contract_id": "1234567890abcdef1234567890abcdef1234567800121a0700",
        "block_number": 18934560,
        "block_time": "2024-04-01T12:34:56.000Z",
        "call_data": "0902f1ac",
        "signature_hash": "0902f1ac",
        "result": "0000000000000000000000000000000000000000000000000de0b6b3a7640000",
        "timestamp_utc": "2024-04-01T12:34:56.000Z",
        "_tracing_id": "0122000000000000000000000000000000000001",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Internal Transactions
Source: https://docs.blockdb.io/api-reference/evm/primitives/internal-transactions

POST https://api.blockdb.io/v1/evm/raw/internal-transactions
Query internal transactions (call traces) from debug_traceTransaction with call type, value, gas, and revert data.

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0111 - Internal Transactions`](/data-catalog/evm/primitives/internal-transactions)
* **Description:** Internal transactions (call traces) from `debug_traceTransaction`. Response rows mirror `blockdb_evm.b0111_internal_transactions_v1` (hex strings without `0x` for `BYTEA` fields in JSON).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Internal-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0111_internal_transactions_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Internal-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0111_internal_transactions_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or explicit selectors.\
  Providing more than one option (e.g., both ranges or ranges plus selectors) results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Explicit set of block numbers. Mutually exclusive with `tx_hashes`.
</ParamField>

<ParamField type="string[]">
  Filter by parent transaction hash (hex string, 32 bytes, no `0x` prefix). Returns all call traces for those transactions. Mutually exclusive with `block_numbers`.
</ParamField>

#### Address & Type Filters

<ParamField type="string">
  Filter by caller address (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Filter by callee address (hex string, 20 bytes, no `0x` prefix). Failed CREATE/CREATE2 may have null `to_address` and are excluded when this filter is present.
</ParamField>

<ParamField type="string[]">
  Filter by call type: `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2`. Omit to return all types.
</ParamField>

<ParamField type="boolean">
  Filter by underlying transaction success (`true` = success, `false` = reverted). Omit to return traces for both.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (addresses, call\_types, tx\_success, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of internal transaction (call trace) records, ordered by block, tx index, and trace address.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block number of the parent transaction.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the block (ISO-8601).
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index of the parent transaction within the block.
</ResponseField>

<ResponseField name="data.trace_address" type="string">
  Position in the call tree (e.g. `"0"`, `"0.0"`, `"0.1"`).
</ResponseField>

<ResponseField name="data.call_type" type="string">
  One of: `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2`.
</ResponseField>

<ResponseField name="data.from_address" type="string">
  Caller address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.to_address" type="string | null">
  Callee address (hex string, 20 bytes); null for failed CREATE/CREATE2.
</ResponseField>

<ResponseField name="data.value_wei" type="string">
  Native value transferred in this call, in wei (string to preserve precision).
</ResponseField>

<ResponseField name="data.gas" type="string | null">
  Gas allocated for this call (string to preserve precision); null when disabled from indexing.
</ResponseField>

<ResponseField name="data.gas_used" type="string | null">
  Gas consumed by this call (string to preserve precision); null when disabled from indexing.
</ResponseField>

<ResponseField name="data.input" type="string | null">
  Calldata for this call (hex string, no `0x` prefix); null when disabled from indexing.
</ResponseField>

<ResponseField name="data.output" type="string | null">
  Return data from the call (hex string, no `0x` prefix when present); null when disabled from indexing or if the call reverted or return data is absent in the source trace.
</ResponseField>

<ResponseField name="data.error" type="string | null">
  Error message if the call reverted; null otherwise.
</ResponseField>

<ResponseField name="data.tx_success" type="boolean">
  Success of the underlying parent transaction that produced this internal call.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Internal tracing ID for observability (hex string, no `0x` prefix); unique per row.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp, e.g. `"2025-11-11T18:42:15.123Z"`.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp in the same format.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/internal-transactions" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_address": "0000000000000000000000000000000000000000",
    "to_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "call_types": ["CALL", "DELEGATECALL"],
    "tx_success": true,
    "limit": 250,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"limit\":250,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/internal-transactions");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"limit\":250,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/internal-transactions", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/internal-transactions",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "from_block": 12345678,
          "to_block": 12345999,
          "tx_hashes": ["7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"],
          "call_types": ["CALL", "DELEGATECALL"],
          "limit": 250,
          "cursor": None
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/internal-transactions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      tx_hashes: ["7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"],
      call_types: ["CALL", "DELEGATECALL"],
      limit: 250,
      cursor: null
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "limit": 250,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/internal-transactions", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "from_address": "0000000000000000000000000000000000000000",
        "to_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "call_types": [
          "CALL",
          "DELEGATECALL"
        ],
        "tx_success": true,
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "block_number": 12345680,
        "block_time": "2025-10-29T00:01:23Z",
        "tx_index": 5,
        "trace_address": "0",
        "call_type": "CALL",
        "from_address": "0000000000000000000000000000000000000000",
        "to_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "value_wei": "1000000000000000000",
        "gas": null,
        "gas_used": null,
        "input": null,
        "output": null,
        "error": null,
        "tx_success": true,
        "_tracing_id": "0111000000000000000000000000000000000001",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      },
      {
        "block_number": 12345680,
        "block_time": "2025-10-29T00:01:23Z",
        "tx_index": 5,
        "trace_address": "0.1",
        "call_type": "DELEGATECALL",
        "from_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "to_address": "0000000000000000000000000000000000000001",
        "value_wei": "0",
        "gas": null,
        "gas_used": null,
        "input": null,
        "output": null,
        "error": null,
        "tx_success": true,
        "_tracing_id": "0111000000000000000000000000000000000002",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": "next_page_cursor",
    "page_count": 2
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "body",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_block",
            "location": "body",
            "reason": "required_with",
            "expected": "provide either block range (from_block + to_block), time range (from_timestamp + to_timestamp), or tx_hashes / block_numbers"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by from_address, to_address, call_types, or tx_hashes"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Logs
Source: https://docs.blockdb.io/api-reference/evm/primitives/logs

POST https://api.blockdb.io/v1/evm/raw/logs
Query decoded EVM log events with flexible topic filters.

## Overview

* **Dataset ID:** [`0103 - Logs`](/data-catalog/evm/primitives/logs)
* **Description:** Event logs emitted by contract transactions.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Logs-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0103_logs_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Logs-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0103_logs_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  Every request must include at least one primary criterion: a block range (`from_block`/`to_block`), a time range (`from_timestamp`/`to_timestamp`), `block_numbers`, or `tx_hashes`. A block range and a time range are mutually exclusive, as are `block_numbers` and `tx_hashes`.\
  `contract_addresses` and `topic_zeros` are **refinement filters** that require a **block range or time range** specifically — they cannot be used on their own, and a `block_numbers`/`tx_hashes` set does not satisfy this (an unbounded scan over a hot contract or topic would time out).\
  Providing none of the above results in HTTP 400.
</Warning>

#### Bounding Windows

<ParamField type="number[]">
  Explicit set of block numbers (a bounding window). Mutually exclusive with `tx_hashes`.
</ParamField>

<ParamField type="string[]">
  Filter logs by parent transaction hash (hex string, 32 bytes, no `0x` prefix); a bounding window. Mutually exclusive with `block_numbers`.
</ParamField>

#### Contract & Topic Filters

<ParamField type="string[]">
  Filter by emitting contract address (hex string, 20 bytes, no `0x` prefix). Requires a block range or time range.
</ParamField>

<ParamField type="string[]">
  Filter by the primary event topic. Anonymous events have `topic_zero = null`. Requires a block range or time range.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (block numbers, tx hashes, contract addresses, topics).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element mirrors the table columns (chain implied by `meta.chain_id`). Resolve transaction hash via `block_number` + `tx_index` and the transactions dataset if needed — there is no `tx_hash` column in SQL.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height containing the log.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the `blocks` table for easier aggregation.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index of the parent transaction within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Position of the log within the transaction.
</ResponseField>

<ResponseField name="data.contract_address" type="string">
  Address of the emitting contract (20 bytes).
</ResponseField>

<ResponseField name="data.topic_zero" type="string">
  Primary topic hash identifying the event (32 bytes). `null` for anonymous events.
</ResponseField>

<ResponseField name="data.data_topics" type="string[]">
  Subsequent event topics (`topics[1..n]`), each stored as a 32-byte hex string.
</ResponseField>

<ResponseField name="data.data" type="string">
  Raw event data payload (hex string (no `0x` prefix)).
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Tracing identifier for the canonical transaction record (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/logs" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "contract_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "topic_zeros": [
      "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ],
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/logs");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/logs", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/logs",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_numbers': [12345678, 12345679],
   'chain_id': 1,
   'contract_addresses': ['0000000000000000000000000000000000000000'],
   'from_block': 12345678,
  'from_timestamp': '2025-10-29T00:00:00Z',
  'to_block': 12345999,
  'to_timestamp': '2025-11-11T00:00:00Z',
  'topic_zeros': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
  'tx_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
  'limit': 200,
  'cursor': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/logs", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "contract_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "topic_zeros": [
      "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ],
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "contract_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "topic_zeros": [
      "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ],
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/logs", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "block_numbers": [
          12345678,
          12345679
        ],
        "tx_hashes": [
          "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
        ],
        "contract_addresses": [
          "0000000000000000000000000000000000000000"
        ],
        "topic_zeros": [
          "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        ]
      }
    },
    "data": [
      {
        "block_number": 12345678,
        "block_time": "2025-11-11T18:42:15.123Z",
        "tx_index": 4,
        "log_index": 0,
        "contract_address": "0000000000000000000000000000000000000000",
        "topic_zero": "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "data_topics": [
          "0000000000000000000000000000000000000000000000000000000000000000",
          "0000000000000000000000000000000000000000000000000000000000000001"
        ],
        "data": "00000000000000000000000000000000000000000000000000000000000003e8",
        "_tracing_id": "0103000000000000000000000000000000000000",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Raw Data Overview
Source: https://docs.blockdb.io/api-reference/evm/primitives/overview

Access canonical blockchain primitives: blocks, transactions, logs, contracts, and function results.

## Overview

The Raw Data suite provides direct access to on-chain execution artifacts with cryptographic verification metadata. These endpoints deliver the foundational blockchain primitives that power all derived datasets. Each endpoint includes lineage fields (`_tracing_id`) that link records back to their on-chain origins.

### Endpoint Matrix

| Endpoint                                                                                     | Summary                                                                | Dataset ID | Typical Latency |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------- | --------------- |
| [`POST /evm/raw/blocks`](/api-reference/evm/primitives/blocks)                               | Retrieve canonical EVM blocks with integrity metadata                  | `0101`     | \< 200 ms       |
| [`POST /evm/raw/blocks-summary`](/api-reference/evm/primitives/blocks-summary)               | Aggregated block metrics (gas, throughput, fees) over a range          | —          | \< 300 ms       |
| [`POST /evm/raw/transactions`](/api-reference/evm/primitives/transactions)                   | Executed transactions with gas accounting and lineage                  | `0102`     | \< 200 ms       |
| [`POST /evm/raw/logs`](/api-reference/evm/primitives/logs)                                   | Decoded event logs with topic filters                                  | `0103`     | \< 200 ms       |
| [`POST /evm/raw/contracts`](/api-reference/evm/primitives/contracts)                         | Contract deployment metadata (contract\_id, supports metamorphic)      | `0121`     | \< 200 ms       |
| [`POST /evm/raw/function-results`](/api-reference/evm/primitives/function-results)           | Deterministic contract call outputs versioned by block (contract\_id)  | `0122`     | \< 250 ms       |
| [`POST /evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions) | Call traces (debug\_traceTransaction) with value, gas, and revert data | `0111`     | \< 300 ms       |

### Parameter Conventions

<ParamField type="number">
  Starting block height (inclusive) for range queries.
</ParamField>

<ParamField type="number">
  Ending block height (inclusive) for range queries.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="number[]">
  Explicit list of block heights for precise lookups.
</ParamField>

<ParamField type="string[]">
  Parent transaction hashes (hex string, 32 bytes, no `0x` prefix) for targeted retrievals.
</ParamField>

<ParamField type="string[]">
  Block hashes (hex string, 32 bytes, no `0x` prefix) for exact matching.
</ParamField>

<ParamField type="string[]">
  Contract addresses (hex string, 20 bytes, no `0x` prefix) to scope results to specific contracts.
</ParamField>

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="string">
  Pagination cursor returned from previous responses.
</ParamField>

<ParamField type="number">
  Maximum number of records to return.
</ParamField>

### Usage Guidance

* **Start with blocks** — Use `/evm/blocks` to establish time ranges before querying transactions or logs
* **Batch array filters** — Prefer array filters (`block_numbers`, `tx_hashes`) over range queries for better performance
* **Join via `_tracing_id`** — Use lineage identifiers to join across datasets (blocks → transactions → logs)
* **Cache function-results** — Deterministic outputs are immutable; cache aggressively to reduce API calls

### Common Patterns

**Get all transactions in a block:**

```json theme={null}
{
  "chain_id": 1,
  "block_numbers": [
    12345678
  ]
}
```

**Find logs for specific event:**

```json theme={null}
{
  "chain_id": 1,
  "topic_zeros": [
    "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
  ],
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z"
}
```

**Lookup contract deployment:**

```json theme={null}
{
  "chain_id": 1,
  "contract_addresses": [
    "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  ]
}
```

### See also

* [`POST /evm/raw/blocks`](/api-reference/evm/primitives/blocks) — Block headers and integrity metadata
* [`POST /evm/raw/transactions`](/api-reference/evm/primitives/transactions) — Transaction execution data
* [`POST /evm/raw/logs`](/api-reference/evm/primitives/logs) — Event log emissions
* [`POST /evm/raw/contracts`](/api-reference/evm/primitives/contracts) — Contract deployment records
* [`POST /evm/raw/function-results`](/api-reference/evm/primitives/function-results) — Contract call outputs
* [`POST /evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions) — Call traces (internal txs)


# Transactions
Source: https://docs.blockdb.io/api-reference/evm/primitives/transactions

POST https://api.blockdb.io/v1/evm/raw/transactions
Filter canonical transactions with execution metadata and gas accounting.

## Overview

* **Dataset ID:** [`0102 - Transactions`](/data-catalog/evm/primitives/transactions)
* **Description:** Transactions included in blocks.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0102_transactions_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0102_transactions_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or explicit selectors.\
  Providing more than one option (e.g., both ranges or ranges plus selectors) results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Direct Selectors

<ParamField type="number[]">
  Explicit set of block numbers. Mutually exclusive with `tx_hashes`.
</ParamField>

<ParamField type="string[]">
  Explicit set of transaction hashes (hex string, 32 bytes, no `0x` prefix). Mutually exclusive with `block_numbers`.
</ParamField>

#### Address & Type Filters

<ParamField type="string[]">
  Filter by sender address (20 bytes, hex string, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by recipient address (20 bytes, hex string, no `0x` prefix). Contract-creation transactions set `to_address` to `null` and are excluded when this filter is present.
</ParamField>

<ParamField type="string[]">
  Filter by contract addresses created by the transaction.
</ParamField>

<ParamField type="boolean">
  Filter by execution status (`true` = success, `false` = revert). Omit to include pre-Byzantium transactions with `null` status.
</ParamField>

<ParamField type="number[]">
  Filter by transaction type ID (e.g., `2` = EIP-1559, `1` = legacy).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Opaque pagination cursor supplied by a previous response.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters (block numbers, hashes, addresses, status flags) echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of transaction objects.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height containing the transaction.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp joined from the `blocks` table for easier aggregation.
</ResponseField>

<ResponseField name="data.tx_hash" type="string">
  Keccak-256 hash of the transaction (32 bytes, hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index within the block; directly verifiable from RLP.
</ResponseField>

<ResponseField name="data.from_address" type="string">
  Sender address (20 bytes).
</ResponseField>

<ResponseField name="data.to_address" type="string | null">
  Recipient address (20 bytes). `null` denotes contract creation.
</ResponseField>

<ResponseField name="data.created_contract_address" type="string | null">
  Address of the contract created by this transaction. `null` for non-creation transactions.
</ResponseField>

<ResponseField name="data.gas_used" type="string">
  Gas consumed by the transaction (string to preserve `NUMERIC(78)` precision).
</ResponseField>

<ResponseField name="data.effective_gas_price_wei" type="string">
  Effective gas price paid, expressed in wei (string to preserve precision).
</ResponseField>

<ResponseField name="data.status_success" type="boolean">
  Execution status: `true` = success, `false` = revert, `null` for pre-Byzantium blocks.
</ResponseField>

<ResponseField name="data.root" type="string">
  Post-transaction state root for pre-Byzantium blocks (32 bytes).
</ResponseField>

<ResponseField name="data.tx_type" type="number">
  Transaction type identifier (e.g., `2` = EIP-1559, `1` = legacy).
</ResponseField>

<ResponseField name="data.trace_failed" type="boolean | null">
  `true` if trace failed, `false` if trace succeeded, `null` if trace not available.
</ResponseField>

<ResponseField name="data.value_wei" type="string">
  Value transferred in wei (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="data.input" type="string">
  Calldata sent with the transaction (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data.nonce" type="number">
  Sender nonce.
</ResponseField>

<ResponseField name="data.gas_limit" type="string">
  Gas limit provided by the sender (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="data.gas_price_wei" type="string">
  Legacy gas price in wei (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="data.max_fee_per_gas_wei" type="string">
  Max fee per gas in wei for EIP-1559 transactions (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="data.max_priority_fee_per_gas_wei" type="string">
  Max priority fee per gas in wei for EIP-1559 transactions (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Tracing identifier for the canonical transaction record (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/raw/transactions" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "from_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "to_addresses": [
      "0000000000000000000000000000000000000001"
    ],
    "created_contract_addresses": [
      "0000000000000000000000000000000000000002"
    ],
    "status_success": true,
    "tx_types": [
      0,
      1,
      2
    ],
    "limit": 200,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"from_addresses\":[\"0000000000000000000000000000000000000000\"],\"to_addresses\":[\"0000000000000000000000000000000000000001\"],\"created_contract_addresses\":[\"0000000000000000000000000000000000000002\"],\"status_success\":true,\"tx_types\":[0,1,2],\"limit\":200,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/transactions");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"from_addresses\":[\"0000000000000000000000000000000000000000\"],\"to_addresses\":[\"0000000000000000000000000000000000000001\"],\"created_contract_addresses\":[\"0000000000000000000000000000000000000002\"],\"status_success\":true,\"tx_types\":[0,1,2],\"limit\":200,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/transactions", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/raw/transactions",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_numbers': [12345678, 12345679],
   'chain_id': 1,
   'created_contract_addresses': ['0000000000000000000000000000000000000002'],
   'from_addresses': ['0000000000000000000000000000000000000000'],
   'from_block': 12345678,
   'from_timestamp': '2025-10-29T00:00:00Z',
   'status_success': True,
   'to_addresses': ['0000000000000000000000000000000000000001'],
   'to_block': 12345999,
   'to_timestamp': '2025-11-11T00:00:00Z',
   'tx_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
   'tx_types': [0, 1, 2],
   'limit': 200,
   'cursor': None}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/raw/transactions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "from_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "to_addresses": [
      "0000000000000000000000000000000000000001"
    ],
    "created_contract_addresses": [
      "0000000000000000000000000000000000000002"
    ],
    "status_success": true,
    "tx_types": [
      0,
      1,
      2
    ],
    "limit": 200,
    "cursor": null
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_timestamp": "2025-10-29T00:00:00Z",
    "to_timestamp": "2025-11-11T00:00:00Z",
    "block_numbers": [
      12345678,
      12345679
    ],
    "tx_hashes": [
      "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
    ],
    "from_addresses": [
      "0000000000000000000000000000000000000000"
    ],
    "to_addresses": [
      "0000000000000000000000000000000000000001"
    ],
    "created_contract_addresses": [
      "0000000000000000000000000000000000000002"
    ],
    "status_success": true,
    "tx_types": [
      0,
      1,
      2
    ],
    "limit": 200,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/transactions", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "block_numbers": [
          12345678,
          12345679
        ],
        "tx_hashes": [
          "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
        ],
        "from_addresses": [
          "0000000000000000000000000000000000000000"
        ],
        "to_addresses": [
          "0000000000000000000000000000000000000001"
        ],
        "created_contract_addresses": [
          "0000000000000000000000000000000000000002"
        ],
        "status_success": true,
        "tx_types": [
          0,
          1,
          2
        ]
      }
    },
    "data": [
      {
        "block_number": 12345678,
        "block_time": "2025-11-11T18:42:15.123Z",
        "tx_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
        "tx_index": 4,
        "from_address": "0000000000000000000000000000000000000000",
        "to_address": "0000000000000000000000000000000000000001",
        "created_contract_address": null,
        "gas_used": "21000",
        "effective_gas_price_wei": "1234567890123456789",
        "status_success": true,
        "root": null,
        "tx_type": 2,
        "trace_failed": false,
        "value_wei": "0",
        "input": "a9059cbb000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000003e8",
        "nonce": 7,
        "gas_limit": 21000,
        "gas_price_wei": "1234567890",
        "max_fee_per_gas_wei": "2000000000",
        "max_priority_fee_per_gas_wei": "1000000000",
        "_tracing_id": "010200000000000000000000000000000000",
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Liquidity Distribution
Source: https://docs.blockdb.io/api-reference/evm/reserves/liquidity-distribution

POST https://api.blockdb.io/v1/evm/reserves/liquidity-distribution
On-demand per-tick liquidity and token amounts for concentrated liquidity pools.

## Overview

* **Dataset ID:** [`0301 - Liquidity Pool Reserves`](/data-catalog/evm/reserves/liquidity-pools-reserves)
* **Description:** Retrieves the full tick-level liquidity distribution for a single concentrated-liquidity pool snapshot (Uniswap v3/v4-style). Amounts are computed on demand from the stored `liquidity_values` blob — no pre-aggregated detail table is queried.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.json?download=true)

Returns the full tick-level liquidity distribution for a single concentrated-liquidity pool snapshot
(Uniswap v3/v4-style). Amounts are computed on demand from the stored `liquidity_values` blob —
no pre-aggregated detail table is queried.

**Key characteristics:**

* Returns one snapshot per call (the most recent within the requested block/time window)
* Configurable price window: `1.0`-`10.0`% symmetric band around the current price
* Each tick row carries both raw (`amount0_raw`) and decimals-adjusted (`amount0`) amounts

<Note>
  For **even-distribution** pools (Uniswap v2, Balancer, etc.) use
  [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves).
</Note>

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Pool Selector (exactly one required)

<ParamField type="string">
  BlockDB 32-byte pool identifier (hex, no `0x`).
</ParamField>

<ParamField type="string">
  Pool contract address (hex, 20 bytes, no `0x`).
</ParamField>

<ParamField type="string">
  Protocol-specific pool ID, e.g. Uniswap V4 `pool_id` (hex, 32 bytes, no `0x`).
</ParamField>

<Warning>
  Provide **exactly one** of `pool_uid`, `pool_address`, or `pool_id`. Providing more or fewer results in HTTP 400.
</Warning>

#### Snapshot Selector (exactly one required)

<ParamField type="string">
  Direct snapshot key (hex, no `0x`). When set, block/time range must not be provided.
</ParamField>

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`. The most recent snapshot within the range is returned.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

#### Price Window

<ParamField type="number">
  Symmetric percent band around the current price tick, e.g. `5.0` = ±5%.
  Must be between `1.0` and `10.0` inclusive. Values outside this range return HTTP 400.
</ParamField>

#### Amounts

<ParamField type="boolean">
  Off by default. When set to `true`, each tick row includes `amount0` and `amount1` scaled by ERC-20
  decimals. Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency, so it
  is opt-in; when omitted or `false`, `amount0`/`amount1` are `null` and only the always-present
  `amount0_raw`/`amount1_raw` fields are populated.
</ParamField>

## Response Fields

#### Envelope

<ResponseField name="chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="request_window" type="object">
  Block/timestamp bounds echoed from the request.
</ResponseField>

<ResponseField name="filters" type="object">
  Filters echoed from the request.
</ResponseField>

<ResponseField name="snapshot" type="object">
  The single resolved snapshot.
</ResponseField>

#### Snapshot Fields

<ResponseField name="snapshot.pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="snapshot.exchange_id" type="number">
  Exchange identifier.
</ResponseField>

<ResponseField name="snapshot.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="snapshot.block_number" type="number">
  Block height of the snapshot.
</ResponseField>

<ResponseField name="snapshot.block_time" type="string">
  Block timestamp (ISO-8601).
</ResponseField>

<ResponseField name="snapshot.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="snapshot.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="snapshot.tick_spacing" type="number">
  Pool tick spacing (e.g. `60` for a 0.3% Uniswap v3 pool).
</ResponseField>

<ResponseField name="snapshot.current_tick" type="number">
  Active tick at the time of the snapshot.
</ResponseField>

<ResponseField name="snapshot.current_sqrt_price" type="string">
  Q64.96 sqrt price as an integer string.
</ResponseField>

<ResponseField name="snapshot.price_window_percent" type="number">
  Echoed from the request.
</ResponseField>

<ResponseField name="snapshot.resolved_lower_tick" type="number">
  Actual lower bound of the tick range returned (aligned to tick spacing).
</ResponseField>

<ResponseField name="snapshot.resolved_upper_tick" type="number">
  Actual upper bound of the tick range returned.
</ResponseField>

<ResponseField name="snapshot.token0_address" type="string | null">
  Token0 contract address (hex, no `0x`). Populated when pool metadata is available.
</ResponseField>

<ResponseField name="snapshot.token1_address" type="string | null">
  Token1 contract address (hex, no `0x`). Populated when pool metadata is available.
</ResponseField>

<ResponseField name="snapshot.token0_decimals" type="number | null">
  ERC-20 decimals for token0. `null` when unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.token1_decimals" type="number | null">
  ERC-20 decimals for token1. `null` when unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.ticks" type="object[]">
  Ordered array of tick rows within the resolved range. Only ticks with non-zero liquidity are included.
</ResponseField>

<ResponseField name="snapshot._tracing_id" type="string">
  Lineage hash for the snapshot row.
</ResponseField>

#### Tick Row Fields (`snapshot.ticks[]`)

<ResponseField name="snapshot.ticks[].tick" type="number">
  Lower tick of this liquidity position (same as `lower_tick`).
</ResponseField>

<ResponseField name="snapshot.ticks[].lower_tick" type="number">
  Lower bound of the tick interval.
</ResponseField>

<ResponseField name="snapshot.ticks[].upper_tick" type="number">
  Upper bound of the tick interval (`lower_tick + tick_spacing`).
</ResponseField>

<ResponseField name="snapshot.ticks[].liquidity" type="string">
  Uniswap v3 liquidity value (L) for this tick as an integer string.
</ResponseField>

<ResponseField name="snapshot.ticks[].amount0_raw" type="string">
  Token0 amount at this tick in base units (integer string, no decimals applied).
</ResponseField>

<ResponseField name="snapshot.ticks[].amount0" type="string | null">
  Token0 amount divided by `10^token0_decimals`.
  `null` when decimals are unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.ticks[].amount1_raw" type="string">
  Token1 amount at this tick in base units (integer string, no decimals applied).
</ResponseField>

<ResponseField name="snapshot.ticks[].amount1" type="string | null">
  Token1 amount divided by `10^token1_decimals`.
  `null` when decimals are unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<RequestExample>
  ```bash cURL — ±5% window theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
    "from_block": 20000000,
    "to_block": 20001000,
    "price_window_percent": 5.0,
    "include_adjusted_amounts": true
  }'
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
          "from_block": 20000000,
          "to_block": 20001000,
          "price_window_percent": 5.0,
          "include_adjusted_amounts": True
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/reserves/liquidity-distribution", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "from_block": 20000000,
      "to_block": 20001000,
      "price_window_percent": 5.0,
      "include_adjusted_amounts": true
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"pool_uid\":\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\",\"from_block\":20000000,\"to_block\":20001000,\"price_window_percent\":5.0,\"include_adjusted_amounts\":true}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync(
              "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution", payload);
          response.EnsureSuccessStatusCode();

          Console.WriteLine(await response.Content.ReadAsStringAsync());
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "chain_id": 1,
    "request_window": {
      "from_block": 20000000,
      "to_block": 20001000,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "filters": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "pool_address": null,
      "pool_id": null,
      "tracing_id": null,
      "price_window_percent": 5.0,
      "include_adjusted_amounts": true
    },
    "snapshot": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 301,
      "block_number": 20000842,
      "block_time": "2025-11-11T18:42:15.123Z",
      "tx_index": 12,
      "log_index": 3,
      "tick_spacing": 60,
      "current_tick": 210130,
      "current_sqrt_price": "14614467034852101032872730522039888223787",
      "price_window_percent": 5.0,
      "resolved_lower_tick": 209580,
      "resolved_upper_tick": 210660,
      "token0_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token1_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "token0_decimals": 18,
      "token1_decimals": 6,
      "ticks": [
        {
          "tick": 210060,
          "lower_tick": 210060,
          "upper_tick": 210120,
          "liquidity": "5823941670000000000000000000",
          "amount0_raw": "1000000000000000000",
          "amount0": "1.0",
          "amount1_raw": "2500000000",
          "amount1": "2500.0"
        },
        {
          "tick": 210120,
          "lower_tick": 210120,
          "upper_tick": 210180,
          "liquidity": "9104823200000000000000000000",
          "amount0_raw": "840000000000000000",
          "amount0": "0.84",
          "amount1_raw": "1890000000",
          "amount1": "1890.0"
        },
        "..."
      ],
      "_tracing_id": "0301000000000000000000000000000000000002"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "price_window_percent must be between 1 and 10.",
      "hint": "Use a value in [1.0, 10.0], e.g. 5.0 for ±5%.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/evm/reserves/liquidity-distribution"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "No concentrated-liquidity reserves snapshot was found for the given parameters.",
      "hint": "Verify the pool selector and block/time range. This endpoint only returns snapshots that contain liquidity_values data.",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/evm/reserves/liquidity-distribution"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "severity": "critical",
      "retryable": true,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Pools Reserves Overview
Source: https://docs.blockdb.io/api-reference/evm/reserves/overview

Access normalized pool reserve snapshots for on-chain liquidity analytics and time-series analysis.

## Overview

The Pools Reserves endpoints provide time-series snapshots of AMM pool liquidity states. Reserve data is normalized across pool types (constant-product, concentrated liquidity, weighted, bin-based) to enable consistent analytics regardless of the underlying AMM. Each snapshot includes lineage metadata linking back to on-chain state changes.

### Endpoint Matrix

| Endpoint                                                                                             | Summary                                                          | Dataset ID | Typical Latency |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------- | --------------- |
| [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves)                                      | Normalized reserve snapshots with decimals-adjusted amounts      | `0301`     | \< 250 ms       |
| [`POST /v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) | Per-tick liquidity distribution for concentrated liquidity pools | `0301`     | \< 400 ms       |

### Parameter Conventions

<ParamField type="number">
  Starting block height (inclusive) for reserve snapshots.
</ParamField>

<ParamField type="number">
  Ending block height (inclusive) for reserve snapshots.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="string[]">
  BlockDB pool identifiers for direct lookups.
</ParamField>

<ParamField type="string[]">
  Pool contract addresses to scope reserve data.
</ParamField>

<ParamField type="string[]">
  Provider-specific pool identifiers when applicable.
</ParamField>

<ParamField type="number[]">
  Exchange identifiers for filtering by DEX protocol.
</ParamField>

<ParamField type="number[]">
  AMM model filters. Use [Pool Type enumeration](/api-reference/enumerations/pool-type) values.
</ParamField>

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="boolean">
  Off by default. When set to `true`, reserve amounts and tick amounts are also returned scaled by ERC-20
  token decimals. Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency,
  so it is opt-in; when omitted or `false`, only the always-present raw base-unit fields are populated.
</ParamField>

### Usage Guidance

* **Join with pools metadata** — Link reserve snapshots to pool metadata via `pool_uid` for complete context
* **Time-series analysis** — Reserve data is optimized for chronological queries; use block/time ranges for historical analysis
* **Filter by exchange** — Use `exchange_ids` to focus on specific DEX protocols (Uniswap, Curve, etc.)
* **Concentrated liquidity** — Use [`/v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) for per-tick breakdown with a configurable price window (1–10%)
* **Decimals-adjusted amounts** — Enable `include_adjusted_amounts` (off by default) to receive human-readable token amounts alongside raw base-unit values; it adds a decimals lookup, so opt in only when you need the scaled values
* **Cache recent snapshots** — Latest reserve states change frequently; cache with short TTL (1–5 minutes)

### Reserve Data Models

**Even-Distribution Pools** (Uniswap v2, SushiSwap, Balancer):

* `reserves`: Array of raw token balances (base units)
* `reserves_decimals_adjusted`: Same values divided by each token's decimals (e.g. `/ 10^18` for ETH)
* `current_tick`: `null`
* `current_sqrt_price`: `null`

**Concentrated Liquidity** (Uniswap v3/v4, SushiSwap v3, PancakeSwap v3):

* `reserves`: `null` (reserves are distributed across ticks)
* `current_tick`: Active tick position
* `current_sqrt_price`: Q64.96 sqrt price
* For per-tick distribution → use [`/v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution)

**Bin-Based Pools** (TraderJoe v2, Aerodrome Slipstream):

* `current_bin`: Active bin identifier

### Common Patterns

**Track pool reserves over time:**

```json theme={null}
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z",
  "include_adjusted_amounts": true
}
```

**Get reserves for all Uniswap v2 pools (raw amounts only):**

```json theme={null}
{
  "chain_id": 1,
  "pool_type_ids": [201],
  "from_block": 18000000,
  "to_block": 18001000,
  "include_adjusted_amounts": false
}
```

**Analyze concentrated liquidity tick distribution (±5% around spot):**

```json theme={null}
{
  "chain_id": 1,
  "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
  "from_block": 20000000,
  "to_block": 20001000,
  "price_window_percent": 5.0,
  "include_adjusted_amounts": true
}
```

### Dataset Relationships

* **Pools → Reserves**: Join pool metadata to reserve snapshots using `pool_uid`
* **Reserves → Swap Fees**: Combine swap-fee time-series with reserve state for pool economics
* **Swap Fees → Yields**: Yield predictions are derived from swap fees and current reserves
* **Reserves → Prices**: Reserve changes drive pricing calculations in L1/L2/L3 layers
* **Reserves → Transactions**: Reserve snapshots link to transaction logs via `_parent_tracing_ids`

### See Also

* [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves) — Reserve snapshots with decimals-adjusted amounts
* [`POST /v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) — Per-tick liquidity distribution
* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Per-swap fee accounting
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications
* [Digital Exchange](/api-reference/enumerations/digital-exchange) — DEX protocol identifiers
* [Pricing Suite Overview](/api-reference/evm/prices/crypto/overview) — Price data derived from reserves


# Reserves
Source: https://docs.blockdb.io/api-reference/evm/reserves/reserves

POST https://api.blockdb.io/v1/evm/reserves
Read normalized pool reserve snapshots for on-chain liquidity analytics.

## Overview

* **Dataset ID:** [`0301 - Liquidity Pool Reserves`](/data-catalog/evm/reserves/liquidity-pools-reserves)
* **Description:** Retrieves time-series snapshots of AMM pool reserves, covering both even-distribution (constant-product, weighted, stable) and concentrated/bin liquidity models.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_v1.json?download=true)

<Note>
  For **concentrated liquidity** (Uniswap v3/v4-style) tick distribution, use the dedicated
  [`POST /v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) endpoint,
  which computes per-tick amounts on demand with a configurable price window.
</Note>

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="number[]">
  Filter snapshots by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by BlockDB pool identifiers (`uid` from `/evm/entities/pools`).
</ParamField>

<ParamField type="string[]">
  Filter by pool contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by protocol-specific pool identifiers (e.g., Uniswap V4 `pool_id`).
</ParamField>

<ParamField type="number[]">
  Filter snapshots by pool archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

#### Amounts

<ParamField type="boolean">
  Off by default. When set to `true`, each snapshot includes `reserves_decimals_adjusted` — the same
  reserve amounts scaled by ERC-20 token decimals (e.g. dividing a USDC value by 10⁶). Enabling it adds a
  per-request ERC-20 decimals lookup (extra join) that increases latency, so it is opt-in; when omitted or
  `false`, `reserves_decimals_adjusted` is `null` and only the always-present raw `reserves` array is populated.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (e.g., exchange IDs, pool identifiers, pool types).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of reserve snapshot objects.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier (`uid` from `/evm/entities/pools`).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange identifier associated with the pool.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height where the reserve change was observed.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  Block timestamp when the event occurred.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based index of the parent transaction within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Position of the log within the transaction.
</ResponseField>

<ResponseField name="data.reserves" type="string[] | null">
  Current reserves per token in pool order, as raw integer strings (base units). `null` for concentrated-liquidity pools where reserves are not stored at the snapshot level.
</ResponseField>

<ResponseField name="data.reserves_decimals_adjusted" type="string[] | null">
  Same order as `reserves`, but each value divided by `10^decimals` for the corresponding ERC-20 token.
  `null` when decimals are unavailable for at least one pool token, when `reserves` is `null`, or when
  `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="data.current_tick" type="number | null">
  Current tick for concentrated-liquidity pools. `null` when not applicable.
</ResponseField>

<ResponseField name="data.current_sqrt_price" type="string | null">
  Q64.96 sqrt price as an integer string. `null` when not applicable.
</ResponseField>

<ResponseField name="data.current_bin" type="number | null">
  Current bin id for bin-style AMMs. `null` when not applicable.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash for the snapshot.
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Record last update timestamp.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/reserves" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "pool_type_ids": [201, 302],
    "include_adjusted_amounts": true
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"pool_type_ids\":[201,302],\"include_adjusted_amounts\":true}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/reserves");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"pool_type_ids\":[201,302],\"include_adjusted_amounts\":true}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/reserves", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/reserves",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "from_block": 12345678,
          "to_block": 12345999,
          "pool_uids": ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"],
          "pool_type_ids": [201, 302],
          "include_adjusted_amounts": True
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/reserves", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "from_block": 12345678,
      "to_block": 12345999,
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "pool_type_ids": [201, 302],
      "include_adjusted_amounts": true
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "pool_type_ids": [201, 302],
    "include_adjusted_amounts": true
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/reserves", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": null,
        "to_timestamp": null
      },
      "filters": {
        "exchange_ids": null,
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ],
        "pool_addresses": null,
        "pool_ids": null,
        "pool_type_ids": [201, 302]
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 18934567,
        "block_time": "2025-11-11T18:42:15.123Z",
        "tx_index": 4,
        "log_index": 2,
        "reserves": [
          "169649594140000000000000",
          "60446403492000"
        ],
        "reserves_decimals_adjusted": [
          "169649.59414",
          "60446403.492"
        ],
        "current_tick": null,
        "current_sqrt_price": null,
        "current_bin": null,
        "_tracing_id": "0301000000000000000000000000000000000000",
        "_parent_tracing_ids": [
          "0203000000000000000000000000000000000000"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      },
      ...
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io"
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "retry_after_seconds": 2,
        "limit_scope": "api_key"
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# JSON-RPC Example
Source: https://docs.blockdb.io/api-reference/evm/rpc/example

POST https://api.blockdb.io/v1/evm/rpc?chain_id=1
Detailed example of executing a standard Ethereum JSON-RPC method through BlockDB.

## Overview

BlockDB supports standard Ethereum JSON-RPC methods. This page provides a template for making calls to the JSON-RPC endpoint, including the expected request structure and response format.

## Request Parameters

Standard JSON-RPC 2.0 requests require the following fields in the JSON body:

<ParamField type="string">
  The version of the JSON-RPC protocol. Must be `"2.0"`.
</ParamField>

<ParamField type="string">
  The name of the Ethereum method to be invoked (e.g., `eth_getBlockByNumber`, `eth_call`, `eth_getBalance`).
</ParamField>

<ParamField type="array">
  A structured array of parameters for the specific method being called.
</ParamField>

<ParamField type="number | string">
  A unique identifier established by the client that will be echoed back in the response.
</ParamField>

## Response Fields

The JSON-RPC response follows the standard envelope:

<ResponseField name="jsonrpc" type="string">
  The version of the JSON-RPC protocol.
</ResponseField>

<ResponseField name="id" type="number | string">
  The unique identifier passed in the request.
</ResponseField>

<ResponseField name="result" type="any">
  The method-specific result object. The structure varies depending on the method invoked.
</ResponseField>

<ResponseField name="error" type="object">
  Present only if the request failed. Contains `code`, `message`, and optional `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/rpc?chain_id=1" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBlockByNumber",
      "params": ["latest", false]
    }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getBlockByNumber\",\"params\":[\"latest\",false]}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/rpc?chain_id=1");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getBlockByNumber\",\"params\":[\"latest\",false]}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/rpc?chain_id=1", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/rpc?chain_id=1",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "jsonrpc": "2.0",
          "id": 1,
          "method": "eth_getBlockByNumber",
          "params": ["latest", False]
      }
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/rpc?chain_id=1", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBlockByNumber",
      "params": ["latest", false]
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
          "jsonrpc": "2.0",
          "id": 1,
          "method": "eth_getBlockByNumber",
          "params": ["latest", false]
      }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/rpc?chain_id=1", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "number": "0x1213456",
      "hash": "0x7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
      "parentHash": "0xf78e26c5959a94d6a62ed3837f5dcecf0d3761bf0a502e12a08fd7bc44c8568d",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x0000000000000000000000000000000000000000",
      "stateRoot": "0x...",
      "transactionsRoot": "0x...",
      "receiptsRoot": "0x...",
      "logsBloom": "0x...",
      "difficulty": "0x0",
      "totalDifficulty": "0x...",
      "size": "0x...",
      "extraData": "0x...",
      "gasLimit": "0x1c9c380",
      "gasUsed": "0x...",
      "timestamp": "0x654f1234",
      "transactions": [],
      "uncles": []
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# JSON-RPC Overview
Source: https://docs.blockdb.io/api-reference/evm/rpc/overview

POST https://api.blockdb.io/v1/evm/rpc?chain_id=<chain_id>
Use BlockDB as an EVM JSON-RPC endpoint compatible with standard Ethereum execution-client methods.

## Overview

BlockDB exposes a **drop-in compatible Ethereum JSON-RPC** endpoint for EVM networks. Use it when you want to connect existing tooling (web3 libraries, indexers, bots) without rewriting to BlockDB's REST endpoint format.

This page documents the BlockDB entrypoint and the key conventions you need to call Ethereum JSON-RPC successfully.

## Endpoint

```text theme={null}
POST https://api.blockdb.io/v1/evm/rpc?chain_id=<chain_id>
```

### Authentication

Send your API key on every request:

```text theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

## Pricing

JSON-RPC access is included in all BlockDB plans.

* **Basic Plan**: Shared infrastructure, standard rate limits.
* **Standard & Platinum Plans**: High-throughput access with dedicated support options.

For more details, see [Pricing](/pricing/home).

## Method Compatibility

We support the **classic Ethereum execution-client JSON-RPC method families**, including:

* `eth_*`
* `net_*`

For the canonical method list and parameter conventions, see the Ethereum JSON-RPC reference:

* [Ethereum JSON-RPC API (execution client)](https://ethereum.org/developers/docs/apis/json-rpc/)

## Conventions (important)

### Hex encoding

Ethereum JSON-RPC uses hex encoding with specific rules:

* **Quantities** (block numbers, integers): hex with `0x` prefix, most compact form (`0x0` for zero)
* **Byte arrays** (hashes, addresses, calldata): hex with `0x` prefix, two hex digits per byte

### Block parameter

Many methods accept a “block parameter”. Common values include:

* `"earliest"`, `"latest"`, `"safe"`, `"finalized"`, `"pending"`
* A specific block number encoded as a hex quantity (e.g., `"0x12A05F"`).

## Examples

### Example: `eth_getBlockByNumber`

```bash theme={null}
curl -X POST "https://api.blockdb.io/v1/evm/rpc?chain_id=1" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getBlockByNumber",
    "params": ["latest", false]
  }'
```

### Example: `eth_call`

```bash theme={null}
curl -X POST "https://api.blockdb.io/v1/evm/rpc?chain_id=1" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "eth_call",
    "params": [
      {
        "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "data": "0x313ce567"
      },
      "latest"
    ]
  }'
```

## See also

* [EVM Primitives Overview](/api-reference/evm/primitives/overview)
* [Authorization](/api-reference/overview/authorization)
* [Pricing Overview](/pricing/home)


# Swaps Overview
Source: https://docs.blockdb.io/api-reference/evm/swaps/overview

Access per-swap fee accounting for pool economics, revenue attribution, and yield modeling.

## Overview

The Swaps endpoint provides per-swap fee accounting for AMM pools. Each swap record includes executed token amounts, computed fee amounts, and fee splits across recipients (LPs/users, protocol, extra destinations). This data enables revenue attribution, pool economics analysis, and feeds into yield prediction models.

### Endpoint Matrix

| Endpoint                                                     | Summary                                                | Dataset ID | Typical Latency |
| ------------------------------------------------------------ | ------------------------------------------------------ | ---------- | --------------- |
| [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) | Per-swap fee accounting (executed sizes + fee amounts) | `0303`     | \< 250 ms       |

### Parameter Conventions

<ParamField type="number">
  Starting block height (inclusive) for swap fee records.
</ParamField>

<ParamField type="number">
  Ending block height (inclusive) for swap fee records.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="string[]">
  BlockDB pool identifiers for filtering swap fees by pool.
</ParamField>

<ParamField type="string[]">
  Pool contract addresses to scope swap fee data.
</ParamField>

<ParamField type="string[]">
  Filter by input token addresses.
</ParamField>

<ParamField type="string[]">
  Filter by output token addresses.
</ParamField>

<ParamField type="string[]">
  Filter by fee token addresses.
</ParamField>

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

### Usage Guidance

* **Join with fee terms** — Link swap fees to pool fee configuration via `pool_uid` to understand fee splits
* **Time-series analysis** — Swap fees are ordered by block/time; use ranges for historical revenue analysis
* **Filter by tokens** — Use `token_in_addresses` and `token_out_addresses` to analyze specific trading pairs
* **Revenue attribution** — Fee split fields (`fee_amount_user`, `fee_amount_protocol`, `fee_amount_extra`) enable precise revenue attribution
* **Feed yield models** — Swap fee data is the primary input for yield/ROI predictions (see `/evm/yields`)

### Fee Calculation

Swap fees are computed using the pool's fee terms (from `/evm/entities/pools/fee-terms`):

* `fee_amount_total ≈ amount_in * total_fee`
* `fee_amount_user ≈ amount_in * user_fee` (when available)
* `fee_amount_protocol ≈ amount_in * protocol_fee` (when available)
* `fee_amount_extra ≈ amount_in * extra_fee` (when available)

Fee amounts are denominated in the `fee_token`, which may differ from `token_in` or `token_out` depending on the pool type.

### Common Patterns

**Calculate pool revenue over time:**

```json theme={null}
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z"
}
```

**Analyze fees for a specific trading pair:**

```json theme={null}
{
  "chain_id": 1,
  "token_in_addresses": [
    "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  ],
  "token_out_addresses": [
    "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  ],
  "from_block": 19000000
}
```

**Track protocol revenue:**

```json theme={null}
{
  "chain_id": 1,
  "pool_addresses": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-31T23:59:59Z"
}
```

### Dataset Relationships

* **Pools → Swap Fees**: Join pool metadata to swap fees using `pool_uid`
* **Fee Terms → Swap Fees**: Fee terms define the fee calculation rules applied to each swap
* **Swap Fees → Yields**: Yield predictions are derived from historical swap fees and current reserves
* **Swap Fees → Reserves**: Swap fees indicate liquidity changes that affect reserve snapshots
* **Swap Fees → Prices**: Swap execution prices are captured in the pricing layers

### See Also

* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Per-swap fee accounting endpoint
* [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms) — Pool fee configuration
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions derived from swap fees
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Pool reserve snapshots
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications


# Swap Fees
Source: https://docs.blockdb.io/api-reference/evm/swaps/swap-fees

POST https://api.blockdb.io/v1/evm/swaps/fees
Read per-swap fee accounting (executed sizes + computed fee amounts) for pool economics and yield modeling.

## Overview

* **Dataset ID:** [`0303 - Liquidity Pool Swap Fees`](/data-catalog/evm/swaps/liquidity-pools-swap-fees)
* **Description:** Per-swap fee accounting: executed swap sizes plus computed fee amounts using the pool's fee terms (`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0303_liquidity_pools_swap_fees_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0303_liquidity_pools_swap_fees_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="number[]">
  Filter swaps by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by BlockDB pool identifiers (`uid` from `/evm/entities/pools`).
</ParamField>

<ParamField type="string[]">
  Filter by pool contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by protocol-specific pool identifiers (e.g., Uniswap V4 `pool_id`).
</ParamField>

<ParamField type="number[]">
  Filter by AMM archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

#### Token Selectors (directional)

<ParamField type="string[]">
  Restrict to swaps where the input token is in this set (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Restrict to swaps where the output token is in this set (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Restrict to swaps where the fee is denominated in one of these tokens (hex string, 20 bytes, no `0x` prefix).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

#### Decimals-Adjusted Amounts

<ParamField type="boolean">
  Off by default. When set to `true`, the response includes decimals-adjusted siblings of every `*_raw` field (`amount_in`, `amount_out`, `fee_amount_total`, `fee_amount_user`, `fee_amount_protocol`, `fee_amount_extra`). Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency, so it is opt-in; when omitted or `false`, those fields are returned as `null` and only the always-present `*_raw` fields are populated.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (selectors, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of per-swap fee records matching the request. There is no separate numeric `id` field.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier (`uid` from `/evm/entities/pools`).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.token_in" type="string">
  20-byte address of the input token (direction of trade).
</ResponseField>

<ResponseField name="data.token_out" type="string">
  20-byte address of the output token for this swap direction.
</ResponseField>

<ResponseField name="data.fee_token" type="string">
  Token address the fee is denominated in (typically `token_in`).
</ResponseField>

<ResponseField name="data.amount_in_raw" type="string">
  Executed input amount as a raw integer in `token_in`'s smallest denomination. String-encoded to preserve `uint256` precision.
</ResponseField>

<ResponseField name="data.amount_in" type="string | null">
  Decimals-adjusted form of `amount_in_raw` (`amount_in_raw / 10^decimals` resolved against `token_in`). `null` when decimals are unknown or `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.amount_out_raw" type="string">
  Executed output amount as a raw integer in `token_out`'s smallest denomination.
</ResponseField>

<ResponseField name="data.amount_out" type="string | null">
  Decimals-adjusted form of `amount_out_raw` (resolved against `token_out`). `null` when decimals are unknown or `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.fee_amount_total_raw" type="string">
  Total fee amount as a raw integer in `fee_token`'s smallest denomination.
</ResponseField>

<ResponseField name="data.fee_amount_total" type="string | null">
  Decimals-adjusted form of `fee_amount_total_raw` (resolved against `fee_token`). `null` when decimals are unknown or `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.fee_amount_user_raw" type="string | null">
  User/LP share of the fee as a raw integer in `fee_token` units. `null` when the protocol does not split.
</ResponseField>

<ResponseField name="data.fee_amount_user" type="string | null">
  Decimals-adjusted form of `fee_amount_user_raw`. `null` when the raw value is `null`, when decimals are unknown, or when `include_adjusted_amounts=false`.
</ResponseField>

<ResponseField name="data.fee_amount_protocol_raw" type="string | null">
  Protocol share of the fee as a raw integer in `fee_token` units. `null` when the protocol does not split.
</ResponseField>

<ResponseField name="data.fee_amount_protocol" type="string | null">
  Decimals-adjusted form of `fee_amount_protocol_raw`. Same null semantics as the user field.
</ResponseField>

<ResponseField name="data.fee_amount_extra_raw" type="string | null">
  Extra-destination share of the fee as a raw integer in `fee_token` units. `null` when not applicable.
</ResponseField>

<ResponseField name="data.fee_amount_extra" type="string | null">
  Decimals-adjusted form of `fee_amount_extra_raw`. Same null semantics as the user field.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height where the swap event was observed.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the block containing the swap.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Zero-based log index within the transaction.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/swaps/fees" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19000100,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "token_in_addresses": [
      "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
    ],
    "token_out_addresses": [
      "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    ],
    "limit": 250
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19000100,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/swaps/fees");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);
      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":19000000,\"to_block\":19000100,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/swaps/fees", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/swaps/fees",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1,
   'from_block': 19000000,
   'to_block': 19000100,
   'pool_uids': ['88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000'],
   'token_in_addresses': ['c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'],
   'token_out_addresses': ['a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
   'limit': 250}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/swaps/fees", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19000100,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "token_in_addresses": [
      "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
    ],
    "token_out_addresses": [
      "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    ],
    "limit": 250
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 19000000,
    "to_block": 19000100,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "token_in_addresses": [
      "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
    ],
    "token_out_addresses": [
      "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    ],
    "limit": 250
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/swaps/fees", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 19000000,
        "to_block": 19000100
      },
      "resolved_window": {
        "from_block": 19000000,
        "to_block": 19000100
      },
      "filters": {
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ],
        "token_in_addresses": [
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
        ],
        "token_out_addresses": [
          "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        ],
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 19000042,
        "block_time": "2025-12-20T12:34:56Z",
        "tx_index": 15,
        "log_index": 88,
        "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "amount_in_raw": "5000000000000000000",
        "amount_in": "5",
        "amount_out_raw": "15850000000",
        "amount_out": "15850",
        "fee_amount_total_raw": "15000000000000000",
        "fee_amount_total": "0.015",
        "fee_amount_user_raw": "12000000000000000",
        "fee_amount_user": "0.012",
        "fee_amount_protocol_raw": "3000000000000000",
        "fee_amount_protocol": "0.003",
        "fee_amount_extra_raw": "0",
        "fee_amount_extra": "0",
        "_tracing_id": "0303c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0103c0ffee000000000000000000000000000000000000000000000000000001",
          "0204c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-12-20T12:35:01Z",
        "_updated_at": "2025-12-20T12:35:01Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Transfers Overview
Source: https://docs.blockdb.io/api-reference/evm/transfers/overview

Query all token transfer events — native ETH, ERC-20, ERC-721, and ERC-1155 — in a single unified endpoint.

## Overview

The Transfers suite provides access to all token transfer events produced by the TokenTransfersEngine via a single unified endpoint. Use the optional `transfer_type` filter to narrow results to a specific asset kind. The endpoint supports the same request shape (chain, block or time range, optional address filters, pagination) and returns a consistent record format with lineage fields.

### Endpoint

| Endpoint                                                                              | Summary                                                       | Transfer types                                       |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
| [`POST /evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers) | All transfer types in one response; filter by `transfer_type` | native\_tx, native\_internal, erc20, erc721, erc1155 |

### Parameter Conventions

<ParamField type="number">
  Target EVM network. See [Chain](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="number">
  Starting block number (inclusive). Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`; mutually exclusive with block range.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

<ParamField type="string">
  Filter by sender address (hex, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Filter by recipient address (hex, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Filter by token contract (hex, 20 bytes). For native endpoint, omit or leave unset.
</ParamField>

<ParamField type="number">
  Page size; max 1000. Stays under \~10 MB when combined with narrow ranges.
</ParamField>

<ParamField type="string">
  Pagination cursor from a previous response.
</ParamField>

### Usage Guidance

* **Filter by type** — Pass `transfer_type` as integer codes (`0`=native\_tx, `1`=native\_internal, `2`=erc20, `3`=erc721, `4`=erc1155) to narrow results to a specific asset kind in a single request. *See the [TransferType](/api-reference/enumerations/transfer-type) enumeration.*
* **Narrow by address** — Use `from_address` / `to_address` and optionally `token_address` to reduce payload and cost.
* **Join with entities** — Use `token_address` with [ERC-20](/api-reference/evm/entities/tokens-erc20), [ERC-721](/api-reference/evm/entities/tokens-erc721), or [ERC-1155](/api-reference/evm/entities/tokens-erc1155) token metadata for symbols and decimals.

### Common Patterns

**ERC-20 transfers for a wallet:**

```json theme={null}
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "to_address": "0000000000000000000000000000000000000001",
  "limit": 250
}
```

**NFT (ERC-721) transfers for a collection:**

```json theme={null}
{
  "chain_id": 1,
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z",
  "token_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "limit": 250
}
```

**Native ETH only (no token contract):**

```json theme={null}
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "from_address": "0000000000000000000000000000000000000000",
  "limit": 250
}
```

**All transfer types in one request:**

```json theme={null}
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "limit": 250
}
```

### Dataset & Relationships

* **Dataset ID:** `0304` — [Token transfers](/data-catalog/evm/transfers/token-transfers) (data catalog)
* **Transfers → Transactions:** Join on `(block_number, tx_index)` to [transactions](/api-reference/evm/primitives/transactions)
* **Transfers → Tokens:** Join `token_address` to [ERC-20](/api-reference/evm/entities/tokens-erc20), [ERC-721](/api-reference/evm/entities/tokens-erc721), or [ERC-1155](/api-reference/evm/entities/tokens-erc1155) for metadata

### See Also

* [Token Transfers](/api-reference/evm/transfers/token-transfers) — Full endpoint reference
* [Data catalog: Token Transfers](/data-catalog/evm/transfers/token-transfers) — Schema and columns


# Token Transfers
Source: https://docs.blockdb.io/api-reference/evm/transfers/token-transfers

POST https://api.blockdb.io/v1/evm/transfers/token-transfers
Query token transfer events (native ETH, ERC-20, ERC-721, ERC-1155) from transactions, internal transactions, and transfer logs.

## Overview

* **Dataset ID:** [`0304 - Token Transfers`](/data-catalog/evm/transfers/token-transfers)
* **Description:** Token transfer events (native ETH, ERC-20, ERC-721, ERC-1155) produced by TokenTransfersEngine from transactions, internal transactions, and transfer logs.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Transfers-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0304_token_transfers_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Transfers-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0304_token_transfers_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range or a time range.\
  Providing both results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Optional Filters

<ParamField type="string">
  Filter by sender address (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Filter by recipient address (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Filter by token contract address (hex string, 20 bytes, no `0x` prefix). Use `null` for native network token (e.g. ETH on Ethereum).
</ParamField>

<ParamField type="integer[]">
  Filter by transfer type integer code: `0`=native\_tx, `1`=native\_internal, `2`=erc20, `3`=erc721, `4`=erc1155. Omit to return all types. *See the [TransferType](/api-reference/enumerations/transfer-type) enumeration.*
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filter parameters echoed from the request (addresses, transfer\_type, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Each element mirrors the table columns (chain implied by `meta.chain_id`). Primary key in SQL is `_tracing_id`.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block where the transfer occurred.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the block (ISO-8601).
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number | null">
  Log index within the transaction receipt; null for native or internal tx transfers.
</ResponseField>

<ResponseField name="data.trace_address" type="string | null">
  Trace address for internal tx transfers (e.g. `"0"`, `"0.1"`); null for log-based transfers.
</ResponseField>

<ResponseField name="data.from_address" type="string">
  Sender address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.to_address" type="string">
  Recipient address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.token_address" type="string | null">
  Token contract address (hex string, 20 bytes); null for native ETH.
</ResponseField>

<ResponseField name="data.amount_raw" type="string">
  Raw amount in smallest unit (wei for native, raw uint256 for ERC-20/1155). String to preserve precision.
</ResponseField>

<ResponseField name="data.amount_adj" type="string | null">
  Decimal-adjusted amount; null if decimals unknown or NFT (ERC-721).
</ResponseField>

<ResponseField name="data.token_id" type="string | null">
  Token ID for ERC-721 and ERC-1155; null for native/ERC-20. String to preserve precision.
</ResponseField>

<ResponseField name="data.transfer_type" type="integer">
  Transfer type as integer enum: `0`=native\_tx, `1`=native\_internal, `2`=erc20, `3`=erc721, `4`=erc1155. *See the [TransferType](/api-reference/enumerations/transfer-type) enumeration.*
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  BlockDB lineage identifier (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  BlockDB lineage identifiers of the parent records.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp, e.g. `"2025-11-11T18:42:15.123Z"`.
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp in the same format.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/transfers/token-transfers" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "from_address": "0000000000000000000000000000000000000000",
    "to_address": "0000000000000000000000000000000000000001",
    "token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "transfer_type": [2, 3],
    "limit": 250,
    "cursor": null
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"limit\":250,\"cursor\":null}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/transfers/token-transfers");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"limit\":250,\"cursor\":null}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/transfers/token-transfers", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/transfers/token-transfers",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "from_block": 12345678,
          "to_block": 12345999,
          "from_timestamp": "2025-10-29T00:00:00Z",
          "to_timestamp": "2025-11-11T00:00:00Z",
          "transfer_type": [2, 3],
          "limit": 250,
          "cursor": None
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/transfers/token-transfers", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      from_timestamp: "2025-10-29T00:00:00Z",
      to_timestamp: "2025-11-11T00:00:00Z",
      transfer_type: ["erc20", "erc721"],
      limit: 250,
      cursor: null
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999,
    "limit": 250,
    "cursor": null
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/transfers/token-transfers", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 12345678,
        "to_block": 12345999,
        "from_timestamp": "2025-10-29T00:00:00Z",
        "to_timestamp": "2025-11-11T00:00:00Z"
      },
      "filters": {
        "transfer_type": [
          2,
          3
        ],
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "block_number": 12345680,
        "block_time": "2025-10-29T00:01:23Z",
        "tx_index": 5,
        "log_index": 2,
        "trace_address": null,
        "from_address": "0000000000000000000000000000000000000000",
        "to_address": "0000000000000000000000000000000000000001",
        "token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "amount_raw": "1000000000000000000",
        "amount_adj": "1.0",
        "token_id": null,
        "transfer_type": 2,
        "_tracing_id": "0304000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0102000000000000000000000000000000000001",
          "0201000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      },
      {
        "block_number": 12345681,
        "block_time": "2025-10-29T00:02:00Z",
        "tx_index": 12,
        "log_index": 0,
        "trace_address": null,
        "from_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "to_address": "0000000000000000000000000000000000000002",
        "token_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "amount_raw": "1",
        "amount_adj": null,
        "token_id": "1234",
        "transfer_type": 3,
        "_tracing_id": "0304000000000000000000000000000000000002",
        "_parent_tracing_ids": [
          "0102000000000000000000000000000000000001",
          "0201000000000000000000000000000000000001"
        ],
        "_created_at": "2025-11-11T18:42:15.123Z",
        "_updated_at": "2025-11-11T18:42:15.123Z"
      }
    ],
    "cursor": "next_page_cursor",
    "page_count": 2
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "body",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_block",
            "location": "body",
            "reason": "required_with",
            "expected": "provide either block range (from_block + to_block) or time range (from_timestamp + to_timestamp)"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by from_address, to_address, token_address, or transfer_type"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# TVL Overview
Source: https://docs.blockdb.io/api-reference/evm/tvl/overview

Access Total Value Locked (TVL) snapshots in USD for liquidity pools across chains.

## Overview

The TVL endpoint provides Total Value Locked snapshots in USD for liquidity pools. Each snapshot represents the pool's total value computed from reserves multiplied by fiat prices, providing a standardized USD-denominated measure of pool liquidity at each on-chain event.

### Endpoint Matrix

| Endpoint                                          | Summary                   | Dataset ID | Typical Latency |
| ------------------------------------------------- | ------------------------- | ---------- | --------------- |
| [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd) | Pool TVL snapshots in USD | `0701`     | \< 300 ms       |

### Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="number">
  Starting block height (inclusive) for TVL snapshots.
</ParamField>

<ParamField type="number">
  Ending block height (inclusive) for TVL snapshots.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="string[]">
  BlockDB pool identifiers for filtering TVL data by pool.
</ParamField>

<ParamField type="string[]">
  Pool contract addresses to scope TVL data.
</ParamField>

<ParamField type="number">
  Minimum TVL threshold in USD for filtering pools.
</ParamField>

### Usage Guidance

* **Pool ranking** — Use TVL to rank pools by liquidity depth
* **Liquidity migration** — Track TVL changes over time to identify liquidity flows
* **Protocol health** — Monitor aggregate TVL across pools for protocol-level metrics
* **Risk assessment** — Filter pools by minimum TVL for routing and execution quality
* **Dashboards** — Build TVL charts and leaderboards with full provenance

### TVL Calculation

TVL is computed as:

```
tvl_usd = sum(token_amounts[i] x fiat_price[i])
```

Where:

* `token_amounts[i]` is the decimals-adjusted reserve amount for token `i`
* `fiat_price[i]` is the USD price for token `i` at the snapshot time

### Common Patterns

**Rank pools by TVL:**

```json theme={null}
{
  "chain_id": 1,
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "min_tvl_usd": 1000000
}
```

**Get TVL history for specific pools:**

```json theme={null}
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_block": 19000000,
  "to_block": 19100000
}
```

### Dataset Relationships

* **Reserves → TVL**: Reserve snapshots provide token amounts for TVL calculation
* **Prices → TVL**: Fiat prices provide USD conversion for TVL
* **Pools → TVL**: Join pool metadata to TVL snapshots using `pool_uid`
* **TVL → Yields**: TVL can be used alongside yields for liquidity-adjusted ROI analysis

### See Also

* [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd) — TVL snapshots endpoint
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Pool reserves (input to TVL)
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield predictions
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications


# TVL USD
Source: https://docs.blockdb.io/api-reference/evm/tvl/tvl-usd

POST https://api.blockdb.io/v1/evm/tvl
Read pool Total Value Locked (TVL) snapshots in USD.

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0701 - Liquidity Pool TVL (USD)`](/data-catalog/evm/tvl/liquidity-pools-tvl-usd)
* **Description:** Pool TVL (Total Value Locked) snapshots in USD, computed from reserves multiplied by fiat prices. Grain: one row per (pool, event triple); `pool_uid` → `blockdb_evm.b0211_liquidity_pools_v1`.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-TVL-USD-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0701_liquidity_pools_tvl_usd_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-TVL-USD-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0701_liquidity_pools_tvl_usd_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="number[]">
  Filter pools by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by BlockDB pool identifiers (`uid` from `/evm/entities/pools`).
</ParamField>

<ParamField type="string[]">
  Filter by pool contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="number[]">
  Filter by AMM archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

#### TVL Filters

<ParamField type="number">
  Minimum TVL threshold in USD.
</ParamField>

<ParamField type="number">
  Maximum TVL threshold in USD.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (selectors, TVL filters, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of TVL snapshot records matching the request.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier — 32-byte `pool_uid` (`uid` from `/evm/entities/pools`).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange / DEX identifier for the pool.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier (AMM archetype).
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height of the TVL snapshot.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the TVL snapshot.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Zero-based log index within the transaction.
</ResponseField>

<ResponseField name="data.token_amounts" type="string[]">
  Array of token amounts (decimals-adjusted), aligned with pool tokens. Returned as strings to preserve precision.
</ResponseField>

<ResponseField name="data.tvl_usd" type="string">
  Total value locked in USD. Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/tvl" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "from_timestamp": "2025-12-01T00:00:00Z",
    "to_timestamp": "2025-12-20T00:00:00Z",
    "min_tvl_usd": 1000000,
    "limit": 250
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"from_timestamp\":\"2025-12-01T00:00:00Z\",\"to_timestamp\":\"2025-12-20T00:00:00Z\",\"min_tvl_usd\":1000000,\"limit\":250}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/tvl");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"from_timestamp\":\"2025-12-01T00:00:00Z\",\"to_timestamp\":\"2025-12-20T00:00:00Z\",\"min_tvl_usd\":1000000,\"limit\":250}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/tvl", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/tvl",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          'chain_id': 1,
          'pool_uids': ['88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000'],
          'from_timestamp': '2025-12-01T00:00:00Z',
          'to_timestamp': '2025-12-20T00:00:00Z',
          'min_tvl_usd': 1000000,
          'limit': 250
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/tvl", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z",
      "min_tvl_usd": 1000000,
      "limit": 250
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "from_timestamp": "2025-12-01T00:00:00Z",
    "to_timestamp": "2025-12-20T00:00:00Z",
    "min_tvl_usd": 1000000,
    "limit": 250
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/tvl", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": null,
        "to_block": null,
        "from_timestamp": "2025-12-01T00:00:00Z",
        "to_timestamp": "2025-12-20T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 21640000,
        "to_block": 21775000,
        "from_timestamp": "2025-12-01T00:00:00Z",
        "to_timestamp": "2025-12-20T00:00:00Z"
      },
      "filters": {
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ],
        "min_tvl_usd": 1000000,
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 19001234,
        "block_time": "2025-12-20T12:34:56Z",
        "tx_index": 7,
        "log_index": 12,
        "token_amounts": [
          "1250.000000000000000000",
          "3950000.000000000000000000"
        ],
        "tvl_usd": "8750000.00",
        "_tracing_id": "0701c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0301c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-12-20T12:35:01Z",
        "_updated_at": "2025-12-20T12:35:01Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or contract addresses"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Verification Overview
Source: https://docs.blockdb.io/api-reference/evm/verification/overview

Stateless utilities for recomputing Ethereum integrity artifacts.

## Overview

The verification suite provides stateless utilities for recomputing canonical Ethereum consensus artifacts. These endpoints help you validate data integrity before committing BlockDB exports (or third-party feeds) into regulated archives and downstream analytics.

### Endpoint Matrix

| Endpoint                                                                               | Purpose                                            | Inputs Expected       | Typical Latency |
| -------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------- | --------------- |
| [`POST /evm/verify/receipt-root`](/api-reference/evm/verification/verify-receipt-root) | Recompute and compare the block receipt trie root. | Full receipt set.     | \< 300 ms       |
| [`POST /evm/verify/logs-bloom`](/api-reference/evm/verification/verify-logs-bloom)     | Recompute a logs bloom filter for a set of events. | Log addresses/topics. | \< 50 ms        |

### Usage Guidance

* Use `receipt-root` for full-block reconciliations when you already possess the entire receipt set.
* Prefer `logs-bloom` for lightweight event checks to avoid recomputing entire tries.
* All endpoints accept arbitrary data providers; discrepancies in the response surface the exact hash mismatch to speed debugging.

### See Also

* [`POST /evm/verify/receipt-root`](/api-reference/evm/verification/verify-receipt-root)
* [`POST /evm/verify/logs-bloom`](/api-reference/evm/verification/verify-logs-bloom)


# Verify Logs Bloom
Source: https://docs.blockdb.io/api-reference/evm/verification/verify-logs-bloom

POST https://api.blockdb.io/v1/evm/verify/logs-bloom
Regenerate logs bloom filters for targeted reconciliations.

## Overview

Recomputes an Ethereum receipt logs bloom filter from the logs you supply and compares it against an expected bloom (for example, the value published in a block header or receipt). Useful when you only care about log-topic coverage without re-verifying the full receipt trie.

## Parameters

<ParamField type="number">
  Network identifier. Use when the verification workflow should be tied to a specific chain context. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Block Context

<ParamField type="number">
  Canonical block height where the log was emitted. Use when the verification workflow should be tied to a specific block height context.
</ParamField>

<ParamField type="string">
  2048-bit bloom filter represented as a 512-character hex string (no `0x` prefix). Typically sourced from a block header or receipt.
</ParamField>

#### Log Inputs

<ParamField type="object[]">
  Logs that should populate the bloom filter. Order is irrelevant.
</ParamField>

<ParamField type="string">
  Address that emitted the log (hex string, 20 bytes, no `0x` prefix). Encoded into the bloom.
</ParamField>

<ParamField type="string[]">
  0-4 indexed topics (hex string, 32 bytes each, no `0x` prefix). Each topic contributes to the bloom. Supply an empty array for topic-less logs.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number | null">
  EVM chain ID echoed from the request when provided; otherwise `null`.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Verification results.
</ResponseField>

<ResponseField name="data.expected_bloom" type="string">
  Bloom filter supplied in the request.
</ResponseField>

<ResponseField name="data.computed_bloom" type="string">
  Bloom filter recomputed from `logs`.
</ResponseField>

<ResponseField name="data.is_identical" type="boolean">
  `true` when `expected_bloom` and `computed_bloom` match bit-for-bit.
</ResponseField>

#### Envelope Fields

<ResponseField name="page_count" type="number">
  Number of verification entries returned (currently `1`).
</ResponseField>

## Use Cases

* Sanity-check log ingestion pipelines without fetching receipts or recomputing trie roots.
* Confirm that filtered event subscriptions captured all expected topics before downstream processing.
* Lightweight guardrail for block producers or relayers to ensure bloom accuracy after custom transformations.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/verify/logs-bloom" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "block_number": 18767124,
    "expected_bloom": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "logs": [
      {
        "contract_address": "0000000000000000000000000000000000000000",
        "topics": [
          "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0000000000000000000000000000000000000000000000000000000000000000"
        ]
      }
    ]
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"block_number\":18767124,\"expected_bloom\":\"00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\",\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0000000000000000000000000000000000000000000000000000000000000000\"]}]}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/verify/logs-bloom");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"block_number\":18767124,\"expected_bloom\":\"00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\",\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0000000000000000000000000000000000000000000000000000000000000000\"]}]}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/verify/logs-bloom", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/verify/logs-bloom",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_number': 18767124,
   'chain_id': 1,
   'expected_bloom': '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
   'logs': [{'contract_address': '0000000000000000000000000000000000000000',
             'topics': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
                        '0000000000000000000000000000000000000000000000000000000000000000']}]}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/verify/logs-bloom", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "block_number": 18767124,
    "expected_bloom": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "logs": [
      {
        "contract_address": "0000000000000000000000000000000000000000",
        "topics": [
          "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0000000000000000000000000000000000000000000000000000000000000000"
        ]
      }
    ]
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "block_number": 18767124,
    "expected_bloom": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "logs": [
      {
        "contract_address": "0000000000000000000000000000000000000000",
        "topics": [
          "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0000000000000000000000000000000000000000000000000000000000000000"
        ]
      }
    ]
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/verify/logs-bloom", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1
    },
    "data": [
      {
        "expected_bloom": "0000…",
        "computed_bloom": "0000…",
        "is_identical": true
      }
    ],
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "Invalid request parameters"
    }
  }
  ```

  ```json 401 theme={null}
  {
  "error": {
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
  }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
  "error": {
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "details": "Limit: <CONFIGURED_RPS> requests/second. Retry after: <RETRY_AFTER>"
  }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Verify Receipt Root
Source: https://docs.blockdb.io/api-reference/evm/verification/verify-receipt-root

POST https://api.blockdb.io/v1/evm/verify/receipt-root
Recompute and compare canonical receipt trie roots.

## Overview

Validates a block's receipt Merkle root by recomputing it from the receipts you provide. Use this endpoint to independently confirm that BlockDB (or any upstream source) delivered a complete, ordered receipt set.

## Parameters

<ParamField type="number">
  EVM network identifier. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Block Context

<ParamField type="number">
  Canonical block height whose receipts you want to verify.
</ParamField>

<ParamField type="string">
  Block hash (hex string, 32 bytes, no `0x` prefix). Acts as a guard to ensure you are verifying the intended block.
</ParamField>

<ParamField type="string">
  Receipt trie root reported by your data source (e.g., the block header). The endpoint recomputes the root from the supplied receipts and compares it to this value.
</ParamField>

#### Transaction Inputs

<ParamField type="object[]">
  Complete list of transaction receipts for the block (order-insensitive).
</ParamField>

<ParamField type="number">
  Zero-based transaction index within the block.
</ParamField>

<ParamField type="number">
  Post-Byzantium execution status (`1` = success, `0` = revert). Mutually exclusive with `root`.
</ParamField>

<ParamField type="string">
  Pre-Byzantium state root (hex string, 32 bytes, no `0x` prefix). Provide only for receipts before Byzantium; omit or set to `null` for modern blocks.
</ParamField>

<ParamField type="number">
  Total gas consumed in the block up to and including this transaction.
</ParamField>

<ParamField type="object[]">
  Logs emitted by the transaction.
</ParamField>

<ParamField type="string">
  Address emitting the log (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  0-4 indexed topics (hex string, 32 bytes each, no `0x` prefix) in emission order. May be empty.
</ParamField>

<ParamField type="string">
  Hex-encoded ABI payload (hex string, even length, no `0x` prefix). Use `"0x"` when empty.
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of verification results (currently one per request).
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Sequential block height.
</ResponseField>

<ResponseField name="data.block_hash" type="string">
  Keccak-256 hash of the block header (hex string, 32 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="data.parent_block_hash" type="string">
  Keccak-256 hash of the parent block.
</ResponseField>

<ResponseField name="data.receipt_root" type="string">
  Receipt trie root sourced from the request.
</ResponseField>

<ResponseField name="data.computed_receipt_root" type="string">
  Root recomputed from the supplied receipts.
</ResponseField>

<ResponseField name="data.is_identical" type="boolean">
  `true` when `computed_receipt_root` matches `receipt_root`; otherwise `false`.
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Reserved for future pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of result objects in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/verify/receipt-root" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "block_number": 18767124,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
    "transactions": [
      {
        "index": 0,
        "status": 1,
        "root": null,
        "cumulative_gas_used": 21000,
        "logs": [
          {
            "contract_address": "0000000000000000000000000000000000000000",
            "topics": [
              "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              "0000000000000000000000000000000000000000000000000000000000000000",
              "0000000000000000000000000000000000000000000000000000000000000000"
            ],
            "data": "0x"
          }
        ]
      }
    ]
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0000000000000000000000000000000000000000000000000000000000000000\",\"0000000000000000000000000000000000000000000000000000000000000000\"],\"data\":\"0x\"}]}]}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");


      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/verify/receipt-root");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);


      CURLcode res = curl_easy_perform(curl);

      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0000000000000000000000000000000000000000000000000000000000000000\",\"0000000000000000000000000000000000000000000000000000000000000000\"],\"data\":\"0x\"}]}]}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/verify/receipt-root", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/verify/receipt-root",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'block_hash': '7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0',
   'block_number': 18767124,
   'chain_id': 1,
   'receipt_root': 'b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f',
   'transactions': [{'cumulative_gas_used': 21000,
                     'index': 0,
                     'logs': [{'contract_address': '0000000000000000000000000000000000000000',
                               'data': '0x',
                               'topics': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
                                          '0000000000000000000000000000000000000000000000000000000000000000',
                                          '0000000000000000000000000000000000000000000000000000000000000000']}],
                     'root': None,
                     'status': 1}]}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/verify/receipt-root", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "block_number": 18767124,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
    "transactions": [
      {
        "index": 0,
        "status": 1,
        "root": null,
        "cumulative_gas_used": 21000,
        "logs": [
          {
            "contract_address": "0000000000000000000000000000000000000000",
            "topics": [
              "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              "0000000000000000000000000000000000000000000000000000000000000000",
              "0000000000000000000000000000000000000000000000000000000000000000"
            ],
            "data": "0x"
          }
        ]
      }
    ]
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "block_number": 18767124,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
    "transactions": [
      {
        "index": 0,
        "status": 1,
        "root": null,
        "cumulative_gas_used": 21000,
        "logs": [
          {
            "contract_address": "0000000000000000000000000000000000000000",
            "topics": [
              "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              "0000000000000000000000000000000000000000000000000000000000000000",
              "0000000000000000000000000000000000000000000000000000000000000000"
            ],
            "data": "0x"
          }
        ]
      }
    ]
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/verify/receipt-root", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1
    },
    "data": [
      {
        "block_number": 18767124,
        "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
        "parent_block_hash": "8a1e67f5d30a6a56f5afc7f9deee5ee97d6af872637dcf71aa41cc403baba2d2",
        "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
        "computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
        "is_identical": true
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Yields Overview
Source: https://docs.blockdb.io/api-reference/evm/yields/overview

Access rolling pool yield/ROI predictions across fixed horizons for pool allocation and performance analysis.

## Overview

The Yields endpoint provides rolling yield/ROI predictions per pool across fixed time horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D). Each prediction is anchored to a specific block/log position and includes aligned arrays for pool tokens, current reserves, observed/predicted volumes, user fees, and ROI fractions. Predictions are derived from historical swap fees and current reserve states.

### Endpoint Matrix

| Endpoint                                               | Summary                                          | Dataset ID | Typical Latency |
| ------------------------------------------------------ | ------------------------------------------------ | ---------- | --------------- |
| [`POST /evm/yields`](/api-reference/evm/yields/yields) | Pool yield/ROI predictions across fixed horizons | `0411`     | \< 300 ms       |

### Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField type="number">
  Target prediction horizon in days. Supported values: 1, 3, 7, 14, 30, 90, 365.
</ParamField>

<ParamField type="number">
  Starting block height (inclusive) for yield predictions.
</ParamField>

<ParamField type="number">
  Ending block height (inclusive) for yield predictions.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField type="string[]">
  BlockDB pool identifiers for filtering yield predictions by pool.
</ParamField>

<ParamField type="string[]">
  Pool contract addresses to scope yield data.
</ParamField>

<ParamField type="boolean">
  Only return predictions where `observed_period_days == target_period_days` (no extrapolation).
</ParamField>

<ParamField type="number">
  Minimum ROI threshold for filtering predictions.
</ParamField>

### Usage Guidance

* **Pool ranking** — Use yield predictions to rank pools by expected fee yield over a horizon
* **Allocation screens** — Build pool allocation signals using APR/ROI predictions with full provenance
* **Model validation** — Compare yield predictions against actual swap fees and reserves for backtesting
* **Horizon selection** — Choose `target_period_days` based on your investment horizon (short-term vs long-term)
* **Full period filtering** — Use `require_full_period: true` to exclude extrapolated predictions when historical data is insufficient

### Yield Calculation

Yield predictions are computed using:

* **Historical swap fees** (from `/evm/swaps/fees`) — Observed fee amounts over the available window
* **Current reserves** (from `/evm/reserves`) — Current pool state for ROI denominator
* **Extrapolation** — When `observed_period_days < target_period_days`, predictions are scaled by `target_period_days / observed_period_days`

ROI per token: `roi_predicted[i] = user_fees_predicted[i] / current_reserves[i]`

### Prediction Quality Indicators

Each yield record includes quality indicators:

* `observed_period_days`: Actual days of history used
* `is_full_period`: `true` when `observed_period_days == target_period_days`
* `is_extrapolated`: `true` when history is shorter than target
* `extrapolation_factor`: Scaling factor applied (target / observed)

### Common Patterns

**Rank pools by 30-day yield:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 30,
  "require_full_period": true,
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z"
}
```

**Get yield predictions for specific pools:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 7,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_block": 19000000
}
```

**Filter by minimum ROI:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 30,
  "min_roi": 0.05,
  "require_full_period": true
}
```

### Dataset Relationships

* **Swap Fees → Yields**: Historical swap fees are the primary input for yield predictions
* **Reserves → Yields**: Current reserves provide the denominator for ROI calculations
* **Pools → Yields**: Join pool metadata to yield predictions using `pool_uid`
* **Fee Terms → Yields**: Fee terms determine which fees are attributed to LPs/users
* **Yields → Prices**: Yield predictions can inform pricing models for pool tokens

### See Also

* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions endpoint
* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Historical swap fees (input to yield models)
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Current pool reserves (input to yield models)
* [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms) — Pool fee configuration
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications


# Yields
Source: https://docs.blockdb.io/api-reference/evm/yields/yields

POST https://api.blockdb.io/v1/evm/yields
Read rolling pool yield/ROI predictions across fixed horizons, derived from swap fees and current reserves.

<Warning>
  **Not publicly available:** This dataset is not included in the standard public API. Request access via a custom plan — contact [support@blockdb.io](mailto:support@blockdb.io).
</Warning>

## Overview

* **Dataset ID:** [`0411 - Liquidity Pool Yields`](/data-catalog/evm/yields/liquidity-pools-yields)
* **Description:** Rolling yield/ROI predictions per pool over fixed horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D), based on historical swap fees (blockdb\_evm.b0303\_liquidity\_pools\_swap\_fees\_v1) and current reserves (latest blockdb\_evm.b0301\_liquidity\_pools\_reserves\_v1 snapshot).
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Yields-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0411_liquidity_pools_yields_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Yields-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0411_liquidity_pools_yields_v1.json?download=true)

## Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

#### Range Filters (mutually exclusive)

<ParamField type="number">
  Starting block number (inclusive) for the query. Use with `to_block`.
</ParamField>

<ParamField type="number">
  Ending block number (inclusive) for the query. Use with `from_block`.
</ParamField>

<ParamField type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with `to_timestamp`.
</ParamField>

<ParamField type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with `from_timestamp`.
</ParamField>

<Warning>
  Validation rule:\
  You must provide **either** a block range, a time range, or at least one direct selector.\
  Providing more than one option results in HTTP 400.\
  Providing none results in HTTP 400.
</Warning>

#### Pool Selectors

<ParamField type="number[]">
  Filter pools by exchange IDs. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by BlockDB pool identifiers (`uid` from `/evm/entities/pools`).
</ParamField>

<ParamField type="string[]">
  Filter by pool contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by protocol-specific pool identifiers (e.g., Uniswap V4 `pool_id`).
</ParamField>

<ParamField type="number[]">
  Filter by AMM archetype. *See the [PoolType](/api-reference/enumerations/pool-type) enumeration for supported values.*
</ParamField>

#### Horizon & Token Filters

<ParamField type="number">
  Target horizon in days. Allowed values: `1, 3, 7, 14, 30, 90, 365`.
</ParamField>

<ParamField type="string[]">
  Restrict to pools that contain at least one of these tokens (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="boolean">
  If `true`, returns only rows where `observed_period_days == target_period_days` (no extrapolation).
</ParamField>

#### Pagination Controls

<ParamField type="number">
  Recommended default `250`; maximum `1000` to stay under \~10 MB responses.
</ParamField>

<ParamField type="string">
  Pagination cursor from a prior call.
</ParamField>

## Response Fields

#### Meta

<ResponseField name="meta" type="object">
  Echo of request metadata applied to the response.
</ResponseField>

<ResponseField name="meta.chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="meta.request_window" type="object">
  Pure echo of the window you sent (`from_block`/`to_block`/`from_timestamp`/`to_timestamp`); unset bounds are `null`.
</ResponseField>

<ResponseField name="meta.resolved_window" type="object | null">
  The concrete window the query actually executed against, after resolving the request. For a **block range** on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), `from_timestamp`/`to_timestamp` hold the resolved timestamp window (and `from_block`/`to_block` echo your request). For a **time range** on a block-keyed endpoint, `from_block`/`to_block` hold the resolved block range (and the timestamps echo your request). `null` for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
</ResponseField>

<ResponseField name="meta.resolved_window.from_block" type="number | null">
  Resolved/echoed start block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_block" type="number | null">
  Resolved/echoed end block of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.from_timestamp" type="string | null">
  Resolved/echoed start timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.resolved_window.to_timestamp" type="string | null">
  Resolved/echoed end timestamp (ISO-8601) of the executed window.
</ResponseField>

<ResponseField name="meta.filters" type="object">
  Filters echoed from the request (selectors, horizon filters, pagination state, etc.).
</ResponseField>

#### Data

<ResponseField name="data" type="object[]">
  Array of yield/ROI prediction records matching the request. Rows are keyed by `(pool_uid, target_period_days, block_number, tx_index, log_index)`; there is no separate numeric `id` field.
</ResponseField>

<ResponseField name="data.pool_uid" type="string">
  BlockDB pool identifier (`uid` from `/evm/entities/pools`).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="data.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="data.block_number" type="number">
  Block height of the as-of snapshot anchor.
</ResponseField>

<ResponseField name="data.block_time" type="string">
  UTC timestamp of the as-of snapshot anchor.
</ResponseField>

<ResponseField name="data.tx_index" type="number">
  Zero-based transaction index within the block.
</ResponseField>

<ResponseField name="data.log_index" type="number">
  Zero-based log index within the transaction.
</ResponseField>

<ResponseField name="data.target_period_days" type="number">
  Target horizon in days (1, 3, 7, 14, 30, 90, 365).
</ResponseField>

<ResponseField name="data.observed_period_days" type="number">
  Observed history actually used to produce the prediction.
</ResponseField>

<ResponseField name="data.is_full_period" type="boolean">
  `true` when `observed_period_days == target_period_days`.
</ResponseField>

<ResponseField name="data.is_extrapolated" type="boolean">
  `true` when the row is scaled from shorter history.
</ResponseField>

<ResponseField name="data.extrapolation_factor" type="string">
  Scaling factor applied when extrapolating. Returned as a string to preserve precision.
</ResponseField>

<ResponseField name="data.window_start_time" type="string">
  Start time of the observed window used for aggregation.
</ResponseField>

<ResponseField name="data.window_end_time" type="string">
  End time of the observed window used for aggregation.
</ResponseField>

<ResponseField name="data.tokens" type="string[]">
  Pool token addresses. All array-valued metrics are aligned to this order.
</ResponseField>

<ResponseField name="data.current_reserves" type="string[]">
  Current reserves per token (decimals-adjusted). Returned as strings to preserve precision.
</ResponseField>

<ResponseField name="data.volume_observed" type="string[]">
  Observed traded volume per token in the observed window.
</ResponseField>

<ResponseField name="data.volume_predicted" type="string[]">
  Predicted traded volume per token for the target horizon.
</ResponseField>

<ResponseField name="data.user_fees_observed" type="string[]">
  Observed user/LP fee amounts per token in the observed window.
</ResponseField>

<ResponseField name="data.user_fees_predicted" type="string[]">
  Predicted user/LP fee amounts per token for the target horizon.
</ResponseField>

<ResponseField name="data.roi_predicted" type="string[]">
  Predicted ROI fractions per token for the target horizon.
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  Row-level lineage hash (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  Lineage references of immediate parents.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

#### Envelope Fields

<ResponseField name="cursor" type="string | null">
  Cursor token for pagination.
</ResponseField>

<ResponseField name="page_count" type="number">
  Number of records returned in `data`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/yields" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "target_period_days": 30,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "from_timestamp": "2025-12-01T00:00:00Z",
    "to_timestamp": "2025-12-20T00:00:00Z",
    "require_full_period": true,
    "limit": 250
  }'
  ```

  ```c C theme={null}
  #include <curl/curl.h>
  #include <stdio.h>
  #include <stdlib.h>

  int main(void) {
      CURL *curl = curl_easy_init();
      if (!curl) return 1;

      const char *token = getenv("BLOCKDB_API_KEY");
      char auth_header[256];
      snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
      const char *payload = "{\"chain_id\":1,\"target_period_days\":30,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"from_timestamp\":\"2025-12-01T00:00:00Z\",\"to_timestamp\":\"2025-12-20T00:00:00Z\",\"require_full_period\":true,\"limit\":250}";

      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, auth_header);
      headers = curl_slist_append(headers, "Content-Type: application/json");

      curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/yields");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);

      CURLcode res = curl_easy_perform(curl);
      curl_slist_free_all(headers);
      curl_easy_cleanup(curl);
      return res == CURLE_OK ? 0 : 1;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"target_period_days\":30,\"pool_uids\":[\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"],\"from_timestamp\":\"2025-12-01T00:00:00Z\",\"to_timestamp\":\"2025-12-20T00:00:00Z\",\"require_full_period\":true,\"limit\":250}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync("https://api.blockdb.io/v1/evm/yields", payload);
          response.EnsureSuccessStatusCode();

          var body = await response.Content.ReadAsStringAsync();
          Console.WriteLine(body);
      }
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/yields",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={'chain_id': 1,
   'target_period_days': 30,
   'pool_uids': ['88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000'],
   'from_timestamp': '2025-12-01T00:00:00Z',
   'to_timestamp': '2025-12-20T00:00:00Z',
   'require_full_period': True,
   'limit': 250}
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/yields", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
    "chain_id": 1,
    "target_period_days": 30,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "from_timestamp": "2025-12-01T00:00:00Z",
    "to_timestamp": "2025-12-20T00:00:00Z",
    "require_full_period": true,
    "limit": 250
  })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "os"
      "strings"
  )

  func main() {
      payload := strings.NewReader(`{
    "chain_id": 1,
    "target_period_days": 30,
    "pool_uids": [
      "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
    ],
    "from_timestamp": "2025-12-01T00:00:00Z",
    "to_timestamp": "2025-12-20T00:00:00Z",
    "require_full_period": true,
    "limit": 250
  }`)

      req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/yields", payload)
      req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      // Handle response
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_timestamp": "2025-12-01T00:00:00Z",
        "to_timestamp": "2025-12-20T00:00:00Z"
      },
      "resolved_window": {
        "from_block": 21640000,
        "to_block": 21775000,
        "from_timestamp": "2025-12-01T00:00:00Z",
        "to_timestamp": "2025-12-20T00:00:00Z"
      },
      "filters": {
        "pool_uids": [
          "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
        ],
        "target_period_days": 30,
        "require_full_period": true,
        "limit": 250,
        "cursor": null
      }
    },
    "data": [
      {
        "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "exchange_id": 1,
        "type_id": 201,
        "block_number": 19001234,
        "block_time": "2025-12-20T12:34:56Z",
        "tx_index": 7,
        "log_index": 12,
        "target_period_days": 30,
        "observed_period_days": 30,
        "is_full_period": true,
        "is_extrapolated": false,
        "extrapolation_factor": "1.000000",
        "window_start_time": "2025-11-20T12:34:56Z",
        "window_end_time": "2025-12-20T12:34:56Z",
        "tokens": [
          "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        ],
        "current_reserves": [
          "1250.000000000000000000",
          "3950000.000000000000000000"
        ],
        "volume_observed": [
          "12000.000000000000000000",
          "0.000000000000000000"
        ],
        "volume_predicted": [
          "12000.000000000000000000",
          "0.000000000000000000"
        ],
        "user_fees_observed": [
          "36.000000000000000000",
          "0.000000000000000000"
        ],
        "user_fees_predicted": [
          "36.000000000000000000",
          "0.000000000000000000"
        ],
        "roi_predicted": [
          "0.028800000000000000",
          "0.000000000000000000"
        ],
        "_tracing_id": "0411c0ffee000000000000000000000000000000000000000000000000000001",
        "_parent_tracing_ids": [
          "0303c0ffee000000000000000000000000000000000000000000000000000001",
          "0301c0ffee000000000000000000000000000000000000000000000000000001"
        ],
        "_created_at": "2025-12-20T12:35:01Z",
        "_updated_at": "2025-12-20T12:35:01Z"
      }
    ],
    "cursor": null,
    "page_count": 1
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000, # configured rate limit
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Authorization
Source: https://docs.blockdb.io/api-reference/overview/authorization

API keys, the BlockDB dashboard, and how to send credentials on every request.

## Overview

BlockDB authenticates **REST** and **WebSocket** traffic with **API keys**. Send your key in the `Authorization` header on every request that requires authentication. Keys are tied to your subscription: which datasets and chains you can query, your [compute unit](/api-reference/overview/compute-units) allowance, and your [rate limit](/api-reference/overview/rate-limiting). See the [dataset index](/data-catalog/evm/dataset-index) and [Dataset ID](/api-reference/enumerations/dataset-id) for how products map to `blockdb_evm` tables.

<Info>
  There is **no separate token endpoint** and **no OAuth flow**. The string you copy from the dashboard is the credential you pass as `Bearer <key>`.
</Info>

## Get an account and API keys

<Steps>
  <Step title="Open an account">
    Sign up at [accounts.blockdb.io](https://accounts.blockdb.io/sign-up) if you do not already have a BlockDB account.
  </Step>

  <Step title="Create and manage keys in the dashboard">
    Open **[dashboard.blockdb.io](https://dashboard.blockdb.io)**. There you can:

    * **Create** new API keys (up to **5 active keys** per account)
    * **Label** keys (for example production vs staging)
    * **Rotate** a key when you need a new secret while phasing out an old one
    * **Revoke** a key that is compromised or no longer needed

    Store keys only in environment variables or a secret manager—never commit them to source control.
  </Step>

  <Step title="Send the key on each request">
    Use the HTTP `Authorization` header with the `Bearer` scheme:

    ```
    Authorization: Bearer <your_api_key>
    ```
  </Step>
</Steps>

## Code examples: call the API with an API key

Set **`BLOCKDB_API_KEY`** in your environment (or substitute the value from the dashboard). These examples use the historic REST base URL **`https://api.blockdb.io/v1`**.

<CodeGroup>
  ```bash cURL theme={null}
  # Usage (no body)
  curl -sS "https://api.blockdb.io/v1/usage" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY"

  # Example data request
  curl -sS -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}'
  ```

  ```python Python theme={null}
  import os
  import requests

  API_BASE = "https://api.blockdb.io/v1"
  KEY = os.environ["BLOCKDB_API_KEY"]

  h = {"Authorization": f"Bearer {KEY}"}

  r = requests.get(f"{API_BASE}/usage", headers=h, timeout=30)
  r.raise_for_status()
  print(r.json())

  r2 = requests.post(
      f"{API_BASE}/evm/raw/blocks",
      headers={**h, "Content-Type": "application/json"},
      json={"chain_id": 1, "from_block": 12345678, "to_block": 12345999, "limit": 10},
      timeout=30,
  )
  r2.raise_for_status()
  print(r2.json())
  ```

  ```javascript Node.js theme={null}
  const API_BASE = "https://api.blockdb.io/v1";
  const key = process.env.BLOCKDB_API_KEY;
  if (!key) throw new Error("Set BLOCKDB_API_KEY");

  const headers = { Authorization: `Bearer ${key}` };

  const usage = await fetch(`${API_BASE}/usage`, { headers });
  console.log(await usage.json());

  const blocks = await fetch(`${API_BASE}/evm/raw/blocks`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      limit: 10,
    }),
  });
  console.log(await blocks.json());
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;

  var key = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")
      ?? throw new InvalidOperationException("Set BLOCKDB_API_KEY");

  using var http = new HttpClient { BaseAddress = new Uri("https://api.blockdb.io/v1/") };
  http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);

  var usage = await http.GetAsync("usage");
  usage.EnsureSuccessStatusCode();
  Console.WriteLine(await usage.Content.ReadAsStringAsync());

  var body = new StringContent(
      """{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}""",
      Encoding.UTF8,
      "application/json");
  var blocks = await http.PostAsync("evm/raw/blocks", body);
  blocks.EnsureSuccessStatusCode();
  Console.WriteLine(await blocks.Content.ReadAsStringAsync());
  ```
</CodeGroup>

### Official SDKs

The [.NET](/api-reference/sdks/dotnet), [Python](/api-reference/sdks/python), and [JavaScript](/api-reference/sdks/javascript) SDKs accept your API key and attach `Authorization: Bearer` for you. See each SDK page for the exact constructor and configuration options.

## Security practices

* **Rotation:** Create a new key in the dashboard, deploy it, then revoke the old key.
* **Least privilege:** Use separate keys for production and non-production when possible (within the five-key limit).
* **Incidents:** Revoke a key immediately if it leaks; create a replacement in the dashboard.

## See Also

* [Usage & Limits](/api-reference/account-and-usage/usage) — `plan`, `cu_*`, and `rate_limit_rps` for your key
* [Rate Limiting](/api-reference/overview/rate-limiting) — RPS, backoff, and `429` handling
* [Error Codes](/api-reference/overview/error-codes) — Full error reference
* [Troubleshooting: API Authentication Failures](/troubleshooting/runbooks/api-authentication-failures) — 401/403 runbook

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.blockdb.io/v1/evm/raw/blocks' \
    -H 'Authorization: Bearer <BLOCKDB_API_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "chain_id": 1,
      "from_block": 12345678,
      "to_block": 12345999
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999
      },
      "filters": {
        "limit": 10,
        "cursor": null
      }
    },
    "data": [],
    "cursor": null,
    "page_count": 0
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>


# Compute Units
Source: https://docs.blockdb.io/api-reference/overview/compute-units

API pricing based on Compute Units (CU): pay only for what you use, proportional to computational complexity.

## Compute Unit (CU) Pricing Model

BlockDB uses a **Compute Unit (CU)** pricing model that charges based on the computational complexity of each API endpoint. This ensures you only pay for what you use, without being forced into expensive plans for simple queries.

### How Compute Units Work

Each API request consumes a fixed number of Compute Units determined by the **data layer** — **not by result size or pagination depth**.

Your **monthly CU allowance** (`cu_limit`, `cu_used`, `cu_remaining` on [`GET /usage`](/api-reference/account-and-usage/usage)) is **account-wide** and **shared by every API key**—adding keys does not create separate CU pools. The same applies to **RPS**; see [Rate limiting](/api-reference/overview/rate-limiting).

|  Level | CU / request | Endpoint Family                                                        | Endpoint                                                                                               |
| :----: | :----------: | :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
| **L1** |   **1 CU**   | Raw history, blocks summary, lineage (parents), verification, JSON-RPC | [`evm/raw/blocks`](/api-reference/evm/primitives/blocks)                                               |
|        |              |                                                                        | [`evm/raw/blocks-summary`](/api-reference/evm/primitives/blocks-summary)                               |
|        |              |                                                                        | [`evm/raw/transactions`](/api-reference/evm/primitives/transactions)                                   |
|        |              |                                                                        | [`evm/raw/logs`](/api-reference/evm/primitives/logs)                                                   |
|        |              |                                                                        | [`evm/raw/contracts`](/api-reference/evm/primitives/contracts)                                         |
|        |              |                                                                        | [`evm/raw/function-results`](/api-reference/evm/primitives/function-results)                           |
|        |              |                                                                        | [`evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions)                 |
|        |              |                                                                        | [`evm/lineage/parents`](/api-reference/evm/lineage/parents)                                            |
|        |              |                                                                        | [`evm/verify/receipt-root`](/api-reference/evm/verification/verify-receipt-root)                       |
|        |              |                                                                        | [`evm/verify/logs-bloom`](/api-reference/evm/verification/verify-logs-bloom)                           |
|        |              |                                                                        | [`evm/rpc`](/api-reference/evm/rpc/overview)                                                           |
| **L2** |   **40 CU**  | Entities, lineage (record)                                             | [`evm/lineage/record`](/api-reference/evm/lineage/record)                                              |
|        |              |                                                                        | [`evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20)                                |
|        |              |                                                                        | [`evm/entities/tokens/erc721`](/api-reference/evm/entities/tokens-erc721)                              |
|        |              |                                                                        | [`evm/entities/tokens/erc1155`](/api-reference/evm/entities/tokens-erc1155)                            |
|        |              |                                                                        | [`evm/entities/pools`](/api-reference/evm/entities/pools)                                              |
|        |              |                                                                        | [`evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms)                                |
| **L3** |   **80 CU**  | Reserves, transfers, swaps, prints, flash loans                        | [`evm/reserves`](/api-reference/evm/reserves/reserves)                                                 |
|        |              |                                                                        | [`evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution)            |
|        |              |                                                                        | [`evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers)                        |
|        |              |                                                                        | [`evm/swaps/fees`](/api-reference/evm/swaps/swap-fees)                                                 |
|        |              |                                                                        | [`evm/prices/spot/crypto/prints`](/api-reference/evm/prices/crypto/prices-spot-prints)                 |
|        |              |                                                                        | [`evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints)                           |
| **L4** |   **80 CU**  | Per-pool OHLC/VWAP                                                     | [`evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap)                     |
|        |              |                                                                        | [`evm/prices/spot/crypto/ohlc`](/api-reference/evm/prices/crypto/prices-spot-ohlc)                     |
|        |              |                                                                        | [`evm/yields`](/api-reference/evm/yields/yields)                                                       |
| **L5** |   **80 CU**  | Cross-pool VWAP                                                        | [`evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) |
| **L6** |  **100 CU**  | Token-to-fiat VWAP                                                     | [`evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat)                    |
| **L7** |  **200 CU**  | Pool TVL USD                                                           | [`evm/tvl`](/api-reference/evm/tvl/tvl-usd)                                                            |
| **L8** |  **300 CU**  | Arbitrage path topology & path status                                  | [`evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                                              |
|        |              |                                                                        | [`evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)                                  |
| **L9** |  **1000 CU** | Arbitrage opportunities                                                | [`evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities)                              |

<Note>
  CU consumption is calculated per request. Result size and pagination do not affect CU cost — only the endpoint level determines the CU value.
</Note>

## CU Billing & Tracking

### How CU Consumption is Tracked

Query the [`GET /usage`](/api-reference/account-and-usage/usage) endpoint to retrieve your plan, `cu_used`, `cu_remaining`, `cu_limit`, `cu_reset_at`, and `rate_limit_rps`. This endpoint is free to use and does not consume compute units.

<Note>
  The `/usage` endpoint provides comprehensive usage data including consumption by dataset, billing period information, and rate limits.
</Note>

### Overage Handling

When you exceed your monthly CU allowance:

* **Hard limits**: API requests are blocked once your CU allowance is exhausted
* **Additional packages**: Purchase additional CU packages to continue using the API
* **No automatic overage charges**: You control when to purchase additional CUs—no unexpected charges
* **Package options**: Additional CU packages are available in various sizes to match your needs

<Warning>
  Once your CU allowance is exhausted, API requests will return `429 Too Many Requests` until you purchase an additional CU package. Plan your usage accordingly to avoid service interruptions.
</Warning>

## Pricing Examples

### Example 1: Raw block query (L1)

```
POST /evm/raw/blocks
CU cost: 1 CU
```

### Example 2: ERC-20 token lookup (L2)

```
POST /evm/entities/tokens/erc20
CU cost: 40 CU
```

### Example 3: Fiat VWAP price (L5, dataset `0605`, `b0605_token_to_fiat_vwap`)

```
POST /evm/prices/spot/fiat/vwap
CU cost: 100 CU
```

### Example 4: Multi-step analysis workflow

```
POST /evm/raw/blocks              (find block range)  →    1 CU  [L1]
POST /evm/raw/logs                (filter events)     →    1 CU  [L1]
POST /evm/reserves       (pool snapshot)     →   80 CU  [L3]
POST /evm/prices/spot/crypto/ohlc (crypto OHLC)       →   80 CU  [L4]
POST /evm/prices/spot/fiat/vwap   (fiat benchmark)    →  100 CU  [L5]
POST /evm/tvl                     (pool TVL USD)      →  200 CU  [L6]
POST /evm/arb/opportunities       (arb opportunities) →  1000 CU  [L8]
                                                Total: 1462 CU
```

## See Also

* [Dataset index](/data-catalog/evm/dataset-index) — Dataset IDs and `blockdb_evm` table names
* [Pricing Plans](/pricing/home) - Compare API, WSS, and Bulk Delivery options
* [Usage Endpoint](/api-reference/account-and-usage/usage) - Track your CU consumption
* [Contact Support](/troubleshooting/raising-a-support-ticket) - Billing and account questions


# Error Codes
Source: https://docs.blockdb.io/api-reference/overview/error-codes

Complete reference of API error codes, meanings, and resolution strategies.

## Overview

BlockDB API uses structured error envelopes with consistent codes, HTTP status, retry guidance, and links back to the docs. Use `hint`, `severity`, and `retryable` to decide whether to fix the request or retry later.

## Error Response Format

All error responses follow this structure (fields may vary by code):

<CodeGroup>
  ```json Error theme={null}
  {
    "error": {
      "code": "ERROR_CODE",
      "http_status": 400,
      "message": "Human-readable error message.",
      "hint": "Actionable guidance.",
      "severity": "error | warning | critical",
      "retryable": false,
      "details": {},
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</CodeGroup>

## Common Error Codes

### Authentication & Authorization

| Code                    | HTTP Status | Description                                | Resolution                                                                                     |
| ----------------------- | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `BAD_REQUEST`           | 400         | Invalid or missing parameters              | Fix fields listed in `details.invalid_parameters`; use ISO-8601 timestamps and valid chain IDs |
| `UNAUTHORIZED`          | 401         | Invalid or missing API key                 | Send `Authorization: Bearer <API_KEY>`; regenerate key if compromised                          |
| `FORBIDDEN`             | 403         | API key lacks permission for this endpoint | Upgrade plan or request access (`required_plan` in `details`)                                  |
| `NOT_FOUND`             | 404         | Resource does not exist                    | Verify endpoint path and parameters                                                            |
| `PAYLOAD_TOO_LARGE`     | 413         | Response would exceed size limits          | Lower `limit`, narrow block/time window, or reduce filters                                     |
| `RATE_LIMIT_EXCEEDED`   | 429         | Request rate exceeded                      | Apply client throttling/backoff and honor `retry_after_seconds`                                |
| `INTERNAL_SERVER_ERROR` | 500         | Unexpected server error                    | Safe to retry; include `incident_id` in support tickets                                        |

## Error Code Reference by Category

<AccordionGroup>
  <Accordion title="Authentication & Authorization">
    * `UNAUTHORIZED` (401)
    * `FORBIDDEN` (403)
  </Accordion>

  <Accordion title="Request Validation">
    * `BAD_REQUEST` (400)
    * `NOT_FOUND` (404)
  </Accordion>

  <Accordion title="Quota & Payload">
    * `RATE_LIMIT_EXCEEDED` (429)
    * `PAYLOAD_TOO_LARGE` (413)
  </Accordion>

  <Accordion title="Server Errors">
    * `INTERNAL_SERVER_ERROR` (500)
  </Accordion>
</AccordionGroup>

## See Also

* [Dataset index](/data-catalog/evm/dataset-index) — Dataset-scoped access and table names
* [Troubleshooting: API Error Codes](/troubleshooting/error-codes/api/home) - Detailed troubleshooting guide
* [Authorization](/api-reference/overview/authorization) - Authentication errors
* [Rate Limiting](/api-reference/overview/rate-limiting) - Rate limit handling
* [Raising a Support Ticket](/troubleshooting/raising-a-support-ticket) - Get help with errors


# Introduction
Source: https://docs.blockdb.io/api-reference/overview/home

Overview of the BlockDB Historic REST API — authentication, pagination, compute units, and onboarding for EVM blockchain data.

## Video walkthrough

**BlockDB Free Account, API Key & First Query in 2 Minutes** — sign up, create a key, and run your first query:

<iframe title="BlockDB Free Account, API Key & First Query in 2 Minutes" />

For written steps, see the [Quick Start Guide](/user-guide/about-blockdb/quick-start-guide).

**Version:** `v1`\
**Last Updated:** `2026-05-12`

## Base URL

```http theme={null}
https://api.blockdb.io/v1
```

Use HTTPS for every request. Data endpoints are `POST` with a JSON body and typically return an envelope with `data`, `cursor`, and `count` for pagination. Account endpoints such as [`GET /usage`](/api-reference/account-and-usage/usage) and [`GET /health`](/api-reference/account-and-usage/health) use `GET` with no body.

## Authentication

Authentication uses **API keys** from **[dashboard.blockdb.io](https://dashboard.blockdb.io)** (up to **five** active keys per account). Send the key on every request as `Authorization: Bearer <API_KEY>`. Entitlements (datasets and chains) are tied to your account; **monthly compute units and RPS are account-wide and shared across all keys**—you cannot assign separate usage or rate limits to individual keys. Requests without a valid key return `401`. See [Authorization](/api-reference/overview/authorization) and [Rate limiting](/api-reference/overview/rate-limiting).

<Callout icon="lightbulb">
  The API never accepts query parameters for filters. Always place filters in the JSON body (for example, `chain_id`, block ranges, or address lists).
</Callout>

## Endpoint families

<CardGroup>
  <Card title="Ledger & execution" icon="square-binary" href="/api-reference/evm/primitives/blocks">
    Blocks, transactions, logs, internal traces, contracts, and function results.
  </Card>

  <Card title="Tokens & liquidity" icon="hexagon-vertical-nft" href="/api-reference/evm/entities/tokens-erc20">
    ERC-20/721/1155 registries, pools, fee terms, reserves, transfers, and swap fees.
  </Card>

  <Card title="Pricing & TVL" icon="chart-line" href="/api-reference/evm/prices/overview">
    Swap prints, OHLC, per-pool and cross-pool VWAP, token-to-USD VWAP, yields, and TVL.
  </Card>

  <Card title="Flash loans & arbitrage" icon="bolt" href="/api-reference/evm/flash-loans/overview">
    Flash loan prints, arb paths, path status, and opportunities.
  </Card>
</CardGroup>

## Lineage, verification, and JSON-RPC

* **[Lineage](/api-reference/evm/lineage/overview)** — Resolve records, genesis artifacts, and parent graphs from `_tracing_id`.
* **[Verification](/api-reference/evm/verification/overview)** — Recompute receipt trie roots and log blooms for integrity checks.
* **[JSON-RPC](/api-reference/evm/rpc/overview)** — Proxied Ethereum JSON-RPC methods with `chain_id` routing.

## Enumerations & shared metadata

* [Dataset index](/data-catalog/evm/dataset-index) — All EVM dataset IDs, `blockdb_evm` table names, and catalog links
* [Chain](/api-reference/enumerations/chain)
* [Digital Exchange](/api-reference/enumerations/digital-exchange)
* [Dataset ID](/api-reference/enumerations/dataset-id)
* [Pool Type](/api-reference/enumerations/pool-type)
* [Asset Class](/api-reference/enumerations/asset-class)
* [Fiat Currency](/api-reference/enumerations/fiat-currency)
* [Market Kind](/api-reference/enumerations/market-kind)

## Contact & support

[support@blockdb.io](mailto:support@blockdb.io)


# LLM Onboarding
Source: https://docs.blockdb.io/api-reference/overview/llm-onboarding

LLM-friendly instructions for querying BlockDB REST endpoints safely (auth, pagination, limits, and deterministic filters).

## 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.

<CodeGroup>
  ```markdown theme={null}
  # BlockDB API — LLM instructions

  You are helping users call the BlockDB REST API. Follow these rules so requests succeed and responses are correct.

  ---

  ## 1. Hard rules (avoid most mistakes)

  | Rule | Value |
  |------|--------|
  | **Base URL** | `https://api.blockdb.io/v1` |
  | **Auth** | Every request: `Authorization: Bearer <API_KEY>` (keys from [dashboard.blockdb.io](https://dashboard.blockdb.io)) |
  | **Method** | Almost all: `POST` with JSON body. Exception: `GET /usage` for usage stats. |
  | **Body** | `Content-Type: application/json`. All filters go in the **body** — do not use query parameters for filters. |
  | **Response shape** | Envelope: `{ "data": [...], "cursor": "<string or null>", "page_count": <number> }`. Use `cursor` for the next page. |
  | **Determinism** | Prefer `from_block` / `to_block` for reproducible results; time ranges are supported but mapped to blocks server-side. |

  ---

  ## 2. Choosing the right endpoint

  - **Index of all endpoints**: `/api-reference/evm/overview` — use this when unsure.
  - **Dataset → table → CU cost**: [Dataset index](/data-catalog/evm/dataset-index) maps dataset IDs to `blockdb_evm` tables; [Compute units](/api-reference/overview/compute-units) maps each endpoint family to CU tiers (L1–L8).
  - **IDs (chain, exchange, pool type, dataset)**: Use **Enumerations** (`/api-reference/enumerations/overview`) — do not guess numeric IDs.
  - **By use case**:
    - Raw chain data (blocks, txs, logs, contracts) → **Primitives** (`/api-reference/evm/primitives/overview`).
    - Pools, tokens, fee terms → **Entities** (`/api-reference/evm/entities/overview`).
    - Reserves, swaps, yields, TVL → **Reserves / Swaps / Yields / TVL** under EVM.
    - Prices (crypto or fiat) → **Prices** (`/api-reference/evm/prices/overview`).
    - Provenance / audit → use `_tracing_id` / `_parent_tracing_ids` columns and [Dataset ID](/api-reference/enumerations/dataset-id); see [Data verification](/data-catalog/overview/data-verification).

  ---

  ## 3. Request template

  Typical EVM POST body (endpoint-specific fields may add or replace):

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

  - **Required**: `chain_id` (see enumerations for valid values).
  - **Range**: `from_block` / `to_block` **or** `from_timestamp` / `to_timestamp` (often mutually exclusive; check per-endpoint docs).
  - **Selectors**: e.g. `pool_uids`, `pool_addresses`, `exchange_ids`, `pool_type_ids`, token addresses — only include what the endpoint supports.
  - **Pagination**: `limit` (default 250, max typically 1000) and `cursor` (omit or null on first request).

  ---

  ## 4. Pagination

  - If the response has `cursor` non-null: send the **same** endpoint again with that `cursor` in the body to get the next page.
  - Stop when `cursor` is null or `page_count` is 0.
  - Prefer smaller time/block windows and multiple pages over very large `limit` values (keeps responses under ~10 MB).

  ---

  ## 5. Errors and retries

  - **Error format**: JSON body with `error`: `code`, `message`, `hint`, `retryable`. Use `hint` to fix the request.
  - **401** (UNAUTHORIZED): Invalid or missing API key → fix `Authorization: Bearer <API_KEY>`.
  - **403** (FORBIDDEN): Key lacks permission → check plan and entitlements.
  - **429** (RATE_LIMIT_EXCEEDED): Honor `Retry-After` (header or in body); use exponential backoff; cap max retries (e.g. 5).
  - **5xx**: If `retryable` is true (or not set), retry with backoff; otherwise treat as non-retryable.

  ---

  ## 6. Lineage and verification (auditability)

  - Use `_tracing_id` on returned rows to reference a specific record.
  - **Lineage** API: trace how a row was derived (record, genesis, parents).
  - **Verification** API: recompute receipt roots or logs bloom filters for proofs.

  ---

  ## 7. When in doubt — read the docs

  **Always prefer the official documentation over inference.** If you are unsure about an endpoint, parameter, enumeration value, schema field, or behaviour — fetch the relevant page from `https://docs.blockdb.io` before generating a request.

  Useful starting points:

  | Need | URL |
  |------|-----|
  | Full endpoint index | `https://docs.blockdb.io/api-reference/evm/overview` |
  | Dataset index (IDs and SQL table names) | `https://docs.blockdb.io/data-catalog/evm/dataset-index` |
  | Enumerations (chain IDs, exchange IDs, pool types) | `https://docs.blockdb.io/api-reference/enumerations/overview` |
  | Pagination rules and default limits | `https://docs.blockdb.io/api-reference/overview/pagination-and-limits` |
  | Auth and API key scopes | `https://docs.blockdb.io/api-reference/overview/authorization` |
  | Rate limits and retry guidance | `https://docs.blockdb.io/api-reference/overview/rate-limiting` |
  | CU costs per endpoint | `https://docs.blockdb.io/api-reference/overview/compute-units` |
  | Error codes and hints | `https://docs.blockdb.io/api-reference/overview/error-codes` |
  | Specific endpoint (example) | `https://docs.blockdb.io/api-reference/evm/primitives/blocks` |

  Treat `https://docs.blockdb.io` as the authoritative source. If a page gives you new information that contradicts your prior assumptions, use the page.

  ---

  ## 8. Good LLM behavior

  - **Ask** for missing inputs: chain, token addresses, pool identifiers, time or block range.
  - **Resolve** IDs from Enumerations or docs — never invent chain_id, exchange_id, pool_type_id, or pool UIDs.
  - **Never fabricate** addresses, pool UIDs, or token contract addresses.
  - **When unsure** which endpoint to use, fetch `https://docs.blockdb.io/api-reference/evm/overview` and match the user's goal to the table.
  - **Before generating a request**: confirm you have a valid base URL, auth header, POST + JSON body, and at least `chain_id` (and range or selectors as required by the endpoint).
  - **If a parameter or field is unfamiliar**: fetch the endpoint's doc page on `https://docs.blockdb.io` and read the parameter definitions before proceeding.
  ```
</CodeGroup>


# Pagination & Limits
Source: https://docs.blockdb.io/api-reference/overview/pagination-and-limits

Recommended pagination defaults to keep responses under ~10 MB.

### Overview

Paginated endpoints support `limit` (default `250`, max `1000`) and `cursor` in the JSON body.

| Endpoint                                                                                                        | Default limit | Max limit | Approx. item size (bytes) |
| --------------------------------------------------------------------------------------------------------------- | ------------- | --------- | ------------------------- |
| **Primitives**                                                                                                  |               |           |                           |
| [`POST /v1/evm/raw/blocks`](/api-reference/evm/primitives/blocks)                                               | 250           | 1000      | \~800                     |
| [`POST /v1/evm/raw/transactions`](/api-reference/evm/primitives/transactions)                                   | 250           | 1000      | \~600                     |
| [`POST /v1/evm/raw/logs`](/api-reference/evm/primitives/logs)                                                   | 250           | 1000      | \~800                     |
| [`POST /v1/evm/raw/internal-transactions`](/api-reference/evm/primitives/internal-transactions)                 | 250           | 1000      | \~500                     |
| [`POST /v1/evm/raw/contracts`](/api-reference/evm/primitives/contracts)                                         | 250           | 1000      | \~400                     |
| [`POST /v1/evm/raw/function-results`](/api-reference/evm/primitives/function-results)                           | 250           | 1000      | \~600                     |
| **Transfers**                                                                                                   |               |           |                           |
| [`POST /v1/evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers)                        | 250           | 1000      | \~400                     |
| **Entities**                                                                                                    |               |           |                           |
| [`POST /v1/evm/entities/tokens/erc20`](/api-reference/evm/entities/tokens-erc20)                                | 250           | 1000      | \~600                     |
| [`POST /v1/evm/entities/tokens/erc721`](/api-reference/evm/entities/tokens-erc721)                              | 250           | 1000      | \~500                     |
| [`POST /v1/evm/entities/tokens/erc1155`](/api-reference/evm/entities/tokens-erc1155)                            | 250           | 1000      | \~500                     |
| [`POST /v1/evm/entities/pools`](/api-reference/evm/entities/pools)                                              | 250           | 1000      | \~600                     |
| [`POST /v1/evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms)                                | 250           | 1000      | \~400                     |
| [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves)                                                 | 250           | 1000      | \~800                     |
| **Swaps, yields, TVL**                                                                                          |               |           |                           |
| [`POST /v1/evm/swaps/fees`](/api-reference/evm/swaps/swap-fees)                                                 | 250           | 1000      | \~600                     |
| [`POST /v1/evm/yields`](/api-reference/evm/yields/yields)                                                       | 250           | 1000      | \~600                     |
| [`POST /v1/evm/tvl`](/api-reference/evm/tvl/tvl-usd)                                                            | 250           | 1000      | \~500                     |
| **Prices**                                                                                                      |               |           |                           |
| [`POST /v1/evm/prices/spot/crypto/prints`](/api-reference/evm/prices/crypto/prices-spot-prints)                 | 250           | 1000      | \~600                     |
| [`POST /v1/evm/prices/spot/crypto/ohlc`](/api-reference/evm/prices/crypto/prices-spot-ohlc)                     | 250           | 1000      | \~600                     |
| [`POST /v1/evm/prices/spot/crypto/vwap`](/api-reference/evm/prices/crypto/prices-spot-vwap)                     | 250           | 1000      | \~600                     |
| [`POST /v1/evm/prices/spot/crypto/vwap-aggregate`](/api-reference/evm/prices/crypto/prices-spot-vwap-aggregate) | 250           | 1000      | \~600                     |
| [`POST /v1/evm/prices/spot/fiat/vwap`](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat)                    | 250           | 1000      | \~600                     |
| **Flash loans & arbitrage**                                                                                     |               |           |                           |
| [`POST /v1/evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints)                           | 250           | 1000      | \~500                     |
| [`POST /v1/evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                                              | 250           | 1000      | \~400                     |
| [`POST /v1/evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)                                  | 250           | 1000      | \~350                     |
| [`POST /v1/evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities)                              | 250           | 1000      | \~500                     |

### Methodology

Sizes are indicative; shrink `limit` when rows include large `BYTEA` or array fields.


# Rate Limiting
Source: https://docs.blockdb.io/api-reference/overview/rate-limiting

Account-wide RPS and shared compute units across API keys, 429 handling, and backoff strategies.

## Overview

BlockDB enforces **account-wide** limits so traffic stays fair and the platform remains stable. Your subscription defines a **single requests-per-second (RPS) ceiling** and a **single compute unit (CU) usage allowance** for the billing period. Those limits are **shared by every API key** on the account: there is **no** per-key RPS budget, **no** per-key CU pool, and **no** way to split or “distribute” rate or usage across keys.

<Info>
  Rate limiting is measured in **requests per second (RPS)**. [`GET /usage`](/api-reference/account-and-usage/usage) returns `rate_limit_rps` and your **CU** fields (`cu_used`, `cu_limit`, `cu_remaining`) for the **account**—the same values apply no matter which of your keys (up to five) you use.
</Info>

<Warning>
  Using multiple API keys does **not** multiply your RPS or your monthly CU budget. If two services each send traffic at the account RPS cap, they contend for the same shared limit. Plan concurrency and backoff accordingly.
</Warning>

## API keys and shared limits

You can create up to **five** keys in **[dashboard.blockdb.io](https://dashboard.blockdb.io)** for **rotation** (old vs new), **separate environments** (e.g. staging vs production in your own systems), or **blast-radius control** (revoke one key without rotating everything). Those are operational choices—**not** a mechanism to assign different RPS or CU to each key. BlockDB does not offer per-key rate or usage allocation.

```bash Example: two keys, one shared account limit theme={null}
# Both keys authenticate different callers but draw from the same RPS and CU pool.
Authorization: Bearer $BLOCKDB_API_KEY_PROD
Authorization: Bearer $BLOCKDB_API_KEY_STAGING
# Shared: rate_limit_rps and monthly CU (see /usage)
```

## Rate Limit Responses

### 429 Too Many Requests

When you exceed your rate limit, the API returns `429` with a `Retry-After` header:

```json Error theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": "Limit: <CONFIGURED_RPS> requests/second. Retry after: <RETRY_AFTER>"
  }
}
```

## Backoff Strategies

### Exponential Backoff

Implement exponential backoff when receiving `429` responses:

<CodeGroup>
  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  public static async Task<HttpResponseMessage> RequestWithBackoffAsync(
      HttpClient client,
      Func<HttpRequestMessage> requestFactory,
      int maxRetries = 5)
  {
      var delay = TimeSpan.FromSeconds(1);

      for (var attempt = 0; attempt < maxRetries; attempt++)
      {
          using var request = requestFactory();
          var response = await client.SendAsync(request);

          if (response.StatusCode == (System.Net.HttpStatusCode)429)
          {
              var retryAfterHeader = response.Headers.RetryAfter?.Delta ?? delay;
              await Task.Delay(retryAfterHeader);
              delay = retryAfterHeader;
              continue;
          }

          if (response.IsSuccessStatusCode || attempt == maxRetries - 1)
          {
              return response;
          }

          await Task.Delay(delay);
          delay = TimeSpan.FromMilliseconds(delay.TotalMilliseconds * 2);
      }

      throw new InvalidOperationException("Retries exhausted");
  }
  ```

  ```cpp C++ theme={null}
  #include <chrono>
  #include <thread>
  #include <stdexcept>
  #include "http_client.h" // Replace with your preferred HTTP client wrapper

  HttpResponse requestWithBackoff(const HttpRequest& request, int maxRetries = 5) {
      using namespace std::chrono_literals;
      auto delay = 1s;

      for (int attempt = 0; attempt < maxRetries; ++attempt) {
          HttpResponse response = HttpClient::Send(request);

          if (response.status == 429) {
              auto retryAfter = response.headers.count("Retry-After")
                  ? std::chrono::seconds(std::stoi(response.headers.at("Retry-After")))
                  : delay;
              std::this_thread::sleep_for(retryAfter);
              delay = retryAfter;
              continue;
          }

          if (response.status < 500 || attempt == maxRetries - 1) {
              return response;
          }

          std::this_thread::sleep_for(delay);
          delay *= 2;
      }

      throw std::runtime_error("Retries exhausted");
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def request_with_backoff(url, headers, data, max_retries=5):
      delay = 1  # Start with 1 second
      
      for attempt in range(max_retries):
          try:
              response = requests.post(url, headers=headers, json=data)
              
              if response.status_code == 429:
                  retry_after = int(response.headers.get('Retry-After', delay))
                  time.sleep(retry_after)
                  delay = retry_after
                  continue
              
              return response
          except Exception as e:
              if attempt == max_retries - 1:
                  raise
              delay *= 2  # Exponential backoff
              time.sleep(delay)
  ```

  ```javascript Node.js theme={null}
  async function requestWithBackoff(url, options, maxRetries = 5) {
    let delay = 1000; // Start with 1 second
    
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      try {
        const response = await fetch(url, options);
        
        if (response.status === 429) {
          const retryAfter = parseInt(response.headers.get('Retry-After') || delay / 1000);
          delay = retryAfter * 1000;
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
        
        return response;
      } catch (error) {
        if (attempt === maxRetries - 1) throw error;
        delay *= 2; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
  ```
</CodeGroup>

## Best Practices

<Tip>
  Implement request queuing for high-volume applications to smooth out request patterns.
</Tip>

<Warning>
  Do not ignore `429` responses or retry immediately. Always respect the `Retry-After` header to avoid further rate limiting.
</Warning>

## Performance Expectations

When staying within your rate limits, typical **Historic REST API** response times look like:

* **Mean (average)**: 300-500 ms
* **p99**: around 900 ms

<Info>
  Figures are indicative and vary by endpoint, payload size, and region. Latency targets assume you're staying within your configured RPS limits. Sustained over-limit traffic may experience higher latency and eventual rate limiting.
</Info>

## Latency and routing (not separate quotas)

BlockDB may route you to a nearby edge or region for **lower latency** (for example via GeoDNS). That routing does **not** create separate RPS or CU pools per region or per key. Your **account** RPS and CU limits always apply the same way.

## Key rotation and dashboard

In **[dashboard.blockdb.io](https://dashboard.blockdb.io)** you can create, label, and revoke keys (up to five active). You **cannot** assign a different RPS or CU cap to an individual key—limits stay at the **account** level. Use [`GET /usage`](/api-reference/account-and-usage/usage) to monitor `rate_limit_rps` and **CU** usage for the whole account, not per key.

<Warning>
  Keep API keys secure and never commit them to version control. Rotate keys regularly for security best practices.
</Warning>

## See Also

* [Authorization](/api-reference/overview/authorization) — API keys and `Authorization: Bearer`
* [Usage & Limits](/api-reference/account-and-usage/usage) — `rate_limit_rps` and shared CU for your account
* [Compute units](/api-reference/overview/compute-units) - CU cost tiers (L1–L8) per endpoint family
* [Error Codes](/api-reference/overview/error-codes) - Complete error reference
* [Service Limits](/troubleshooting/service-limits/home) - Detailed quota information


# .NET SDK
Source: https://docs.blockdb.io/api-reference/sdks/dotnet

Official BlockDB SDK for .NET 10+ — install from NuGet, configure with an API key, and call any EVM endpoint with full async and DI support.

The BlockDB .NET SDK targets **.NET 10** and covers all EVM API endpoints. It sends your API key on every request, and supports cursor-based pagination, retries, and client-side rate limiting.

## Where it's available

* **NuGet:** [BlockDb.Api.Sdk](https://www.nuget.org/packages/BlockDb.Api.Sdk)
* **Source (open source):** [github.com/blockdb-io/blockdb-dotnet-api-sdk](https://github.com/blockdb-io/blockdb-dotnet-api-sdk)

## Installation

```bash theme={null}
dotnet add package BlockDb.Api.Sdk
```

## Quick examples

<CodeGroup>
  ```csharp With DI (ASP.NET Core / Generic Host) theme={null}
  // Program.cs
  using BlockDb.Api.Sdk;

  builder.Services.AddBlockDbClient(options =>
  {
      options.ApiKey = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")!;
  });

  // Inject and use anywhere
  public class MyService
  {
      private readonly BlockDbClient _blockDb;
      public MyService(BlockDbClient blockDb) => _blockDb = blockDb;

      public async Task<IReadOnlyList<Block>> GetRecentBlocksAsync(CancellationToken ct)
      {
          var response = await _blockDb.Primitives.GetBlocksAsync(new GetBlocksRequest
          {
              ChainId   = 1,
              FromBlock = 21_000_000,
              ToBlock   = 21_001_000,
              Limit     = 100
          }, ct);

          return response.Data;
      }
  }
  ```

  ```csharp Without DI (console / scripts) theme={null}
  using BlockDb.Api.Sdk;

  var client = BlockDbClientFactory.Create(new BlockDbClientOptions
  {
      ApiKey = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")!,
  });

  var blocks = await client.Primitives.GetBlocksAsync(new GetBlocksRequest
  {
      ChainId   = 1,
      FromBlock = 21_000_000,
      ToBlock   = 21_001_000,
  });

  Console.WriteLine($"Fetched {blocks.Count} blocks.");
  ```
</CodeGroup>

```csharp theme={null}
// 1-hour OHLCV candles for WETH/USDC
var candles = await client.Prices.Crypto.GetOhlcAsync(new GetPricesOhlcRequest
{
    ChainId           = 1,
    BaseTokenAddress  = "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", // WETH
    QuoteTokenAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    FromBlock         = 21_000_000,
    ToBlock           = 21_010_000,
    AggregationInterval = "1h",
});

foreach (var candle in candles.Data)
    Console.WriteLine($"{candle.OpenTimestamp}  O:{candle.Open}  H:{candle.High}  L:{candle.Low}  C:{candle.Close}");
```

## Pagination

Every endpoint returns `PagedResponse<T>` with a `Cursor` property. Pass the cursor back to retrieve the next page.

<CodeGroup>
  ```csharp Manual paging theme={null}
  string? cursor = null;
  do
  {
      var page = await client.Primitives.GetTransactionsAsync(new GetTransactionsRequest
      {
          ChainId   = 1,
          FromBlock = 20_000_000,
          ToBlock   = 20_100_000,
          Limit     = 1000,
          Cursor    = cursor,
      });

      ProcessBatch(page.Data);
      cursor = page.Cursor;
  }
  while (cursor is not null);
  ```

  ```csharp Automatic paging (PaginationExtensions) theme={null}
  using BlockDb.Api.Sdk.Models.Common;

  await foreach (var tx in PaginationExtensions.GetAllItemsAsync(
      new GetTransactionsRequest { ChainId = 1, FromBlock = 20_000_000, ToBlock = 20_100_000 },
      (req, ct) => client.Primitives.GetTransactionsAsync(req, ct)))
  {
      Console.WriteLine(tx.TxHash);
  }
  ```
</CodeGroup>

## Configuration reference

```csharp theme={null}
new BlockDbClientOptions
{
    // Required — from https://dashboard.blockdb.io
    ApiKey = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")!,

    // Optional overrides
    ApiBaseUrl           = "https://api.blockdb.io",   // default
    HttpTimeout          = TimeSpan.FromSeconds(30), // default
    EnableRetry          = true,
    MaxRetries           = 3,
    RetryBaseDelay       = TimeSpan.FromMilliseconds(500),
    EnableRateLimiting   = true,
    MaxRequestsPerSecond = 100,
}
```

See [Authorization](/api-reference/overview/authorization) for creating and rotating API keys.


# SDKs Overview
Source: https://docs.blockdb.io/api-reference/sdks/home

Official BlockDB SDKs for .NET, Python, and JavaScript/TypeScript — install, authenticate, and call the API with minimal code.

Use an official SDK to integrate BlockDB in your language of choice. Pass your **API key** (from [dashboard.blockdb.io](https://dashboard.blockdb.io)) and the client sends `Authorization: Bearer` on every request.

## Available SDKs

<CardGroup>
  <Card title=".NET" icon="microsoft" href="/api-reference/sdks/dotnet">
    NuGet package for .NET 10+. DI-friendly, fully async, full endpoint coverage.
  </Card>

  <Card title="Python" icon="python" href="/api-reference/sdks/python">
    PyPI package for Python 3.x. Async-first with a sync wrapper included.
  </Card>

  <Card title="JavaScript / TypeScript" icon="node-js" href="/api-reference/sdks/javascript">
    npm package for Node ≥ 18 and browsers. ESM + CJS, full TypeScript types.
  </Card>
</CardGroup>

## Quick comparison

| Feature        | .NET                                                                     | Python                                                         | JavaScript                                                      |
| -------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------- |
| **Package**    | [NuGet: BlockDb.Api.Sdk](https://www.nuget.org/packages/BlockDb.Api.Sdk) | [PyPI: blockdb](https://pypi.org/project/blockdb/)             | [npm: @blockdb/sdk](https://www.npmjs.com/package/@blockdb/sdk) |
| **Source**     | [GitHub](https://github.com/blockdb-io/blockdb-dotnet-api-sdk)           | [GitHub](https://github.com/blockdb-io/blockdb-python-api-sdk) | [GitHub](https://github.com/blockdb-io/blockdb-js-api-sdk)      |
| **Auth**       | API key                                                                  | API key                                                        | API key                                                         |
| **Async**      | Fully async (`Task<T>`)                                                  | Async-first + sync wrapper                                     | `async/await`, async generators                                 |
| **Pagination** | `PagedResponse<T>` + `PaginationExtensions`                              | `PagedResponse[T]` + `async_pages`                             | Cursor + `paginate*` generators                                 |

<Note>
  All SDKs are **open source** and do not embed secrets. Supply an API key at runtime (for example `BLOCKDB_API_KEY`). See [Authorization](/api-reference/overview/authorization) for creating and rotating keys.
</Note>

## Next steps

Pick your language above and follow the **Install** and **Quick example** on that page, then explore the [EVM endpoints](/api-reference/evm/overview) for the full API surface.


# JavaScript / TypeScript SDK
Source: https://docs.blockdb.io/api-reference/sdks/javascript

Official BlockDB SDK for Node.js and browsers — install from npm, full TypeScript types, async generators for pagination, and API key authentication.

The BlockDB JavaScript/TypeScript SDK supports **Node ≥ 18** (native `fetch`) and browsers. It ships as ESM and CJS with complete TypeScript types and zero required runtime dependencies.

## Where it's available

* **npm:** [@blockdb/sdk](https://www.npmjs.com/package/@blockdb/sdk)
* **Source (open source):** [github.com/blockdb-io/blockdb-js-api-sdk](https://github.com/blockdb-io/blockdb-js-api-sdk)

## Installation

```bash theme={null}
npm install @blockdb/sdk
```

## Quick example

```typescript theme={null}
import { BlockDbClient } from "@blockdb/sdk";

const client = new BlockDbClient({
  apiKey: process.env.BLOCKDB_API_KEY!,
});

// Fetch a single page of blocks
const result = await client.primitives.getBlocks({
  chain_id: 1,
  from_block: 21_000_000,
  to_block: 21_001_000,
  limit: 50,
});

console.log(`Got ${result.count} blocks. Next cursor: ${result.cursor}`);
result.data.forEach((b) => console.log(b.block_number, b.block_hash));
```

## Prices example

```typescript theme={null}
// WETH/USDC VWAP over a block range
const vwap = await client.prices.crypto.getVwap({
  chain_id: 1,
  base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",  // WETH
  quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
  from_block: 21_000_000,
  to_block: 21_010_000,
});

console.log(`WETH/USDC VWAP: ${vwap.data[0]?.vwap}`);
```

## Pagination

Every endpoint returns a `cursor` field. Pass it back to fetch the next page, or use the built-in `paginate*` async generators to iterate all pages automatically.

<CodeGroup>
  ```typescript Manual paging theme={null}
  let cursor: string | null | undefined;

  do {
    const page = await client.primitives.getBlocks({
      chain_id: 1,
      from_block: 21_000_000,
      to_block: 21_001_000,
      limit: 100,
      cursor,
    });

    page.data.forEach((b) => process(b));
    cursor = page.cursor;
  } while (cursor);
  ```

  ```typescript Async generator (all pages) theme={null}
  for await (const block of client.primitives.paginateBlocks({
    chain_id: 1,
    from_block: 21_000_000,
    to_block: 21_001_000,
  })) {
    console.log(block.block_number, block.block_hash);
  }
  ```

  ```typescript Paginate transactions theme={null}
  for await (const tx of client.primitives.paginateTransactions({
    chain_id: 1,
    from_block: 21_000_000,
    to_block: 21_000_100,
  })) {
    console.log(tx.tx_hash, tx.gas_used);
  }
  ```
</CodeGroup>

## Cancellation

Every request accepts an `AbortSignal` via the optional second `options` argument:

```typescript theme={null}
const controller = new AbortController();
setTimeout(() => controller.abort(), 3_000);

const tokens = await client.entities.getErc20Tokens(
  { chain_id: 1, contract_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" },
  { signal: controller.signal }
);
```

## Configuration reference

```typescript theme={null}
new BlockDbClient({
  // Required — from https://dashboard.blockdb.io
  apiKey: process.env.BLOCKDB_API_KEY!,

  // Optional overrides
  baseUrl:   "https://api.blockdb.io/v1",  // default
  timeoutMs: 30_000,                      // 30 s

  retry: {
    maxAttempts:      3,
    initialDelayMs:   500,
    maxDelayMs:       30_000,
    backoffMultiplier: 2,
  },

  // Inject a custom fetch (Node <18, test mocks, proxies, …)
  fetch: myCustomFetch,

  // Structured log hook
  onLog: (entry) => logger.debug(entry),
});
```


# Python SDK
Source: https://docs.blockdb.io/api-reference/sdks/python

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.


# Claude Skill
Source: https://docs.blockdb.io/build-with-ai/claude-skills

A ready-to-use Claude skill (SKILL.md) that turns Claude into a BlockDB query agent for Ethereum and EVM on-chain data.

A [Claude skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) packages instructions Claude loads on demand. Drop the one below into your skills directory and Claude can answer on-chain questions by calling BlockDB.

## Create the skill

Save as `blockdb/SKILL.md`:

```markdown theme={null}
---
name: blockdb
description: Query Ethereum / EVM on-chain data (blocks, transactions, transfers, DEX swaps, pools, prices, TVL) via the BlockDB REST API. Use whenever the user asks for on-chain or DeFi data.
---

# BlockDB

Call the BlockDB REST API to answer on-chain data questions.

## Rules
- Base URL: `https://api.blockdb.io/v1`
- Auth: send `Authorization: Bearer <BLOCKDB_API_KEY>` on every request (key from env).
- All endpoints are `POST` + JSON body (filters in the body). Exception: `GET /usage`.
- Response: `{ "data": [...], "cursor": "<string|null>", "page_count": <number> }`.
  Paginate by resending the body with `cursor` until it is null.
- Always include `chain_id` (Ethereum = 1). Prefer `from_block`/`to_block`.
- Never invent chain_id, exchange_id, pool_type_id, or addresses. Resolve IDs from
  https://docs.blockdb.io/api-reference/enumerations/overview.

## Picking an endpoint
- Raw chain data → /api-reference/evm/primitives/overview
- Transfers → /api-reference/evm/transfers/token-transfers
- Swaps → /api-reference/evm/swaps/overview
- Prices → /api-reference/evm/prices/overview
- Full index → /api-reference/evm/overview

## Example
POST https://api.blockdb.io/v1/evm/transfers/token-transfers
{ "chain_id": 1, "from_block": 19000000, "to_block": 19001000, "limit": 250 }
```

## Example prompts

Once the skill is available, ask Claude directly:

> "What were the top 10 largest USDC transfers on Ethereum between blocks 19000000 and 19010000?"

> "Pull Uniswap v3 WETH/USDC swaps for yesterday and chart hourly volume."

## No-key path

For historical research, the [free datasets](/free-datasets/home) need no API key — tell Claude to read the Parquet files from Hugging Face.


# Cursor
Source: https://docs.blockdb.io/build-with-ai/cursor

Add a Cursor rule so the agent calls the BlockDB API correctly — auth, POST + JSON bodies, block ranges, and cursor pagination.

Drop the rule below into your project so Cursor writes correct BlockDB API calls — right auth, right body shape, right pagination.

## Add the rule

Save this as `.cursor/rules/blockdb.mdc` in your project. Cursor loads it automatically.

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

## Use the free datasets for backtests

For historical work, point Cursor at the [free Parquet datasets](/free-datasets/home) instead of the API — no key, no rate limits:

```python theme={null}
import polars as pl
df = pl.read_parquet("hf://datasets/blockdb/ethereum-dex-swaps/year=2024/")
```

<Tip>
  The rule above is a trimmed version of [LLM onboarding](/api-reference/overview/llm-onboarding). Link the full page in long agent sessions for complete pagination and error-handling guidance.
</Tip>


# Build with AI
Source: https://docs.blockdb.io/build-with-ai/overview

Wire BlockDB into AI coding tools — a Cursor rule and a Claude skill, tuned to our API and free datasets, that query on-chain data in natural language.

BlockDB is built to be called by machines. The schema is stable, every endpoint is `POST` + JSON, and responses carry lineage. These pages give you drop-in artifacts so your AI tools can query our API and datasets without you writing glue code.

<CardGroup>
  <Card title="Cursor" icon="laptop-code" href="/build-with-ai/cursor">
    A ready-to-paste rule that teaches Cursor to call the API correctly.
  </Card>

  <Card title="Claude Skill" icon="sparkles" href="/build-with-ai/claude-skills">
    A SKILL.md that turns Claude into a BlockDB query agent.
  </Card>
</CardGroup>

## Start here

Every artifact below builds on the same instruction set. If you're wiring up something custom, point your model at [LLM onboarding](/api-reference/overview/llm-onboarding) — it covers auth, pagination, limits, and the rules that keep generated requests valid.

<Note>
  All paths need an API key (`Authorization: Bearer <API_KEY>`). Create one at [dashboard.blockdb.io](https://dashboard.blockdb.io). Free [historical datasets](/free-datasets/home) need no key at all.
</Note>


# Arbitrage Opportunities
Source: https://docs.blockdb.io/data-catalog/evm/arbitrage/arb-opportunities

Estimated arbitrage profit and token amounts per path at a given on-chain position.

## Overview

* **Dataset ID:** `0901`
* **Table:** `blockdb_evm.b0901_arb_opportunities_v1`
* **Description:** Opportunities computed for active paths at a specific `(block_number, tx_index, log_index)`.
* **Primary key:** `(path_id, is_reversed, block_number, tx_index, log_index)`
* **API:** [POST /evm/arb/opportunities](/api-reference/evm/arbitrage/arb-opportunities)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Opportunities-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0901_arb_opportunities_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Opportunities-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0901_arb_opportunities_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type               | Description                                |
| --------------------- | ------------------ | ------------------------------------------ |
| `block_number`        | `BIGINT`           | Observation block.                         |
| `block_time`          | `TIMESTAMPTZ`      | Block time.                                |
| `tx_index`            | `INTEGER`          | Transaction index.                         |
| `log_index`           | `INTEGER`          | Log index.                                 |
| `path_id`             | `BYTEA`            | 32B path id (`octet_length` = 32).         |
| `is_reversed`         | `BOOLEAN`          | True if evaluated in reversed direction.   |
| `pool_uids`           | `BYTEA[]`          | Pool UIDs in evaluated order.              |
| `token_path`          | `BYTEA[]`          | Tokens in evaluated order.                 |
| `amounts`             | `NUMERIC(78,18)[]` | Per-hop amounts aligned with `token_path`. |
| `profit_in_tokens`    | `NUMERIC(78,18)`   | Profit in `token_path[0]` units.           |
| `token_vwap_usd`      | `NUMERIC(78,18)`   | Token-to-Fiat VWAP USD of token\_path\[0]. |
| `profit_in_usd`       | `NUMERIC(78,18)`   | Profit in USD.                             |
| `_tracing_id`         | `BYTEA`            | Unique tracing ID.                         |
| `_parent_tracing_ids` | `BYTEA[]`          | Parent tracing IDs.                        |
| `_created_at`         | `TIMESTAMPTZ`      | Record creation time.                      |
| `_updated_at`         | `TIMESTAMPTZ`      | Record last update time.                   |

## Related datasets

<Card title="Arbitrage paths" icon="route" href="/data-catalog/evm/arbitrage/arb-paths">
  Path topology and activation status.
</Card>


# Arbitrage Paths
Source: https://docs.blockdb.io/data-catalog/evm/arbitrage/arb-paths

Arbitrage cycle topology and per-path active/inactive status events.

## Overview

Two complementary datasets covering arbitrage cycle topology and lifecycle.

* **Dataset IDs:** `0801` (paths), `0802` (path status)
* **Tables:** `blockdb_evm.b0801_arb_paths_v1`, `blockdb_evm.b0801_arb_path_status_v1`
* **Description:** Undirected arbitrage cycle topology (paths) and their per-event active/inactive status transitions (path status).
* **Primary keys:** `path_id` (paths); `(path_id, block_number, tx_index, log_index)` (path status)
* **API:** [POST /evm/arb/paths](/api-reference/evm/arbitrage/arb-paths), [POST /evm/arb/path-status](/api-reference/evm/arbitrage/arb-path-status)
* **CSV Sample (paths):** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0701_arb_paths_v1.csv?download=true)
* **JSON Sample (paths):** [Download](https://huggingface.co/datasets/BlockDB/MEV-Arbitrage-Paths-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb0701_arb_paths_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Arbitrage paths (`blockdb_evm.b0801_arb_paths_v1`)

The paths table is the **topology registry** for arbitrage cycles. One row is written the first time a given cycle is detected on-chain. A cycle is an undirected loop of pools and tokens — for example a two-hop `A → B → A` or a three-hop `A → B → C → A` — where swapping around the loop could yield a net profit. The `path_id` is a stable 32-byte hash of the cycle topology and serves as the join key for the path status and opportunities tables.

**Primary key:** `path_id`

| Column                | Type          | Description                                                                                                                                                                     |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path_id`             | `BYTEA`       | 32-byte hash that uniquely identifies this undirected cycle. Stable across blocks — the same topology always produces the same `path_id`.                                       |
| `block_number`        | `BIGINT`      | Block height where this path was first observed on-chain.                                                                                                                       |
| `block_time`          | `TIMESTAMPTZ` | UTC timestamp of the block in which the path was first detected.                                                                                                                |
| `tx_index`            | `INTEGER`     | Transaction index within that block (genesis event).                                                                                                                            |
| `log_index`           | `INTEGER`     | Log index within that transaction (genesis event).                                                                                                                              |
| `pool_uids`           | `BYTEA[]`     | Ordered array of pool UIDs forming the cycle. The last hop returns to the starting pool, completing the loop. Join to `blockdb_evm.b0211_liquidity_pools_v1` for pool metadata. |
| `token_cycle`         | `BYTEA[]`     | Token sequence traversed around the cycle (e.g. `[A, B, A]` for arb2 or `[A, B, C, A]` for arb3). The first and last token are always the same (the profit-bearing asset).      |
| `_tracing_id`         | `BYTEA`       | Deterministic BlockDB lineage identifier for this path record.                                                                                                                  |
| `_parent_tracing_ids` | `BYTEA[]`     | Lineage identifiers of the upstream pool/reserve events that triggered path discovery.                                                                                          |
| `_created_at`         | `TIMESTAMPTZ` | Record creation timestamp.                                                                                                                                                      |
| `_updated_at`         | `TIMESTAMPTZ` | Record last update timestamp.                                                                                                                                                   |

## Arbitrage path status (`blockdb_evm.b0801_arb_path_status_v1`)

The path status table records **every activation and deactivation event** for each path. A path becomes active when all its constituent pools are live and arbitrageable; it becomes inactive when a pool in the cycle is deactivated, has insufficient liquidity, or its reserves change in a way that closes the opportunity. Each row captures the exact on-chain event that caused the transition, making it possible to reconstruct the full activation history of any path.

**Primary key:** `(path_id, block_number, tx_index, log_index)`

| Column                | Type          | Description                                                                                                                                                      |
| --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path_id`             | `BYTEA`       | Reference to the path topology in `b0801_arb_paths_v1`.                                                                                                          |
| `block_number`        | `BIGINT`      | Block height of the status change event.                                                                                                                         |
| `block_time`          | `TIMESTAMPTZ` | UTC timestamp of the block containing this status change.                                                                                                        |
| `tx_index`            | `INTEGER`     | Transaction index within the block.                                                                                                                              |
| `log_index`           | `INTEGER`     | Log index within the transaction — pinpoints the exact event that caused the status change.                                                                      |
| `is_active`           | `BOOLEAN`     | `true` when the path became active (all pools live and arbitrageable); `false` when it was deactivated.                                                          |
| `trigger_pool_uid`    | `BYTEA`       | The specific pool whose reserve or state change triggered this status transition. Useful for diagnosing which leg of the cycle opened or closed the opportunity. |
| `_tracing_id`         | `BYTEA`       | Deterministic BlockDB lineage identifier for this status event.                                                                                                  |
| `_parent_tracing_ids` | `BYTEA[]`     | Lineage identifiers of the upstream reserve or swap events that caused this status change.                                                                       |
| `_created_at`         | `TIMESTAMPTZ` | Record creation timestamp.                                                                                                                                       |
| `_updated_at`         | `TIMESTAMPTZ` | Record last update timestamp.                                                                                                                                    |

## Related datasets

<CardGroup>
  <Card title="Arbitrage opportunities" icon="chart-line" href="/data-catalog/evm/arbitrage/arb-opportunities">
    Profit estimates per path and on-chain position.
  </Card>

  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pool metadata for the pools referenced in each cycle.
  </Card>
</CardGroup>


# Dataset Index
Source: https://docs.blockdb.io/data-catalog/evm/dataset-index

Quick reference index for all BlockDB EVM datasets — SQL table names, dataset IDs, and REST API identifiers.

## Dataset index

| Dataset | Table                                                                                                                  | Description                                                                     |
| ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `0101`  | [`blockdb_evm.b0101_blocks_v1`](/data-catalog/evm/primitives/blocks)                                                   | Canonical EVM blocks with integrity metadata.                                   |
| `0102`  | [`blockdb_evm.b0102_transactions_v1`](/data-catalog/evm/primitives/transactions)                                       | Executed transactions, gas, and status.                                         |
| `0103`  | [`blockdb_evm.b0103_logs_v1`](/data-catalog/evm/primitives/logs)                                                       | Event logs emitted by smart contracts.                                          |
| `0111`  | [`blockdb_evm.b0111_internal_transactions_v1`](/data-catalog/evm/primitives/internal-transactions)                     | Internal call traces.                                                           |
| `0121`  | [`blockdb_evm.b0121_contracts_v1`](/data-catalog/evm/primitives/contracts)                                             | Contract deployments (CREATE/CREATE2).                                          |
| `0122`  | [`blockdb_evm.b0122_function_results_v1`](/data-catalog/evm/primitives/function-results)                               | Deterministic contract call outputs.                                            |
| `0201`  | [`blockdb_evm.b0201_erc20_tokens_v1`](/data-catalog/evm/entities/erc20-tokens)                                         | ERC-20 token registry.                                                          |
| `0202`  | [`blockdb_evm.b0202_erc721_tokens_v1`](/data-catalog/evm/entities/erc721-tokens)                                       | ERC-721 collection registry.                                                    |
| `0203`  | [`blockdb_evm.b0203_erc1155_tokens_v1`](/data-catalog/evm/entities/erc1155-tokens)                                     | ERC-1155 contract catalog.                                                      |
| `0211`  | [`blockdb_evm.b0211_liquidity_pools_v1`](/data-catalog/evm/entities/liquidity-pools)                                   | On-chain AMM pools.                                                             |
| `0212`  | [`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`](/data-catalog/evm/entities/liquidity-pools-fee-terms)               | Per-pool fee configuration over time.                                           |
| `0301`  | [`blockdb_evm.b0301_liquidity_pools_reserves_v1`](/data-catalog/evm/reserves/liquidity-pools-reserves)                 | Pool reserve snapshots; details in `b0301_liquidity_pools_reserves_details_v1`. |
| `0302`  | [`blockdb_evm.b0302_token_to_token_prices_swap_prints_v1`](/data-catalog/evm/prices/token-to-token-prices-swap-prints) | Executed swap prints.                                                           |
| `0303`  | [`blockdb_evm.b0303_liquidity_pools_swap_fees_v1`](/data-catalog/evm/swaps/liquidity-pools-swap-fees)                  | Per-swap fee accounting.                                                        |
| `0304`  | [`blockdb_evm.b0304_token_transfers_v1`](/data-catalog/evm/transfers/token-transfers)                                  | Token transfers (native + tokens).                                              |
| `0305`  | [`blockdb_evm.b0305_flash_loan_prints_v1`](/data-catalog/evm/flash-loans/flash-loan-prints)                            | Flash loan prints.                                                              |
| `0404`  | [`blockdb_evm.b0404_token_to_token_prices_ohlc_v1`](/data-catalog/evm/prices/token-to-token-prices-ohlc)               | OHLC bars per pool and direction.                                               |
| `0405`  | [`blockdb_evm.b0405_token_to_token_vwap_v1`](/data-catalog/evm/prices/token-to-token-vwap)                             | Token-to-token VWAP per pool.                                                   |
| `0411`  | [`blockdb_evm.b0411_liquidity_pools_yields_v1`](/data-catalog/evm/yields/liquidity-pools-yields)                       | Pool yield / ROI predictions.                                                   |
| `0505`  | [`blockdb_evm.b0505_token_to_token_cross_pool_vwap_v1`](/data-catalog/evm/prices/token-to-token-cross-pool-vwap)       | Cross-venue token-to-token VWAP (all pools aggregated).                         |
| `0605`  | [`blockdb_evm.b0605_token_to_fiat_vwap`](/data-catalog/evm/prices/token-to-fiat-vwap)                                  | Token-to-USD VWAP buckets.                                                      |
| `0701`  | [`blockdb_evm.b0701_liquidity_pools_tvl_usd_v1`](/data-catalog/evm/tvl/liquidity-pools-tvl-usd)                        | Pool TVL in USD.                                                                |
| `0801`  | [`blockdb_evm.b0801_arb_paths_v1`](/data-catalog/evm/arbitrage/arb-paths)                                              | Arbitrage path definitions.                                                     |
| `0802`  | [`blockdb_evm.b0801_arb_path_status_v1`](/data-catalog/evm/arbitrage/arb-paths)                                        | Arbitrage path active/inactive status events.                                   |
| `0901`  | [`blockdb_evm.b0901_arb_opportunities_v1`](/data-catalog/evm/arbitrage/arb-opportunities)                              | Arbitrage opportunities.                                                        |


# ERC-1155 Tokens
Source: https://docs.blockdb.io/data-catalog/evm/entities/erc1155-tokens

ERC-1155 multi-token contract registry — URI, ERC-165 detection, gaming assets. Ethereum & EVM chains. REST API.

## Overview

* **Dataset ID:** `0203`
* **Table:** `blockdb_evm.b0203_erc1155_tokens_v1`
* **Description:** Catalog of ERC-1155 Multi Token contracts (EIP-1155); one contract can have many token types.
* **Stable id:** `contract_id` (per deployment incarnation; multiple snapshot rows possible—see callout)
* **API:** [POST /evm/entities/tokens/erc1155](/api-reference/evm/entities/tokens-erc1155)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC1155-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0203_erc1155_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC1155-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0203_erc1155_tokens_v1.json?download=true)

### How we recognize ERC-1155

We treat a contract as ERC-1155 when it complies with the [EIP-1155 Multi Token Standard](https://eips.ethereum.org/EIPS/eip-1155). Primary detection uses [ERC-165](https://eips.ethereum.org/EIPS/eip-165): we call `supportsInterface(0xd9b67a26)` and, if it returns true, we classify the address as an ERC-1155 multi-token contract. If that check is unavailable, we use a fallback heuristic: the contract returns a valid result for `balanceOf(address, uint256)` (the two-argument form required by EIP-1155) and does not implement `ownerOf(uint256)` or `decimals()`, so it is distinguished from ERC-721 and ERC-20. The optional **ERC1155Metadata\_URI** extension (`uri(uint256)`) is detected via ERC-165; we store `uri`, `supports_metadata_uri`, and any optional `name`/`symbol`/`decimals` when present.

<Callout icon="lightbulb">
  This table is **append-only**: the same `contract_id` can have **multiple rows** when an upgradeable proxy swaps implementation—we append refreshed view reads at **`upgradeBlock + 1`** with **`tx_index = -1`** (genesis rows use a normal tx index). For **current** metadata, take the **latest** `block_number` per `contract_id` (for point-in-time, add `block_number <= $target` first). Join on **`contract_id`**, not `contract_address` alone—redeploys at the same address get a new `contract_id`.
</Callout>

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                  | Type          | Description                                                                                              |
| ----------------------- | ------------- | -------------------------------------------------------------------------------------------------------- |
| `contract_id`           | `BYTEA`       | Unique contract incarnation ID: 20B address + 4B creation block (BE) + 2B tx\_index (BE).                |
| `contract_address`      | `BYTEA`       | Address of the ERC-1155 contract (20 bytes).                                                             |
| `block_number`          | `BIGINT`      | Block of the log we attribute as the genesis/recognition point.                                          |
| `block_time`            | `TIMESTAMPTZ` | UTC timestamp of the block.                                                                              |
| `tx_index`              | `INTEGER`     | Transaction index in the block, or **`-1`** for proxy-upgrade refresh rows (see callout).                |
| `name`                  | `TEXT`        | Contract name from name() (optional in EIP-1155).                                                        |
| `symbol`                | `TEXT`        | Contract symbol from symbol() (optional in EIP-1155).                                                    |
| `decimals`              | `SMALLINT`    | Contract decimals from decimals() (optional in EIP-1155).                                                |
| `uri`                   | `TEXT`        | URI from uri(uint256) (optional ERC1155Metadata\_URI); clients replace  with token ID in hex (64 chars). |
| `supports_metadata_uri` | `BOOLEAN`     | Whether the contract supports the ERC1155Metadata\_URI extension; NULL when detection was via fallback.  |
| `_tracing_id`           | `BYTEA`       | Tracing ID of this record.                                                                               |
| `_parent_tracing_ids`   | `BYTEA[]`     | Tracing IDs of the parent records.                                                                       |
| `_created_at`           | `TIMESTAMPTZ` | Record creation timestamp.                                                                               |
| `_updated_at`           | `TIMESTAMPTZ` | Record last update timestamp.                                                                            |

## Use Cases

* Multi-token and semi-fungible contract registry
* Game assets and metaverse item catalogs
* Metadata resolution via uri(uint256) with  substitution
* Portfolio and transfer analytics for ERC-1155 holdings

## Related Datasets

<CardGroup>
  <Card title="Token Transfers" icon="coins" href="/data-catalog/evm/transfers/token-transfers">
    ERC-1155 transfer events for these tokens.
  </Card>

  <Card title="ERC-20 Tokens" icon="circle-dollar-to-slot" href="/data-catalog/evm/entities/erc20-tokens">
    Fungible token registry for cross-standard analysis.
  </Card>

  <Card title="ERC-721 Tokens" icon="image" href="/data-catalog/evm/entities/erc721-tokens">
    NFT token registry for cross-standard joins.
  </Card>
</CardGroup>


# ERC-20 Tokens
Source: https://docs.blockdb.io/data-catalog/evm/entities/erc20-tokens

Production-grade ERC-20 token registry with name, symbol & decimals verified across 10 EVM chains. REST API and bulk export.

## Overview

* **Dataset ID:** `0201`
* **Table:** `blockdb_evm.b0201_erc20_tokens_v1`
* **Description:** Catalog of ERC-20 token contracts (EIP-20).
* **Stable id:** `contract_id` (per deployment incarnation; multiple snapshot rows possible—see callout)
* **API:** [POST /evm/entities/tokens/erc20](/api-reference/evm/entities/tokens-erc20)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0201_erc20_tokens_v1.json?download=true)

### How we recognize ERC-20

We treat a contract as ERC-20 when it implements the [EIP-20 Token Standard](https://eips.ethereum.org/EIPS/eip-20). Detection requires that the contract exposes and returns valid results for the **three mandatory** EIP-20 functions: `totalSupply()`, `balanceOf(address)`, and `allowance(address, address)`. We call these at the block where the contract is first seen and only add the address to this catalog if all three calls succeed and return decodable data. The **optional** EIP-20 metadata — `name()`, `symbol()`, and `decimals()` — are read when present and stored in the table; they may be null for tokens that do not implement them.

<Callout icon="lightbulb">
  This table is **append-only**: the same `contract_id` can have **multiple rows** when an upgradeable proxy swaps implementation—we append refreshed view reads at **`upgradeBlock + 1`** with **`tx_index = -1`** (genesis rows use a normal tx index). For **current** metadata, take the **latest** `block_number` per `contract_id` (for point-in-time, add `block_number <= $target` first). Join on **`contract_id`**, not `contract_address` alone—redeploys at the same address get a new `contract_id`.
</Callout>

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type          | Description                                                                               |
| --------------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `contract_id`         | `BYTEA`       | Unique contract incarnation ID: 20B address + 4B creation block (BE) + 2B tx\_index (BE). |
| `contract_address`    | `BYTEA`       | Address of the ERC-20 token contract (20 bytes).                                          |
| `block_number`        | `BIGINT`      | Block of the log we attribute as the genesis/recognition point.                           |
| `block_time`          | `TIMESTAMPTZ` | UTC timestamp of the block.                                                               |
| `tx_index`            | `INTEGER`     | Transaction index in the block, or **`-1`** for proxy-upgrade refresh rows (see callout). |
| `name`                | `TEXT`        | Token name from name() (optional in EIP-20).                                              |
| `symbol`              | `TEXT`        | Token symbol from symbol() (optional in EIP-20).                                          |
| `decimals`            | `SMALLINT`    | Decimals from decimals() (optional in EIP-20; e.g. 8 = divide by 10^8).                   |
| `_tracing_id`         | `BYTEA`       | Tracing ID of this ERC-20 token record.                                                   |
| `_parent_tracing_ids` | `BYTEA[]`     | Tracing IDs of the parent records leading to this ERC-20 token record.                    |
| `_created_at`         | `TIMESTAMPTZ` | Record creation timestamp.                                                                |
| `_updated_at`         | `TIMESTAMPTZ` | Record last update timestamp.                                                             |

## Use Cases

* Token registry to normalize joins for swaps, transfers, pools, and prices
* Amount scaling via decimals for analytics, PnL, and model features
* App backends: display names/symbols and validate token addresses

## Related Datasets

<CardGroup>
  <Card title="Token Transfers" icon="coins" href="/data-catalog/evm/transfers/token-transfers">
    ERC-20 transfer events for these tokens.
  </Card>

  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pools where these tokens are paired.
  </Card>

  <Card title="ERC-721 Tokens" icon="image" href="/data-catalog/evm/entities/erc721-tokens">
    NFT token registry for cross-standard analysis.
  </Card>
</CardGroup>


# ERC-721 Tokens
Source: https://docs.blockdb.io/data-catalog/evm/entities/erc721-tokens

Complete NFT collection registry for Ethereum & EVM chains — ERC-721 metadata, ERC-165 detection. REST API and bulk export.

## Overview

* **Dataset ID:** `0202`
* **Table:** `blockdb_evm.b0202_erc721_tokens_v1`
* **Description:** Catalog of ERC-721 NFT collection contracts (EIP-721).
* **Stable id:** `contract_id` (per deployment incarnation; multiple snapshot rows possible—see callout)
* **API:** [POST /evm/entities/tokens/erc721](/api-reference/evm/entities/tokens-erc721)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC721-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0202_erc721_tokens_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/ERC721-Tokens-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0202_erc721_tokens_v1.json?download=true)

### How we recognize ERC-721

We treat a contract as ERC-721 when it complies with the [EIP-721 Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721). Primary detection uses [ERC-165](https://eips.ethereum.org/EIPS/eip-165): we call `supportsInterface(0x80ac58cd)` and, if it returns true, we classify the address as an ERC-721 NFT collection. If that check is unavailable, we use a fallback heuristic: the contract returns a valid result for `ownerOf(uint256)` and does not implement `decimals()` (so it is distinguished from ERC-20). Optional extensions — **ERC721Metadata** (name, symbol, tokenURI) and **ERC721Enumerable** — are detected via their ERC-165 interface IDs; we store `token_uri`, `supports_metadata`, and `supports_enumerable` when present.

<Callout icon="lightbulb">
  This table is **append-only**: the same `contract_id` can have **multiple rows** when an upgradeable proxy swaps implementation—we append refreshed view reads at **`upgradeBlock + 1`** with **`tx_index = -1`** (genesis rows use a normal tx index). For **current** metadata, take the **latest** `block_number` per `contract_id` (for point-in-time, add `block_number <= $target` first). Join on **`contract_id`**, not `contract_address` alone—redeploys at the same address get a new `contract_id`.
</Callout>

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type          | Description                                                                                         |
| --------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
| `contract_id`         | `BYTEA`       | Unique contract incarnation ID: 20B address + 4B creation block (BE) + 2B tx\_index (BE).           |
| `contract_address`    | `BYTEA`       | Address of the ERC-721 contract (20 bytes).                                                         |
| `block_number`        | `BIGINT`      | Block of the log we attribute as the genesis/recognition point.                                     |
| `block_time`          | `TIMESTAMPTZ` | UTC timestamp of the block.                                                                         |
| `tx_index`            | `INTEGER`     | Transaction index in the block, or **`-1`** for proxy-upgrade refresh rows (see callout).           |
| `name`                | `TEXT`        | Collection name from name() (ERC721Metadata, optional).                                             |
| `symbol`              | `TEXT`        | Collection symbol from symbol() (ERC721Metadata, optional).                                         |
| `token_uri`           | `TEXT`        | Representative sample from the discovery probe.                                                     |
| `supports_metadata`   | `BOOLEAN`     | Whether the contract supports the ERC721Metadata extension; NULL when detection was via fallback.   |
| `supports_enumerable` | `BOOLEAN`     | Whether the contract supports the ERC721Enumerable extension; NULL when detection was via fallback. |
| `_tracing_id`         | `BYTEA`       | Tracing ID of this ERC-721 token record.                                                            |
| `_parent_tracing_ids` | `BYTEA[]`     | Tracing IDs of the parent records leading to this ERC-721 token record.                             |
| `_created_at`         | `TIMESTAMPTZ` | Record creation timestamp.                                                                          |
| `_updated_at`         | `TIMESTAMPTZ` | Record last update timestamp.                                                                       |

## Use Cases

* NFT collection registry for marketplaces and analytics platforms
* Collection discovery and new listing detection
* Metadata resolution via token\_uri for display purposes
* Portfolio tracking and wallet analytics for NFT holdings

## Related Datasets

<CardGroup>
  <Card title="Token Transfers" icon="coins" href="/data-catalog/evm/transfers/token-transfers">
    ERC-721 transfer events for these NFTs.
  </Card>

  <Card title="ERC-20 Tokens" icon="circle-dollar-to-slot" href="/data-catalog/evm/entities/erc20-tokens">
    Fungible token registry for cross-standard joins.
  </Card>

  <Card title="ERC-1155 Tokens" icon="layer-group" href="/data-catalog/evm/entities/erc1155-tokens">
    Multi-token standard for gaming and metaverse assets.
  </Card>
</CardGroup>


# Liquidity Pools
Source: https://docs.blockdb.io/data-catalog/evm/entities/liquidity-pools

Canonical AMM liquidity pool registry — exchange, factory, token pairs, config. 10 EVM chains. REST API and bulk export.

## Overview

* **Dataset ID:** `0211`
* **Table:** `blockdb_evm.b0211_liquidity_pools_v1`
* **Description:** Canonical list of pools; child time-series tables FK to blockdb\_evm.b0211\_liquidity\_pools\_v1(pool\_uid).
* **Primary key:** `pool_uid`
* **API:** [POST /evm/entities/pools](/api-reference/evm/entities/pools)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0211_liquidity_pools_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0211_liquidity_pools_v1.json?download=true)

### How we recognize Liquidity Pools

BlockDB builds the pool registry from **factory-style events** (e.g. Uniswap V2-like `PairCreated` / pool-creation topics) decoded from chain logs, scoped to **known DEX factories** in our exchange metadata.

**Logs alone are not sufficient.** The same pair address can appear in **more than one** `PairCreated`-style log over time—for example when a factory or router path **re-references an existing pair** without deploying a new contract. On-chain, a real new pool is introduced by a **`CREATE` / `CREATE2`** in that transaction's trace; a follow-up transaction may only show reads (e.g. `STATICCALL` to `getPair`) while still emitting a creation-shaped log. Treating every such log as a new pool would pollute the registry.

So for **address-based pools** we **cross-check** each candidate creation log against **internal transactions** for the same `(block_number, transaction_index)` - we require a successful internal **`create` / `create2`** whose **deployed address** matches the **pair/pool address** from the log before we accept it as a new pool.

**Example on Ethereum mainnet (Internal Traces tab) pool address `0x397FF1542f962076d0BFE58eA045FfA2d347ACa0`:**

* **Real deploy:** internal tx shows **`create`** and the new pool contract
  [`0x9011586359ddfc2660fe5bcdf2b53f1d4238ab4f4f998bc79a8cd69aa7c9040d#internal`](https://etherscan.io/tx/0x9011586359ddfc2660fe5bcdf2b53f1d4238ab4f4f998bc79a8cd69aa7c9040d#internal)
* **No deploy:** internal txs show only calls like **`staticcall`** (e.g. `getPair`) — **no** `create` matching the pair
  [`0xa3b1c46152f564a2c3f8a870833225360aad4c6a6feb27b1207e79349d59e55c#internal`](https://etherscan.io/tx/0xa3b1c46152f564a2c3f8a870833225360aad4c6a6feb27b1207e79349d59e55c/advanced#internal)

Non-address pools (e.g. some **V4-style** identifiers) use different discovery rules.

<Callout icon="lightbulb">
  **Takeaway:** we use **pool-creation logs** as the signal, and **internal transaction traces** as a **sanity check** when traces exist—because **multiple creation-shaped logs can refer to one pool**, and only the trace proves a **new** deployment in that transaction.
</Callout>

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type             | Description                                                                                                        |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `pool_uid`            | `BYTEA`          | Stable surrogate key derived from address or pool\_id (used across datasets).                                      |
| `exchange_id`         | `INTEGER`        | Exchange identifier (e.g., 1 for Uniswap, 2 for Sushiswap, etc.).                                                  |
| `type_id`             | `INTEGER`        | Pool type identifier (e.g. 201 for Uniswap V2, 301 for Uniswap V3).                                                |
| `block_number`        | `BIGINT`         | Block number where pool was first recognized/derived.                                                              |
| `block_time`          | `TIMESTAMPTZ`    | UTC timestamp for the block that produced this record.                                                             |
| `tx_index`            | `INTEGER`        | Zero-based transaction index within the block.                                                                     |
| `log_index`           | `INTEGER`        | Zero-based log index within the transaction.                                                                       |
| `factory`             | `BYTEA`          | Factory/pool-manager contract address.                                                                             |
| `tokens`              | `BYTEA[]`        | Array of token addresses that compose the pool, ordered as stored on-chain.                                        |
| `contract_id`         | `BYTEA`          | Incarnation ID for v2/v3 pools: 20B address + 4B creation block (BE) + 2B tx\_index (BE). NULL for v4-style pools. |
| `contract_address`    | `BYTEA`          | 20B address for v2/v3-style pools (nullable for id-only v4).                                                       |
| `pool_id`             | `BYTEA`          | 32B identifier for v4-style pools (nullable for v2/v3).                                                            |
| `pairnum`             | `NUMERIC(6)`     | Internal index representing the slot/order of the token pair within the pool.                                      |
| `asset_managers`      | `BYTEA[]`        | Optional array of asset manager addresses for Balancer-style custodial pools.                                      |
| `amp`                 | `NUMERIC(6)`     | Amplification coefficient for stable or hybrid pools (NULL for constant product pools).                            |
| `weights`             | `NUMERIC(6,5)[]` | Array of normalized token weights for weighted pools (e.g., Balancer).                                             |
| `tick_spacing`        | `SMALLINT`       | Tick spacing parameter for concentrated liquidity pools.                                                           |
| `_tracing_id`         | `BYTEA`          | BlockDB lineage identifier that links this record to lineage APIs.                                                 |
| `_parent_tracing_ids` | `BYTEA[]`        | Tracing identifiers for upstream derived records referenced during computation.                                    |
| `_created_at`         | `TIMESTAMPTZ`    | Record creation timestamp.                                                                                         |
| `_updated_at`         | `TIMESTAMPTZ`    | Record last update timestamp.                                                                                      |

## Use Cases

* Building the complete DEX pool registry for routing and analytics
* Filtering pools by fee, type, or token pair
* Integrating with reserves, price, and swap datasets for liquidity intelligence
* MEV routing, arbitrage path optimization, and chain-wide pool analytics
* Constructing pool-level AI or quantitative features

## Related Datasets

<CardGroup>
  <Card title="Liquidity Pools Reserves" icon="database" href="/data-catalog/evm/reserves/liquidity-pools-reserves">
    Per-block reserve snapshots for these pools.
  </Card>

  <Card title="Liquidity Pools Fee Terms" icon="percent" href="/data-catalog/evm/entities/liquidity-pools-fee-terms">
    Dynamic fee configurations per pool.
  </Card>

  <Card title="Swap Fees" icon="arrow-right-arrow-left" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
    Per-swap fee revenue across these pools.
  </Card>
</CardGroup>


# Liquidity Pool Fee Terms
Source: https://docs.blockdb.io/data-catalog/evm/entities/liquidity-pools-fee-terms

Time-versioned AMM pool fee configuration — LP, protocol & extra splits. Ethereum & EVM chains. REST API.

## Overview

* **Dataset ID:** `0212`
* **Table:** `blockdb_evm.b0212_liquidity_pools_fee_terms_v1`
* **Description:** Per-pool fee configuration (total fee + split between user/LP, protocol, and extra recipients).
* **Primary key:** `(pool_uid, block_number, tx_index, log_index)`
* **Foreign Key:** `pool_uid` → `blockdb_evm.b0211_liquidity_pools_v1(pool_uid)`
* **API:** [POST /evm/entities/pools/fee-terms](/api-reference/evm/entities/fee-terms)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Fee-Terms-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0212_liquidity_pools_fee_terms_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Fee-Terms-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0212_liquidity_pools_fee_terms_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

<Info>
  Fee terms are derived from pool metadata (e.g., pool type configuration) rather than parsed from swap logs. Use these terms to split swap fees into user/LP, protocol, and extra destinations.
</Info>

## Columns

| Column                | Type             | Description                                                                                 |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`          | Pool identifier; join to `blockdb_evm.b0211_liquidity_pools_v1`.                            |
| `exchange_id`         | `INTEGER`        | Exchange identifier.                                                                        |
| `type_id`             | `INTEGER`        | Pool type identifier.                                                                       |
| `block_number`        | `BIGINT`         | Block height where the fee-terms change was recognized/anchored.                            |
| `block_time`          | `TIMESTAMPTZ`    | UTC timestamp of the block.                                                                 |
| `tx_index`            | `INTEGER`        | Transaction index within `block_number`.                                                    |
| `log_index`           | `INTEGER`        | Log index within `tx_index`.                                                                |
| `total_fee`           | `NUMERIC(18,18)` | Total fee fraction (e.g., `0.003` = 0.30%). Nullable when unavailable.                      |
| `user_fee`            | `NUMERIC(18,18)` | Absolute fee fraction allocated to users/LPs (same units as `total_fee`). Nullable.         |
| `protocol_fee`        | `NUMERIC(18,18)` | Absolute fee fraction allocated to protocol/treasury (same units as `total_fee`). Nullable. |
| `extra_fee`           | `NUMERIC(18,18)` | Absolute fee fraction allocated to other destinations (burn, staking, etc.). Nullable.      |
| `_tracing_id`         | `BYTEA`          | Deterministic BlockDB lineage identifier for the fee-terms record.                          |
| `_parent_tracing_ids` | `BYTEA[]`        | Tracing IDs for upstream derived records referenced during computation.                     |
| `_created_at`         | `TIMESTAMPTZ`    | Record creation timestamp.                                                                  |
| `_updated_at`         | `TIMESTAMPTZ`    | Record update timestamp.                                                                    |

## Use Cases

* Fee tier discovery and pool classification
* Protocol revenue attribution vs LP/user revenue
* Normalizing fee splits across heterogeneous AMM designs
* Inputs into pool-level yield/ROI forecasting

## Related Datasets

<CardGroup>
  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pool registry this fee config belongs to.
  </Card>

  <Card title="Swap Fees" icon="arrow-right-arrow-left" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
    Per-swap fee amounts earned by each pool.
  </Card>

  <Card title="Liquidity Pools Yields" icon="chart-line" href="/data-catalog/evm/yields/liquidity-pools-yields">
    Forward-looking yield windows derived from fees.
  </Card>
</CardGroup>


# Flash Loan Prints
Source: https://docs.blockdb.io/data-catalog/evm/flash-loans/flash-loan-prints

Flash loan borrow and repay events across Uniswap-style and Balancer Vault sources.

## Overview

* **Dataset ID:** `0305`
* **Table:** `blockdb_evm.b0305_flash_loan_prints_v1`
* **Description:** One row per borrowed token per on-chain flash loan event (V2-style flash swap, V3 Flash event, Balancer V2 Vault, etc.). `pool_uid` is NULL for vault-level events not tied to a single pool.
* **Primary key:** `(block_number, tx_index, log_index, token)`
* **API:** [POST /evm/flash-loans/prints](/api-reference/evm/flash-loans/flash-loan-prints)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Flash-Loan-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0305_flash_loan_prints_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Flash-Loan-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0305_flash_loan_prints_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type            | Description                                                |
| --------------------- | --------------- | ---------------------------------------------------------- |
| `pool_uid`            | `BYTEA`         | 32B pool id when pool-scoped; NULL for vault-level events. |
| `exchange_id`         | `INTEGER`       | Exchange id when `pool_uid` set; NULL otherwise.           |
| `type_id`             | `INTEGER`       | Pool type id when `pool_uid` set; NULL otherwise.          |
| `block_number`        | `BIGINT`        | Block of the event.                                        |
| `block_time`          | `TIMESTAMPTZ`   | Block time.                                                |
| `tx_index`            | `INTEGER`       | Transaction index.                                         |
| `log_index`           | `INTEGER`       | Log index.                                                 |
| `flash_loan_source`   | `BYTEA`         | 20B emitter (pool or vault contract).                      |
| `token`               | `BYTEA`         | 20B borrowed token for this row.                           |
| `amount_borrowed`     | `NUMERIC(78,0)` | Raw borrowed amount.                                       |
| `amount_repaid`       | `NUMERIC(78,0)` | Raw repaid amount (includes fee).                          |
| `fee_amount`          | `NUMERIC(78,0)` | `amount_repaid - amount_borrowed` (raw).                   |
| `_tracing_id`         | `BYTEA`         | Unique tracing ID.                                         |
| `_parent_tracing_ids` | `BYTEA[]`       | Parent tracing IDs.                                        |
| `_created_at`         | `TIMESTAMPTZ`   | Record creation timestamp.                                 |
| `_updated_at`         | `TIMESTAMPTZ`   | Record update timestamp.                                   |

## Related datasets

<Card title="Swap fees" icon="coins" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
  Fee accounting on directional swaps.
</Card>


# Token-to-Fiat VWAP (USD)
Source: https://docs.blockdb.io/data-catalog/evm/prices/token-to-fiat-vwap

Token-to-USD volume-weighted average price in fixed time buckets, derived from cross-pool token-to-token VWAP via stablecoin anchoring.

## Overview

* **Dataset ID:** `0605`
* **Table:** `blockdb_evm.b0605_token_to_fiat_vwap`
* **Description:** Token-to-USD VWAP (1m..1d) per token, derived from cross-pool token-to-token VWAP (`b0505`) via stablecoin anchoring.
* **Primary key:** `(token_address, bucket_start, bucket_seconds)` — one USD VWAP bar per token, bucket start, and bucket size (idempotent).
* **Unique:** `_tracing_id`
* **API:** [POST /evm/prices/spot/fiat/vwap](/api-reference/evm/prices/fiat/prices-spot-vwap-fiat)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-To-Fiat-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0605_token_to_fiat_vwap_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-To-Fiat-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0605_token_to_fiat_vwap_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type             | Description                                                                                                    |
| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `first_block_number`  | `BIGINT`         | Block of the first contributing event.                                                                         |
| `first_block_time`    | `TIMESTAMPTZ`    | Time of the first contributing event.                                                                          |
| `first_tx_index`      | `INTEGER`        | `tx_index` of the first contributing event.                                                                    |
| `first_log_index`     | `INTEGER`        | `log_index` of the first contributing event.                                                                   |
| `last_block_number`   | `BIGINT`         | Block of the last contributing event.                                                                          |
| `last_block_time`     | `TIMESTAMPTZ`    | Time of the last contributing event.                                                                           |
| `last_tx_index`       | `INTEGER`        | `tx_index` of the last contributing event.                                                                     |
| `last_log_index`      | `INTEGER`        | `log_index` of the last contributing event.                                                                    |
| `bucket_start`        | `TIMESTAMPTZ`    | Inclusive UTC start of the VWAP bucket.                                                                        |
| `bucket_seconds`      | `INTEGER`        | Bucket width in seconds; must be one of `60`, `300`, `900`, `1800`, `3600`, `14400`, `86400`.                  |
| `token_address`       | `BYTEA`          | ERC-20 token address (20 bytes); references the ERC-20 token registry.                                         |
| `price_usd`           | `NUMERIC(78,18)` | VWAP in USD for the bucket.                                                                                    |
| `total_notional_usd`  | `NUMERIC(78,18)` | Total notional USD used in the VWAP weighting.                                                                 |
| `hops`                | `INTEGER`        | Minimum hop count from the stablecoin anchor via `b0505` edges.                                                |
| `sources_count`       | `INTEGER`        | Number of cross-pool pair edges (`b0505` rows) used in the hop chain.                                          |
| `_tracing_id`         | `BYTEA`          | BlockDB tracing ID for the row (unique).                                                                       |
| `_parent_tracing_ids` | `BYTEA[]`        | Tracing IDs of upstream / contributing `b0505` records; column is non-null (PostgreSQL empty array when none). |
| `_created_at`         | `TIMESTAMPTZ`    | Record creation timestamp.                                                                                     |
| `_updated_at`         | `TIMESTAMPTZ`    | Record last update timestamp.                                                                                  |

## Constraints

* **`ck_b0605_bucket_size_allowed`:** `bucket_seconds` ∈ `{60, 300, 900, 1800, 3600, 14400, 86400}`.
* **`uq_b0605_token_to_fiat_vwap_tracing_id`:** `_tracing_id` is unique.
* **`pk_b0605_token_fiat_bucket`:** primary key on `(token_address, bucket_start, bucket_seconds)`.

## Related datasets

<CardGroup>
  <Card title="Cross-Pool Token-to-Token VWAP" icon="chart-line" href="/data-catalog/evm/prices/token-to-token-cross-pool-vwap">
    Cross-venue VWAP that feeds USD anchoring.
  </Card>

  <Card title="Liquidity Pool TVL USD" icon="dollar-sign" href="/data-catalog/evm/tvl/liquidity-pools-tvl-usd">
    USD TVL computed from reserves x this price feed.
  </Card>
</CardGroup>


# Token-to-Token Prices OHLC
Source: https://docs.blockdb.io/data-catalog/evm/prices/token-to-token-prices-ohlc

Onchain OHLCV bars (1 min-1 day) from AMM swap events. Direction-consistent across 10 EVM chains.

## Overview

* **Dataset ID:** `0404`
* **Table:** `blockdb_evm.b0404_token_to_token_prices_ohlc_v1`
* **Description:** Time-bucketed OHLC bars (1m..1d) per pool and token pair direction.
* **Primary key:** `(bucket_start, bucket_seconds, pool_uid, token_in, token_out)`
* **API:** [POST /evm/prices/spot/crypto/ohlc](/api-reference/evm/prices/crypto/prices-spot-ohlc)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-OHLC-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0404_token_to_token_prices_ohlc_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-OHLC-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0404_token_to_token_prices_ohlc_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type             | Description                                                            |
| --------------------- | ---------------- | ---------------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`          | Pool identifier; FK → `b0211_liquidity_pools_v1.pool_uid`.             |
| `exchange_id`         | `INTEGER`        | Exchange identifier.                                                   |
| `type_id`             | `INTEGER`        | Pool type identifier.                                                  |
| `bucket_start`        | `TIMESTAMPTZ`    | Inclusive UTC bucket start.                                            |
| `bucket_end`          | `TIMESTAMPTZ`    | Exclusive UTC bucket end; equals `bucket_start + bucket_seconds`.      |
| `bucket_seconds`      | `INTEGER`        | `60`, `300`, `900`, `1800`, `3600`, `14400`, or `86400`.               |
| `token_in`            | `BYTEA`          | Input token (20B); FK → `b0201_erc20_tokens_v1`.                       |
| `token_out`           | `BYTEA`          | Output token (20B); FK → `b0201_erc20_tokens_v1`.                      |
| `open`                | `NUMERIC(78,18)` | Opening price (token\_out per 1 token\_in, decimals-adjusted).         |
| `high`                | `NUMERIC(78,18)` | High price in bucket.                                                  |
| `low`                 | `NUMERIC(78,18)` | Low price in bucket.                                                   |
| `close`               | `NUMERIC(78,18)` | Closing price in bucket.                                               |
| `volume_in_raw`       | `NUMERIC(78,0)`  | Sum of raw UInt256 `amountIn` values (`0` for carry-forward buckets).  |
| `volume_in`           | `NUMERIC(78,18)` | Decimal-adjusted `token_in` volume; `NULL` if decimals unknown.        |
| `volume_out_raw`      | `NUMERIC(78,0)`  | Sum of raw UInt256 `amountOut` values (`0` for carry-forward buckets). |
| `volume_out`          | `NUMERIC(78,18)` | Decimal-adjusted `token_out` volume; `NULL` if decimals unknown.       |
| `trades_count`        | `BIGINT`         | Trade count in bucket.                                                 |
| `_tracing_id`         | `BYTEA`          | BlockDB tracing ID; unique.                                            |
| `_parent_tracing_ids` | `BYTEA[]`        | Tracing IDs of contributing swap prints; optional.                     |
| `_created_at`         | `TIMESTAMPTZ`    | Record creation time.                                                  |
| `_updated_at`         | `TIMESTAMPTZ`    | Record last update time.                                               |

## Related datasets

<CardGroup>
  <Card title="Token-to-Token VWAP" icon="chart-line" href="/data-catalog/evm/prices/token-to-token-vwap">
    Volume-weighted benchmarks at matching intervals.
  </Card>

  <Card title="Swap prints" icon="arrows-left-right" href="/data-catalog/evm/prices/token-to-token-prices-swap-prints">
    Per-swap executions that aggregate into OHLC.
  </Card>
</CardGroup>


# Token-to-Token Prices Swap Prints
Source: https://docs.blockdb.io/data-catalog/evm/prices/token-to-token-prices-swap-prints

Onchain swap execution prices — realized token_in → token_out price & sizes per swap event. 10 EVM chains.

## Overview

* **Dataset ID:** `0302`
* **Table:** `blockdb_evm.b0302_token_to_token_prices_swap_prints_v1`
* **Description:** Executed swap prints (realized token\_in → token\_out price & sizes) per on-chain swap event.
* **Primary key:** `(pool_uid, token_in, token_out, block_number, tx_index, log_index)`
* **API:** [POST /evm/prices/spot/crypto/prints](/api-reference/evm/prices/crypto/prices-spot-prints)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0302_token_to_token_prices_swap_prints_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Prints-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0302_token_to_token_prices_swap_prints_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type             | Description                                                                                                    |
| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`          | Pool identifier; FK → `b0211_liquidity_pools_v1.pool_uid`.                                                     |
| `exchange_id`         | `INTEGER`        | Exchange identifier.                                                                                           |
| `type_id`             | `INTEGER`        | Pool type identifier.                                                                                          |
| `block_number`        | `BIGINT`         | Block of the swap event.                                                                                       |
| `block_time`          | `TIMESTAMPTZ`    | Block time.                                                                                                    |
| `tx_index`            | `INTEGER`        | Transaction index in block.                                                                                    |
| `log_index`           | `INTEGER`        | Log index in receipt.                                                                                          |
| `token_in`            | `BYTEA`          | Input token (20B).                                                                                             |
| `token_out`           | `BYTEA`          | Output token (20B).                                                                                            |
| `amount_in_raw`       | `NUMERIC(78,0)`  | Amount of token\_in (raw units).                                                                               |
| `amount_out_raw`      | `NUMERIC(78,0)`  | Amount of token\_out (raw units).                                                                              |
| `exec_price`          | `NUMERIC(78,18)` | Realized price: token\_out per 1 token\_in (decimals-adjusted); nullable for extreme cases per pipeline rules. |
| `_tracing_id`         | `BYTEA`          | BlockDB tracing ID; unique.                                                                                    |
| `_parent_tracing_ids` | `BYTEA[]`        | Parent tracing IDs.                                                                                            |
| `_created_at`         | `TIMESTAMPTZ`    | Record creation time.                                                                                          |
| `_updated_at`         | `TIMESTAMPTZ`    | Record last update time.                                                                                       |

## Related datasets

<CardGroup>
  <Card title="OHLC" icon="chart-candlestick" href="/data-catalog/evm/prices/token-to-token-prices-ohlc">
    Time-bucketed bars built from swap activity.
  </Card>

  <Card title="Swap fees" icon="coins" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
    Fee accounting for the same swap events.
  </Card>
</CardGroup>


# Token-to-Token VWAP
Source: https://docs.blockdb.io/data-catalog/evm/prices/token-to-token-vwap

Volume-weighted average cryptocurrency prices (1 min-1 day) from on-chain AMM swaps. 10 EVM chains.

## Overview

* **Dataset ID:** `0405`
* **Table:** `blockdb_evm.b0405_token_to_token_vwap_v1`
* **Description:** Volume-weighted average price (1m..1d) per pool and token pair direction.
* **Primary key:** `(bucket_start, bucket_seconds, pool_uid, token_in, token_out)`
* **API:** [POST /evm/prices/spot/crypto/vwap](/api-reference/evm/prices/crypto/prices-spot-vwap)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0405_token_to_token_vwap_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Prices-VWAP-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0405_token_to_token_vwap_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                 | Type             | Description                                                                |
| ---------------------- | ---------------- | -------------------------------------------------------------------------- |
| `pool_uid`             | `BYTEA`          | Pool identifier; FK → `b0211_liquidity_pools_v1.pool_uid`.                 |
| `exchange_id`          | `INTEGER`        | Exchange identifier.                                                       |
| `type_id`              | `INTEGER`        | Pool type identifier.                                                      |
| `bucket_start`         | `TIMESTAMPTZ`    | Inclusive UTC bucket start.                                                |
| `bucket_end`           | `TIMESTAMPTZ`    | Exclusive UTC bucket end; equals `bucket_start + bucket_seconds`.          |
| `bucket_seconds`       | `INTEGER`        | `60`, `300`, `900`, `1800`, `3600`, `14400`, or `86400`.                   |
| `token_in`             | `BYTEA`          | Input token (20B); FK → `b0201_erc20_tokens_v1`.                           |
| `token_out`            | `BYTEA`          | Output token (20B); FK → `b0201_erc20_tokens_v1`.                          |
| `price_vwap`           | `NUMERIC(78,18)` | VWAP (token\_out per 1 token\_in, decimals-adjusted); `NULL` if undefined. |
| `total_volume_in_raw`  | `NUMERIC(78,0)`  | Sum of raw UInt256 `amountIn` values.                                      |
| `total_volume_in`      | `NUMERIC(78,18)` | Decimal-adjusted `token_in` volume; `NULL` if decimals unknown.            |
| `total_volume_out_raw` | `NUMERIC(78,0)`  | Sum of raw UInt256 `amountOut` values.                                     |
| `total_volume_out`     | `NUMERIC(78,18)` | Decimal-adjusted `token_out` volume; `NULL` if decimals unknown.           |
| `trade_count`          | `BIGINT`         | Number of swaps in the bucket.                                             |
| `_tracing_id`          | `BYTEA`          | BlockDB tracing ID; unique.                                                |
| `_parent_tracing_ids`  | `BYTEA[]`        | Tracing IDs of contributing swap prints; optional.                         |
| `_created_at`          | `TIMESTAMPTZ`    | Record creation time.                                                      |
| `_updated_at`          | `TIMESTAMPTZ`    | Record last update time.                                                   |

## Related datasets

<CardGroup>
  <Card title="Token-to-Token OHLC" icon="chart-candlestick" href="/data-catalog/evm/prices/token-to-token-prices-ohlc">
    OHLC bars for the same directional pairs.
  </Card>

  <Card title="Token-to-USD VWAP" icon="dollar-sign" href="/data-catalog/evm/prices/token-to-fiat-vwap">
    USD VWAP derived from token-to-token VWAP via stablecoin anchoring.
  </Card>
</CardGroup>


# Blocks
Source: https://docs.blockdb.io/data-catalog/evm/primitives/blocks

Complete Ethereum & EVM block header data via REST API — block hash, gas, miner, timestamps. Historical and real-time, 10 chains.

## Overview

* **Dataset ID:** `0101`
* **Table:** `blockdb_evm.b0101_blocks_v1`
* **Description:** Canonical block headers with BlockDB integrity metadata
* **Primary key:** `block_number`
* **API:** [POST /evm/raw/blocks](/api-reference/evm/primitives/blocks)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0101_blocks_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                            | Type          | Description                                                    |
| --------------------------------- | ------------- | -------------------------------------------------------------- |
| `block_number`                    | `BIGINT`      | Monotonic block height (chain-local). Primary key.             |
| `block_hash`                      | `BYTEA`       | 32B Keccak block hash.                                         |
| `parent_block_hash`               | `BYTEA`       | 32B hash of the parent block.                                  |
| `receipt_root`                    | `BYTEA`       | 32B receipts trie root from block header.                      |
| `miner`                           | `BYTEA`       | 20B fee recipient (coinbase) address.                          |
| `gas_limit`                       | `BIGINT`      | Block gas limit.                                               |
| `extra_data`                      | `BYTEA`       | Up to 32B extra data from header.                              |
| `size`                            | `BIGINT`      | Encoded block size (bytes).                                    |
| `timestamp_utc`                   | `TIMESTAMPTZ` | Block timestamp as `timestamptz` (UTC, microsecond precision). |
| `_tracing_id`                     | `BYTEA`       | BlockDB tracing ID; unique.                                    |
| `_computed_receipt_root`          | `BYTEA`       | Recomputed receipts root (BlockDB integrity check).            |
| `_computed_receipt_timestamp_utc` | `TIMESTAMPTZ` | UTC timestamp when receipts root was (re)computed.             |
| `_created_at`                     | `TIMESTAMPTZ` | Record creation timestamp.                                     |
| `_updated_at`                     | `TIMESTAMPTZ` | Record last update timestamp.                                  |

## Use Cases

* Chain reconstruction and blockchain state verification
* Block production and mining analytics
* Gas market analysis and block space utilization
* Chain reorganization detection and handling
* Foundation for transaction and log indexing
* Block-level time series analysis and chain health monitoring

## Related Datasets

<CardGroup>
  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    EVM transaction records with gas, status, and calldata.
  </Card>

  <Card title="Logs" icon="list" href="/data-catalog/evm/primitives/logs">
    Smart contract event logs tied to each block.
  </Card>

  <Card title="Internal Transactions" icon="sitemap" href="/data-catalog/evm/primitives/internal-transactions">
    Nested calls and value flows within transactions.
  </Card>
</CardGroup>


# Contracts
Source: https://docs.blockdb.io/data-catalog/evm/primitives/contracts

Canonical smart contract deployment registry for Ethereum & EVM — CREATE/CREATE2 discovery, deployer address, block. REST API.

## Overview

* **Dataset ID:** `0121`
* **Table:** `blockdb_evm.b0121_contracts_v1`
* **Description:** Smart contracts discovered via CREATE/CREATE2 internal transactions. Uses `contract_id` (26 bytes = address + creation\_block + tx\_index) as primary key to support metamorphic contracts (e.g. CREATE-SELFDESTRUCT-CREATE2 in the same block).
* **Primary key:** `contract_id`
* **Foreign Key:** `(block_number, tx_index)` → `blockdb_evm.b0102_transactions_v1`
* **API:** [POST /evm/raw/contracts](/api-reference/evm/primitives/contracts)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Contracts-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0121_contracts_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Contracts-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0121_contracts_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column               | Type          | Description                                                                                                                               |
| -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `contract_id`        | `BYTEA`       | Unique contract incarnation ID: 20 bytes (address) + 4 bytes (creation block, big-endian) + 2 bytes (tx\_index, big-endian). Primary key. |
| `contract_address`   | `BYTEA`       | The deployed contract address (20 bytes). Separate column for efficient API lookups.                                                      |
| `block_number`       | `BIGINT`      | Block number where contract was deployed.                                                                                                 |
| `block_time`         | `TIMESTAMPTZ` | UTC timestamp of the block.                                                                                                               |
| `tx_index`           | `INTEGER`     | Transaction index within the block.                                                                                                       |
| `trace_address`      | `TEXT`        | Position in call tree (e.g., "0", "0.0", "0.1.2").                                                                                        |
| `creator_address`    | `BYTEA`       | Address that deployed the contract (msg.sender of CREATE/CREATE2).                                                                        |
| `creation_call_type` | `TEXT`        | Type of creation: CREATE or CREATE2.                                                                                                      |
| `_tracing_id`        | `BYTEA`       | Internal tracing identifier for lineage tracking.                                                                                         |
| `_created_at`        | `TIMESTAMPTZ` | Record creation timestamp.                                                                                                                |
| `_updated_at`        | `TIMESTAMPTZ` | Record last update timestamp.                                                                                                             |

## Use Cases

* Contract registry and address validation
* Deployment tracking and contract lifecycle analysis
* Factory pattern analysis and contract creation patterns
* Security research and contract classification
* Integration with contract metadata and ABI databases
* Foundation for contract interaction analysis

## Related Datasets

<CardGroup>
  <Card title="Function Results" icon="brackets-curly" href="/data-catalog/evm/primitives/function-results">
    Read-call results from contract view functions.
  </Card>

  <Card title="Internal Transactions" icon="sitemap" href="/data-catalog/evm/primitives/internal-transactions">
    Calls targeting these contract addresses.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    Deployment and interaction transactions.
  </Card>
</CardGroup>


# Function Results
Source: https://docs.blockdb.io/data-catalog/evm/primitives/function-results

Block-versioned on-chain view function outputs — token metadata, oracle values. Time-travel queries over any contract state.

## Overview

* **Dataset ID:** `0122`
* **Table:** `blockdb_evm.b0122_function_results_v1`
* **Description:** On-chain function call return values versioned by block. Uses `contract_id` (26 bytes) to support metamorphic contracts; primary key is `(contract_id, block_number, call_data)`.
* **Primary key:** `(contract_id, block_number, call_data)`
* **API:** [POST /evm/raw/function-results](/api-reference/evm/primitives/function-results)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Function-Results-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0122_function_results_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Function-Results-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0122_function_results_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column           | Type          | Description                                                                                                                               |
| ---------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `contract_id`    | `BYTEA`       | Unique contract incarnation ID: 20 bytes (address) + 4 bytes (creation block BE) + 2 bytes (tx\_index BE). Links to `b0121_contracts_v1`. |
| `block_number`   | `BIGINT`      | Block at which the value was read.                                                                                                        |
| `block_time`     | `TIMESTAMPTZ` | UTC timestamp of the block.                                                                                                               |
| `call_data`      | `BYTEA`       | Raw call data used to invoke the function.                                                                                                |
| `signature_hash` | `BYTEA`       | 4-byte selector (keccak256(signature)\[0..3]).                                                                                            |
| `result`         | `BYTEA`       | Raw return data from the function call (null if reverted).                                                                                |
| `timestamp_utc`  | `TIMESTAMPTZ` | UTC timestamp when the function call result was recorded.                                                                                 |
| `_tracing_id`    | `BYTEA`       | Tracing ID of the genesis tx record.                                                                                                      |
| `_created_at`    | `TIMESTAMPTZ` | Record creation timestamp.                                                                                                                |
| `_updated_at`    | `TIMESTAMPTZ` | Record last update timestamp.                                                                                                             |

## Use Cases

* Historical state reconstruction and time-travel queries
* Token metadata and balance lookups at specific blocks
* Contract configuration and parameter tracking over time
* Price oracle and external data feed analysis
* Governance proposal and voting state tracking
* Historical analytics requiring point-in-time contract state

## Related Datasets

<CardGroup>
  <Card title="Contracts" icon="file-code" href="/data-catalog/evm/primitives/contracts">
    Deployment metadata for the queried contracts.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    Transactions that triggered these read calls.
  </Card>

  <Card title="Logs" icon="list" href="/data-catalog/evm/primitives/logs">
    Events emitted alongside function invocations.
  </Card>
</CardGroup>


# Internal Transactions
Source: https://docs.blockdb.io/data-catalog/evm/primitives/internal-transactions

Full EVM call-trace data — internal ETH transfers, CREATE/DELEGATECALL, MEV path reconstruction. 10 chains, REST API.

## Overview

* **Dataset ID:** `0111`
* **Table:** `blockdb_evm.b0111_internal_transactions_v1`
* **Description:** Internal transactions (call traces) from `debug_traceTransaction`
* **Primary key:** `(block_number, tx_index, trace_address)`
* **Unique:** `_tracing_id`
* **Foreign key:** `(block_number, tx_index)` → `blockdb_evm.b0102_transactions_v1`
* **API:** [POST /evm/raw/internal-transactions](/api-reference/evm/primitives/internal-transactions)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Internal-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0111_internal_transactions_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Internal-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0111_internal_transactions_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column          | Type          | Description                                                                         |
| --------------- | ------------- | ----------------------------------------------------------------------------------- |
| `block_number`  | `BIGINT`      | Block number of the parent transaction.                                             |
| `block_time`    | `TIMESTAMPTZ` | UTC timestamp of the block.                                                         |
| `tx_index`      | `INTEGER`     | Zero-based index of the parent transaction within the block.                        |
| `trace_address` | `TEXT`        | Position in the call tree (e.g., "0", "0.0", "0.1").                                |
| `call_type`     | `TEXT`        | The type of call: CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2.                  |
| `from_address`  | `BYTEA`       | The address of the caller (20 bytes, enforced).                                     |
| `to_address`    | `BYTEA`       | The address of the callee; null for failed CREATE/CREATE2 (when present, 20 bytes). |
| `value_wei`     | `NUMERIC`     | The native value (in wei) transferred in this call; non-negative.                   |
| `gas`           | `NUMERIC`     | The gas allocated for this call (optional; non-negative when set).                  |
| `gas_used`      | `NUMERIC`     | The gas actually consumed by this call (optional; non-negative when set).           |
| `input`         | `BYTEA`       | The input data (calldata) for this call (optional).                                 |
| `output`        | `BYTEA`       | The return data from the call (optional; if enabled, null = reverted).              |
| `error`         | `TEXT`        | The error message if the call reverted.                                             |
| `tx_success`    | `BOOLEAN`     | The success of the underlying transaction that caused this internal transaction.    |
| `_tracing_id`   | `BYTEA`       | Internal tracing ID for observability (unique).                                     |
| `_created_at`   | `TIMESTAMPTZ` | Record creation timestamp.                                                          |
| `_updated_at`   | `TIMESTAMPTZ` | Record last update timestamp.                                                       |

## Use Cases

* Contract creation and factory flow analysis
* Internal call graphs and cross-contract dependencies
* Value flow and gas consumption per call
* Debugging failed transactions and revert reasons
* MEV and arbitrage path reconstruction

## Related Datasets

<CardGroup>
  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    Top-level transactions that spawned these calls.
  </Card>

  <Card title="Contracts" icon="file-code" href="/data-catalog/evm/primitives/contracts">
    Contract metadata for the callee addresses.
  </Card>

  <Card title="Logs" icon="list" href="/data-catalog/evm/primitives/logs">
    Events emitted during the same transaction context.
  </Card>
</CardGroup>


# Logs
Source: https://docs.blockdb.io/data-catalog/evm/primitives/logs

Every smart contract event log across Ethereum & EVM chains — RLP-verified. The source for DeFi, NFT, and token analytics.

## Overview

* **Dataset ID:** `0103`
* **Table:** `blockdb_evm.b0103_logs_v1`
* **Description:** Event logs emitted by contract transactions
* **Primary key:** `(block_number, tx_index, log_index)`
* **API:** [POST /evm/raw/logs](/api-reference/evm/primitives/logs)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Logs-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0103_logs_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Logs-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0103_logs_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column             | Type          | Description                                                                                       |
| ------------------ | ------------- | ------------------------------------------------------------------------------------------------- |
| `block_number`     | `BIGINT`      | Block height containing this log.                                                                 |
| `block_time`       | `TIMESTAMPTZ` | UTC timestamp of the block.                                                                       |
| `tx_index`         | `INTEGER`     | Zero-based transaction index within the block.                                                    |
| `log_index`        | `INTEGER`     | Position of the log within the transaction; indirectly verified by RLP (All logs must be present) |
| `contract_address` | `BYTEA`       | Address of the contract that emitted the log (20 bytes); directly verified by RLP                 |
| `topic_zero`       | `BYTEA`       | Primary topic hash identifying the event type (32 bytes); directly verified by RLP                |
| `data_topics`      | `BYTEA[]`     | Optional raw concatenation of topics\[1..n] (implementation detail); directly verified by RLP     |
| `data`             | `BYTEA`       | Raw event data; directly verified by RLP                                                          |
| `_tracing_id`      | `BYTEA`       | Tracing ID of the genesis log record.                                                             |
| `_created_at`      | `TIMESTAMPTZ` | Record creation timestamp.                                                                        |
| `_updated_at`      | `TIMESTAMPTZ` | Record last update timestamp.                                                                     |

## Use Cases

* DeFi protocol event tracking (swaps, transfers, mints, burns)
* Token transfer and balance change monitoring
* Smart contract interaction analysis
* Event-driven analytics and alerting systems
* Protocol state reconstruction from events
* Cross-contract event correlation and analysis

## Related Datasets

<CardGroup>
  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    Parent transactions that emitted these logs.
  </Card>

  <Card title="Token Transfers" icon="coins" href="/data-catalog/evm/transfers/token-transfers">
    Transfer events decoded from ERC-20/721/1155 logs.
  </Card>

  <Card title="ERC-20 Tokens" icon="circle-dollar-to-slot" href="/data-catalog/evm/entities/erc20-tokens">
    Token metadata for contracts appearing in logs.
  </Card>
</CardGroup>


# Transactions
Source: https://docs.blockdb.io/data-catalog/evm/primitives/transactions

Full EVM transaction data — sender, gas, calldata, EIP-1559 fields. Historical and real-time across 10 chains via REST API.

## Overview

* **Dataset ID:** `0102`
* **Table:** `blockdb_evm.b0102_transactions_v1`
* **Description:** Transactions included in blocks
* **Primary key:** `tx_hash`
* **API:** [POST /evm/raw/transactions](/api-reference/evm/primitives/transactions)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0102_transactions_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Raw-Transactions-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0102_transactions_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                         | Type          | Description                                                                     |
| ------------------------------ | ------------- | ------------------------------------------------------------------------------- |
| `tx_hash`                      | `BYTEA`       | Keccak-256 hash of the transaction (32 bytes)                                   |
| `from_address`                 | `BYTEA`       | Sender address (20 bytes)                                                       |
| `to_address`                   | `BYTEA`       | Recipient address (null for contract creation, 20 bytes if present)             |
| `block_number`                 | `BIGINT`      | Block height containing this transaction.                                       |
| `block_time`                   | `TIMESTAMPTZ` | UTC timestamp of the block.                                                     |
| `tx_index`                     | `INTEGER`     | Zero-based index of the transaction within the block; directly verified by RLP. |
| `created_contract_address`     | `BYTEA`       | Contract address created by this transaction (20 bytes); null for non-creation. |
| `gas_used`                     | `NUMERIC(78)` | Gas consumed by this transaction.                                               |
| `effective_gas_price_wei`      | `NUMERIC(78)` | Effective gas price paid in wei.                                                |
| `status_success`               | `BOOLEAN`     | Execution status: TRUE if successful, FALSE if reverted.                        |
| `root`                         | `BYTEA`       | Pre-Byzantium: state root (32 bytes) after tx execution; NULL for Byzantium+.   |
| `tx_type`                      | `SMALLINT`    | Type of transaction (e.g., 2=EIP-1559, 1=legacy).                               |
| `trace_failed`                 | `BOOLEAN`     | TRUE if trace failed, FALSE if succeeded, NULL if trace not available.          |
| `value_wei`                    | `NUMERIC`     | Value transferred in wei.                                                       |
| `input`                        | `BYTEA`       | Calldata sent with the transaction.                                             |
| `nonce`                        | `BIGINT`      | Sender nonce.                                                                   |
| `gas_limit`                    | `NUMERIC`     | Gas limit provided by the sender.                                               |
| `gas_price_wei`                | `NUMERIC`     | Gas price in wei (legacy).                                                      |
| `max_fee_per_gas_wei`          | `NUMERIC`     | Max fee per gas (EIP-1559).                                                     |
| `max_priority_fee_per_gas_wei` | `NUMERIC`     | Max priority fee per gas (EIP-1559).                                            |
| `_tracing_id`                  | `BYTEA`       | Tracing ID of the genesis tx record.                                            |
| `_created_at`                  | `TIMESTAMPTZ` | Record creation timestamp.                                                      |
| `_updated_at`                  | `TIMESTAMPTZ` | Record last update timestamp.                                                   |

## Use Cases

* Transaction flow analysis and wallet tracking
* Gas fee analytics and EIP-1559 impact studies
* Contract deployment and creation tracking
* Failed transaction analysis and debugging
* MEV and arbitrage transaction identification
* Cross-chain transaction pattern analysis

## Related Datasets

<CardGroup>
  <Card title="Blocks" icon="cube" href="/data-catalog/evm/primitives/blocks">
    Block headers that contain these transactions.
  </Card>

  <Card title="Logs" icon="list" href="/data-catalog/evm/primitives/logs">
    Smart contract events emitted by transactions.
  </Card>

  <Card title="Internal Transactions" icon="sitemap" href="/data-catalog/evm/primitives/internal-transactions">
    Nested calls spawned within each transaction.
  </Card>
</CardGroup>


# Liquidity Pool Reserves
Source: https://docs.blockdb.io/data-catalog/evm/reserves/liquidity-pools-reserves

AMM reserve snapshots — sqrt price, current tick, token balances, optional tick/bin detail rows.

## Overview

* **Dataset ID:** `0301`
* **Tables:** `blockdb_evm.b0301_liquidity_pools_reserves_v1`, `blockdb_evm.b0301_liquidity_pools_reserves_details_v1`
* **Description:** Per-pool reserve snapshots at every on-chain event (one row per event), with optional granular tick/bin/range detail rows joined via `snapshot_id`.
* **Primary key:** `(pool_uid, block_number, tx_index, log_index)` (reserves); `(snapshot_id, tick/bin/range)` (details)
* **API:** [POST /evm/reserves](/api-reference/evm/reserves/reserves)
* **CSV Sample (reserves):** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_v1.csv?download=true)
* **CSV Sample (details):** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.csv?download=true)
* **JSON Sample (reserves):** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_v1.json?download=true)
* **JSON Sample (details):** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Snapshot columns (`blockdb_evm.b0301_liquidity_pools_reserves_v1`)

Primary key: `(pool_uid, block_number, tx_index, log_index)`.

| Column                | Type              | Description                                                   |
| --------------------- | ----------------- | ------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`           | Pool surrogate key; FK → `b0211_liquidity_pools_v1.pool_uid`. |
| `exchange_id`         | `INTEGER`         | Exchange identifier.                                          |
| `type_id`             | `INTEGER`         | Liquidity pool type identifier.                               |
| `block_number`        | `BIGINT`          | Block when this state was observed.                           |
| `block_time`          | `TIMESTAMPTZ`     | Block time.                                                   |
| `tx_index`            | `INTEGER`         | Transaction index within the block.                           |
| `log_index`           | `INTEGER`         | Log index within the transaction.                             |
| `reserves`            | `NUMERIC(78,0)[]` | Current reserves per token for even-style pools (raw units).  |
| `current_tick`        | `INTEGER`         | Current tick (concentrated liquidity, e.g. Uniswap v3).       |
| `current_sqrt_price`  | `NUMERIC(49,0)`   | Q64.96 sqrt price integer.                                    |
| `current_bin`         | `INTEGER`         | Current bin id for bin-style AMMs.                            |
| `_tracing_id`         | `BYTEA`           | BlockDB tracing ID; unique.                                   |
| `_parent_tracing_ids` | `BYTEA[]`         | Parent tracing IDs.                                           |
| `_created_at`         | `TIMESTAMPTZ`     | Record creation time.                                         |
| `_updated_at`         | `TIMESTAMPTZ`     | Record last update time.                                      |

`CHECK (ck_b0301_reserves_has_payload)` requires at least one of: `reserves`, `current_tick`, `current_bin`, or (per DDL) `liquidity_values`, `amounts0` when those columns exist in your deployed schema. The shipped DDL file references `liquidity_values` / `amounts0` in the payload check; confirm deployed columns match your environment.

## Details columns (`blockdb_evm.b0301_liquidity_pools_reserves_details_v1`)

Join: `details.snapshot_id = reserves._tracing_id`.

| Column        | Type            | Description                                    |
| ------------- | --------------- | ---------------------------------------------- |
| `snapshot_id` | `BYTEA`         | Parent snapshot `_tracing_id`.                 |
| `tick`        | `INTEGER`       | Single-tick locator (v3-style).                |
| `lower_tick`  | `INTEGER`       | Range lower bound.                             |
| `upper_tick`  | `INTEGER`       | Range upper bound.                             |
| `bin_id`      | `INTEGER`       | Single-bin locator.                            |
| `liquidity`   | `NUMERIC(38,0)` | Engine-native liquidity (e.g. Uniswap v3 (L)). |
| `amount0`     | `NUMERIC(78,0)` | Token0 raw amount at locator.                  |
| `amount1`     | `NUMERIC(78,0)` | Token1 raw amount at locator.                  |

Uniqueness: one row per `(snapshot_id, tick)`, per `(snapshot_id, bin_id)`, or per `(snapshot_id, lower_tick, upper_tick)` range.

<Note>
  **Tick range coverage:** Detail rows cover a **±1% range around the current price tick** by default. If you need a wider tick range or full tick coverage, [contact us](mailto:support@blockdb.io).
</Note>

## Use cases

* Pool state backtesting and simulation
* Liquidity distribution analysis (ticks/bins)
* TVL and pricing model inputs

## Related datasets

<CardGroup>
  <Card title="Liquidity pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pool registry keyed by `pool_uid`.
  </Card>

  <Card title="Swap fees" icon="coins" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
    Per-swap economics tied to the same pool events.
  </Card>
</CardGroup>


# Liquidity Pool Swap Fees
Source: https://docs.blockdb.io/data-catalog/evm/swaps/liquidity-pools-swap-fees

Per-swap fee accounting with LP, protocol & extra-destination splits. Historical & real-time across 10 EVM chains.

## Overview

* **Dataset ID:** `0303`
* **Table:** `blockdb_evm.b0303_liquidity_pools_swap_fees_v1`
* **Description:** Per-swap fee accounting: executed swap sizes plus computed fee amounts using the pool's fee terms (`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`).
* **Primary key:** `(pool_uid, token_in, token_out, block_number, tx_index, log_index)`
* **API:** [POST /evm/swaps/fees](/api-reference/evm/swaps/swap-fees)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0303_liquidity_pools_swap_fees_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0303_liquidity_pools_swap_fees_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Columns

| Column                | Type            | Description                                                                               |
| --------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`         | Pool identifier (internal). Join to pool metadata and fee terms.                          |
| `exchange_id`         | `INTEGER`       | Exchange/DEX identifier.                                                                  |
| `type_id`             | `INTEGER`       | Pool type identifier (FK to liquidity\_pool\_types).                                      |
| `block_number`        | `BIGINT`        | Block height where the swap was observed.                                                 |
| `block_time`          | `TIMESTAMPTZ`   | UTC timestamp of the block containing the swap event.                                     |
| `tx_index`            | `INTEGER`       | Transaction index within the block.                                                       |
| `log_index`           | `INTEGER`       | Log index within the transaction.                                                         |
| `token_in`            | `BYTEA`         | 20-byte address of the input token (direction of swap).                                   |
| `token_out`           | `BYTEA`         | 20-byte address of the output token (direction of swap).                                  |
| `fee_token`           | `BYTEA`         | 20-byte token address the fee is denominated in (must equal `token_in` or `token_out`).   |
| `amount_in`           | `NUMERIC(78,0)` | Executed input amount (raw token units).                                                  |
| `amount_out`          | `NUMERIC(78,0)` | Executed output amount (raw token units).                                                 |
| `fee_amount_total`    | `NUMERIC(78,0)` | Total fee amount in `fee_token` units (raw).                                              |
| `fee_amount_user`     | `NUMERIC(78,0)` | User/LP share of fees in `fee_token` units (nullable).                                    |
| `fee_amount_protocol` | `NUMERIC(78,0)` | Protocol share of fees in `fee_token` units (nullable).                                   |
| `fee_amount_extra`    | `NUMERIC(78,0)` | Extra destination share of fees in `fee_token` units (nullable).                          |
| `_tracing_id`         | `BYTEA`         | Deterministic BlockDB lineage identifier for the swap-fee record.                         |
| `_parent_tracing_ids` | `BYTEA[]`       | Tracing IDs for upstream derived records referenced during computation (e.g., fee terms). |
| `_created_at`         | `TIMESTAMPTZ`   | Record creation timestamp.                                                                |
| `_updated_at`         | `TIMESTAMPTZ`   | Record update timestamp.                                                                  |

## Use Cases

* Pool revenue attribution (LP vs protocol vs extra destinations)
* Backtesting fee-sensitive execution and routing strategies
* Inputs to pool yield/ROI modeling (feeds `blockdb_evm.b0411_liquidity_pools_yields_v1`)
* Monitoring fee regime changes and their downstream impacts

## Related Datasets

<CardGroup>
  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pool registry for the fee-generating venues.
  </Card>

  <Card title="Liquidity Pools Yields" icon="chart-line" href="/data-catalog/evm/yields/liquidity-pools-yields">
    Yield windows computed from these swap fees.
  </Card>

  <Card title="Swap Prints" icon="arrows-left-right" href="/data-catalog/evm/prices/token-to-token-prices-swap-prints">
    Per-swap price observations from the same events.
  </Card>
</CardGroup>


# Token Transfers
Source: https://docs.blockdb.io/data-catalog/evm/transfers/token-transfers

Unified ERC-20, ERC-721, ERC-1155 & native ETH transfers in one table. Deterministic tracing IDs, 10 EVM chains.

## Overview

* **Dataset ID:** `0304`
* **Table:** `blockdb_evm.b0304_token_transfers_v1`
* **Description:** Token transfer events (native ETH, ERC-20, ERC-721, ERC-1155) produced by TokenTransfersEngine from transactions, internal transactions, and transfer logs.
* **Primary key:** `_tracing_id`
* **Foreign Key:** `(block_number, tx_index)` → `blockdb_evm.b0102_transactions_v1`
* **API:** [POST /evm/transfers/token-transfers](/api-reference/evm/transfers/token-transfers)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Transfers-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0304_token_transfers_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Token-Transfers-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0304_token_transfers_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

## Methodology

The transfers are created for identified contract addresses that are ERC-20, ERC-721, ERC-1155 or native ETH. If the contract is not identified as one of these, the transfer is not created.

## Columns

| Column                | Type            | Description                                                                         |
| --------------------- | --------------- | ----------------------------------------------------------------------------------- |
| `block_number`        | `BIGINT`        | Block where the transfer occurred.                                                  |
| `block_time`          | `TIMESTAMPTZ`   | UTC timestamp of the block.                                                         |
| `tx_index`            | `INTEGER`       | Transaction index within the block.                                                 |
| `log_index`           | `INTEGER`       | Log index within the transaction receipt; null for native or internal tx transfers. |
| `trace_address`       | `TEXT`          | Trace address for internal tx transfers (e.g. "0", "0.1"); null for other types.    |
| `from_address`        | `BYTEA`         | Sender address (20 bytes).                                                          |
| `to_address`          | `BYTEA`         | Recipient address (20 bytes).                                                       |
| `token_address`       | `BYTEA`         | Token contract address (20 bytes); null for native ETH.                             |
| `amount_raw`          | `NUMERIC(78,0)` | Raw amount in smallest unit (wei for native, raw uint256 for ERC-20/1155).          |
| `amount_adj`          | `TEXT`          | Decimal-adjusted amount; null if decimals unknown or NFT.                           |
| `token_id`            | `NUMERIC(78,0)` | Token ID for ERC-721 and ERC-1155; null for native/ERC-20.                          |
| `transfer_type`       | `SMALLINT`      | Transfer mechanism; see [Transfer Type](/api-reference/enumerations/transfer-type). |
| `_tracing_id`         | `BYTEA`         | BlockDB lineage identifier.                                                         |
| `_parent_tracing_ids` | `BYTEA[]`       | BlockDB lineage identifiers of the parent records.                                  |
| `_created_at`         | `TIMESTAMPTZ`   | Record creation timestamp.                                                          |
| `_updated_at`         | `TIMESTAMPTZ`   | Record last update timestamp.                                                       |

## Use Cases

* Wallet balance and flow analytics
* Token movement and holder tracking
* Compliance and attribution (native + ERC-20/721/1155 in one table)
* MEV and arbitrage flow reconstruction

## Related Datasets

<CardGroup>
  <Card title="ERC-20 Tokens" icon="circle-dollar-to-slot" href="/data-catalog/evm/entities/erc20-tokens">
    Token metadata for the transferred assets.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/data-catalog/evm/primitives/transactions">
    Parent transactions containing these transfers.
  </Card>

  <Card title="Logs" icon="list" href="/data-catalog/evm/primitives/logs">
    Raw event logs that source these transfers.
  </Card>
</CardGroup>


# Liquidity Pool TVL USD
Source: https://docs.blockdb.io/data-catalog/evm/tvl/liquidity-pools-tvl-usd

Tick-resolution USD TVL for every AMM pool — derived from onchain reserves & BlockDB prices. 10 EVM chains.

## Overview

* **Dataset ID:** `0701`
* **Table:** `blockdb_evm.b0701_liquidity_pools_tvl_usd_v1`
* **Description:** Pool TVL (Total Value Locked) snapshots in USD, computed from reserves multiplied by fiat prices. Provides a standardized USD-denominated measure of pool liquidity at each on-chain event.
* **Primary key:** `(pool_uid, block_number, tx_index, log_index)`
* **API:** [POST /evm/tvl](/api-reference/evm/tvl/tvl-usd)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-TVL-USD-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0701_liquidity_pools_tvl_usd_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-TVL-USD-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0701_liquidity_pools_tvl_usd_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

<Info>
  TVL is computed as `sum(token_amounts[i] x fiat_price[i])` for all tokens in the pool. The `token_amounts` array is aligned with the pool's token order from the `blockdb_evm.b0211_liquidity_pools_v1` dataset.
</Info>

## Columns

| Column                | Type               | Description                                                           |
| --------------------- | ------------------ | --------------------------------------------------------------------- |
| `pool_uid`            | `BYTEA`            | Unique pool identifier (32 bytes).                                    |
| `exchange_id`         | `INTEGER`          | Exchange/DEX identifier.                                              |
| `type_id`             | `INTEGER`          | Pool type identifier (FK to liquidity\_pool\_types).                  |
| `block_number`        | `BIGINT`           | Block number when the TVL snapshot was recorded.                      |
| `block_time`          | `TIMESTAMPTZ`      | UTC timestamp when the block was mined.                               |
| `tx_index`            | `INTEGER`          | Transaction index within the block.                                   |
| `log_index`           | `INTEGER`          | Log index within the block.                                           |
| `token_amounts`       | `NUMERIC(78,18)[]` | Array of token amounts (decimals-adjusted), aligned with pool tokens. |
| `tvl_usd`             | `NUMERIC(78,18)`   | Total value locked in USD.                                            |
| `_tracing_id`         | `BYTEA`            | Tracing ID of this TVL record (18 bytes).                             |
| `_parent_tracing_ids` | `BYTEA[]`          | Tracing IDs of the parent records leading to this TVL record.         |
| `_created_at`         | `TIMESTAMPTZ`      | Record creation timestamp.                                            |
| `_updated_at`         | `TIMESTAMPTZ`      | Record last update timestamp.                                         |

## Use Cases

* DEX and pool TVL rankings and dashboards
* Liquidity migration tracking across protocols
* TVL trend analysis and anomaly detection
* Protocol health monitoring and risk assessment
* Liquidity depth scoring for routing decisions

## Related Datasets

<CardGroup>
  <Card title="Liquidity Pools Reserves" icon="database" href="/data-catalog/evm/reserves/liquidity-pools-reserves">
    Raw reserve snapshots that feed TVL calculations.
  </Card>

  <Card title="Liquidity Pools" icon="water" href="/data-catalog/evm/entities/liquidity-pools">
    Pool registry for the TVL-tracked venues.
  </Card>

  <Card title="Token-to-USD VWAP" icon="dollar-sign" href="/data-catalog/evm/prices/token-to-fiat-vwap">
    USD benchmarks used when marking reserves to dollars.
  </Card>
</CardGroup>


# Liquidity Pool Yields
Source: https://docs.blockdb.io/data-catalog/evm/yields/liquidity-pools-yields

Predicted LP yield & APY per AMM pool across 7 time horizons — derived from onchain swap fees. 10 EVM chains.

## Overview

* **Dataset ID:** `0411`
* **Table:** `blockdb_evm.b0411_liquidity_pools_yields_v1`
* **Description:** Rolling yield/ROI predictions per pool over fixed horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D), based on historical swap fees (`blockdb_evm.b0303_liquidity_pools_swap_fees_v1`) and current reserves (latest `blockdb_evm.b0301_liquidity_pools_reserves_v1` snapshot).
* **Primary key:** `(pool_uid, target_period_days, block_number, tx_index, log_index)`
* **API:** [POST /evm/yields](/api-reference/evm/yields/yields)
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Yields-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0411_liquidity_pools_yields_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Yields-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0411_liquidity_pools_yields_v1.json?download=true)

## Sample Viewer

<Frame>
  <iframe />
</Frame>

<Info>
  This dataset emits aligned arrays (one element per pool token). Use `tokens[]` to line up `current_reserves[]`, volumes, fees, and ROI predictions.
</Info>

## Core concepts

* **Target horizon vs observed history**
  * `target_period_days`: horizon you requested (1, 3, 7, 14, 30, 90, 365)
  * `observed_period_days`: how many days of history were available/used
* **Extrapolation**
  * When `observed_period_days < target_period_days`, the dataset marks the row as extrapolated and scales observed values by:
    * (extrapolation\_factor = target\_period\_days / observed\_period\_days)
* **ROI**
  * For each token index `i`:
    * (roi\_predicted\[i] = user\_fees\_predicted\[i] / current\_reserves\[i])

## Columns

| Column                 | Type               | Description                                                                                        |                                                                             |
| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `pool_uid`             | `BYTEA`            | Pool identifier (internal).                                                                        |                                                                             |
| `exchange_id`          | `INTEGER`          | Exchange/DEX identifier.                                                                           |                                                                             |
| `type_id`              | `INTEGER`          | Pool type identifier (FK to liquidity\_pool\_types).                                               |                                                                             |
| `block_number`         | `BIGINT`           | Block height of the as-of snapshot anchor.                                                         |                                                                             |
| `block_time`           | `TIMESTAMPTZ`      | UTC timestamp of the as-of snapshot anchor.                                                        |                                                                             |
| `tx_index`             | `INTEGER`          | Transaction index within the block.                                                                |                                                                             |
| `log_index`            | `INTEGER`          | Log index within the transaction.                                                                  |                                                                             |
| `target_period_days`   | `SMALLINT`         | Target horizon in days. Allowed: `1, 3, 7, 14, 30, 90, 365`.                                       |                                                                             |
| `observed_period_days` | `SMALLINT`         | History actually used (must be `> 0` and `<= target_period_days`).                                 |                                                                             |
| `is_full_period`       | `BOOLEAN`          | `true` when `observed_period_days == target_period_days`.                                          |                                                                             |
| `is_extrapolated`      | `BOOLEAN`          | `true` when the row is scaled from shorter history.                                                |                                                                             |
| `extrapolation_factor` | `NUMERIC(9,6)`     | Scaling factor applied when extrapolating (must be `> 1` when extrapolated; `1` when full period). | e.g. 365.0 for 365D predicted from 1D; max = target\_period\_days / 1 = 365 |
| `window_start_time`    | `TIMESTAMPTZ`      | Start time of the observed window.                                                                 |                                                                             |
| `window_end_time`      | `TIMESTAMPTZ`      | End time of the observed window.                                                                   |                                                                             |
| `tokens`               | `BYTEA[]`          | Pool token addresses (aligned arrays index by this order).                                         |                                                                             |
| `current_reserves`     | `NUMERIC(78,18)[]` | Current reserves per token (decimals-adjusted).                                                    |                                                                             |
| `volume_observed`      | `NUMERIC(78,18)[]` | Observed traded volume per token in the window.                                                    |                                                                             |
| `volume_predicted`     | `NUMERIC(78,18)[]` | Predicted traded volume per token for the target horizon.                                          |                                                                             |
| `user_fees_observed`   | `NUMERIC(78,18)[]` | Observed user/LP fees per token in the window.                                                     |                                                                             |
| `user_fees_predicted`  | `NUMERIC(78,18)[]` | Predicted user/LP fees per token for the target horizon.                                           |                                                                             |
| `roi_predicted`        | `NUMERIC(12,9)[]`  | Predicted ROI fraction per token for the target horizon.                                           |                                                                             |
| `_tracing_id`          | `BYTEA`            | Deterministic BlockDB lineage identifier for the yield record.                                     |                                                                             |
| `_parent_tracing_ids`  | `BYTEA[]`          | Tracing IDs for upstream derived records referenced during computation.                            |                                                                             |
| `_created_at`          | `TIMESTAMPTZ`      | Record creation timestamp.                                                                         |                                                                             |
| `_updated_at`          | `TIMESTAMPTZ`      | Record update timestamp.                                                                           |                                                                             |

## Use Cases

* Pool-level yield and ROI forecasting across standardized horizons
* Ranking pools by predicted fee yield (token-wise and pool-wise)
* Inputs for portfolio allocation and liquidity mining analytics
* Validating fee models by comparing predicted vs realized forward windows

## Related Datasets

<CardGroup>
  <Card title="Swap fees" icon="coins" href="/data-catalog/evm/swaps/liquidity-pools-swap-fees">
    Per-swap fees that feed yield models.
  </Card>

  <Card title="Liquidity Pools Reserves" icon="database" href="/data-catalog/evm/reserves/liquidity-pools-reserves">
    Reserve snapshots used to calculate TVL exposure.
  </Card>
</CardGroup>


# SLAs
Source: https://docs.blockdb.io/data-catalog/overview/access-and-sla

Availability targets, access controls, and support expectations for the catalog.

## Availability Targets

* **API gateway**: 99.95% monthly uptime objective for catalog endpoints.
* **WSS gateway**: 99.95% monthly uptime objective for WSS endpoints.
* **Export bucket**: 99.95% availability for managed parquet exports.
* **Docs + schema registry**: 99.95% uptime served via redundant CDNs.

<Callout>
  Scheduled maintenance windows occur Saturdays 04:00-06:00 UTC. We only take writes offline; historical reads continue to serve from replicas.
</Callout>

## Access Control

* **API key entitlements** are granted per account and determine which dataset IDs and chains you can query (for example access to dataset `0101` for [blocks](/data-catalog/evm/primitives/blocks)).
* **Row-level constraints** are enforced for private beta datasets via tenant IDs baked into `_tracing_id` metadata.
* **Rotate API keys** from the dashboard when needed; revoke compromised keys immediately.

## Support Channels

| Need                | Channel                     | Expected Response                                |
| ------------------- | --------------------------- | ------------------------------------------------ |
| SLA breach / outage | `status.blockdb.io` + pager | Immediate updates + under 30 min acknowledgement |
| Schema questions    | `support@blockdb.io`        | \< 24h during business days                      |

## Incident Process

1. Detection via monitoring or customer report.
2. Status page update + email blast for impacted dataset families.
3. Mitigation, verification, and postmortem delivery within 5 business days.

<Callout icon="lightbulb">
  Enterprise support plans can include custom SLAs or dedicated escalation paths. Reach out to your account manager to enable them.
</Callout>


# Coverage
Source: https://docs.blockdb.io/data-catalog/overview/coverage

Chains, networks, and DEX protocols currently represented in the BlockDB catalog.

## Supported Chains

| Chain ID | Network           | Status           |
| -------- | ----------------- | ---------------- |
| `1`      | Ethereum Mainnet  | ✅ Supported      |
| `10`     | Optimism          | 🔵 Investigation |
| `56`     | BNB Chain         | 🔵 Investigation |
| `130`    | Unichain          | 🟡 Beta          |
| `137`    | Polygon           | 🔵 Investigation |
| `146`    | Sonic             | 🟡 Beta          |
| `5000`   | Mantle            | 🟡 Beta          |
| `8453`   | Base              | 🔵 Investigation |
| `42161`  | Arbitrum          | 🔵 Investigation |
| `43114`  | Avalanche C-Chain | 🟡 Beta          |
| `59144`  | Linea             | 🔵 Investigation |

### How do new chains roll out?

Chains progress through the following lifecycle:

**Investigation → Beta → Supported**

Each new chain is promoted after BlockDB completes:

* Full raw on-chain data indexing
* Historical backfill validation
* Reorg replay testing under mainnet conditions
* Proven parity across datasets and traceability layers

***

## DEX Protocol Coverage

Protocol support is **cross-network**.

If a protocol is marked ✅ **Supported** and it is deployed on a chain that BlockDB supports, it is automatically supported on that chain.

Example: if **Uniswap v4** is deployed on **Polygon** and **Polygon** is supported, then **Uniswap v4 on Polygon** is automatically supported.

| Protocol                 | Status           |
| ------------------------ | ---------------- |
| **Uniswap v2**           | ✅ Supported      |
| **Uniswap v3**           | ✅ Supported      |
| **Uniswap v4**           | ✅ Supported      |
| **Curve**                | 🔵 Investigation |
| **Balancer v2**          | 🟡 Beta          |
| **Balancer v3**          | 🟡 Beta          |
| **SushiSwap v2**         | ✅ Supported      |
| **SushiSwap v3**         | ✅ Supported      |
| **PancakeSwap v2**       | ✅ Supported      |
| **PancakeSwap v3**       | ✅ Supported      |
| **Joe V2**               | 🔵 Investigation |
| **Joe V2.1**             | 🔵 Investigation |
| **Joe V2.2**             | 🔵 Investigation |
| **Maverick**             | 🔵 Investigation |
| **BaseSwap**             | 🔵 Investigation |
| **Aerodrome Slipstream** | 🔵 Investigation |
| **Aerodrome V1**         | 🔵 Investigation |
| **Velodrome V1**         | 🔵 Investigation |
| **Velodrome V2**         | 🔵 Investigation |
| **Velodrome V3**         | 🔵 Investigation |
| **PulseX V1**            | 🔵 Investigation |
| **PulseX V2**            | 🔵 Investigation |
| **ShibaSwap v1**         | ✅ Supported      |
| **ShibaSwap v2**         | ✅ Supported      |

### How do new DEX protocols roll out?

New DEX protocols progress through the following lifecycle:

**Investigation → Beta → Supported**

Each new DEX protocol is promoted after BlockDB completes:

* Factory Discovery & Pool Taxonomy Mapping
* ABI Decoding & Contracts Function Calls Validation
* Deterministic Pool State Reconstruction

<Callout icon="lightbulb">
  Protocol coverage expands automatically as new pool types are supported.\
  Subscribe to **[Release Notes](/release-notes/home)** for weekly updates on supported networks and DEX integrations.
</Callout>


# Freshness
Source: https://docs.blockdb.io/data-catalog/overview/data-freshness

Latency targets and validation routines for keeping datasets current.

## Freshness by channel

BlockDB processes datasets in a coordinated pipeline, so most tables advance together. The main differences you observe in freshness come from **delivery channel** and **chain-specific reorg/finality buffers**.

| Delivery Channel                     | Typical Freshness | Notes                                                                                       |
| ------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------- |
| **Real-time (WSS)**                  | Lowest latency    | Reorg-aware: you may see updates for recent blocks within the real-time buffer window.      |
| **API (REST)**                       | Near-real-time    | Stability guaranteed via chain-specific backoff beyond max reorg; queries are reproducible. |
| **Warehouse shares**                 | Hourly            | Freshness depends on provider and replication cadence.                                      |
| **Bulk exports<br />(SFTP/S3/Blob)** | Nightly snapshots | Nightly by default; hotfix replays are run ad-hoc if needed.                                |

## Chain buffers (blocks)

| Chain ID | Chain            | API & Archive buffer (blocks) | WSS buffer (blocks) | Rationale                                                                                                    | Source                                                                    |
| -------- | ---------------- | ----------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `1`      | Ethereum Mainnet | `3`                           | `0`                 | Etherscan forked-block data shows observed reorgs are almost always one block, we set the buffer above that. | [https://etherscan.io/blocks\_forked](https://etherscan.io/blocks_forked) |

<Info>
  These values are operational defaults and may change over time as chains evolve. If you need stricter guarantees for a specific chain, contact support.
</Info>

### How do I monitor data freshness?

* Use the `_updated_at` column for the dataset you query.
* For API pagination, you can also monitor the response `cursor` progression and returned `count` over time.

<Callout icon="lightbulb">
  Need tighter guarantees? Mirror the dataset via the API and compare `_tracing_id` values. Differences indicate your mirror is stale or queried inside the reorg buffer.
</Callout>


# Granularity
Source: https://docs.blockdb.io/data-catalog/overview/data-granularity

How BlockDB's data granularity enables tick-by-tick prices and full tick range reconstruction for concentrated liquidity protocols.

## Overview

BlockDB indexes **every emitted EVM log and all internal transactions** individually — **one row per event, no aggregation at index time**. This is the architectural foundation that makes tick-by-tick price data and full tick range reconstruction possible for dynamically distributed liquidity protocols like Uniswap v3 and v4.

## What This Enables

### Tick-by-Tick Prices

Because every `Swap` log is captured individually, BlockDB produces a **price print per swap** — not per block, not per minute:

* Each swap event yields one realized price observation
* Continuous price history is reconstructable at any resolution, without interpolation
* Swap prints carry execution metadata: pool, tokens, amounts in/out, fee tier

This is the foundation for [`b0302_token_to_token_prices_swap_prints_v1`](/data-catalog/evm/prices/token-to-token-prices-swap-prints) — the highest-resolution price dataset BlockDB publishes.

### Full Tick Range for Concentrated Liquidity Protocols

Protocols like **Uniswap v3 and v4** distribute liquidity across discrete price ticks rather than uniformly across the curve. Reconstructing the full tick range — and how it shifts over time — requires capturing every `Mint`, `Burn`, and `Swap` event.

BlockDB indexes all of these as individual rows, which makes it possible to:

* Reconstruct the **complete active tick range** at any block / tx / log index
* See exactly where liquidity is concentrated at any point in time
* Track how individual positions open, adjust, and close
* Compute in-range vs. out-of-range liquidity for any price interval

<Frame>
  <img alt="Full tick range distribution for a Uniswap v3 liquidity pool — computed from log-level event data indexed by BlockDB." />
</Frame>

The chart above shows the full tick range distribution of a Uniswap v3 pool. Each bar represents the amount of liquidity available at a specific price tick. This view is only possible when every liquidity event is captured and indexed individually.

Pool reserves with full tick detail are available in [`b0301_liquidity_pools_reserves_v1`](/data-catalog/evm/reserves/liquidity-pools-reserves) and its companion detail table.

***

See the [dataset index](/data-catalog/evm/dataset-index) for each table's grain and key columns.


# Lineage
Source: https://docs.blockdb.io/data-catalog/overview/data-lineage

How BlockDB ties derived rows back to on-chain events using stable identifiers and coordinates.

## Overview

Every record BlockDB delivers comes with a **mathematical receipt you can independently verify**.

You can always ask: **where did this come from, and was it computed correctly?**

**Lineage is the answer** — a traceable path from any derived row (a price, a pool snapshot, a transfer) back to the raw on-chain log that produced it, anchored by cryptographically stable coordinates and verifiable against the Merkle trie that secures the chain itself.

<Frame>
  <img alt="Proof of derivation — how BlockDB traces derived dataset rows back to raw on-chain log events via stable coordinates and Merkle-verifiable receipts." />
</Frame>

***

## What Lineage Gives You

<CardGroup>
  <Card title="Stable row handles" icon="fingerprint">
    `_tracing_id` repeats across API responses and warehouse exports for the same logical row — safe to store, join, and use in support tickets.
  </Card>

  <Card title="Explicit on-chain coordinates" icon="crosshairs">
    `block_height`, `transaction_hash`, `log_index`, and related fields anchor every row to chain execution, where the DDL defines them.
  </Card>

  <Card title="Cross-dataset joins" icon="code-merge">
    Shared coordinates and [dataset IDs](/api-reference/enumerations/dataset-id) let you join OHLC, reserves, transfers, and primitives in SQL or notebooks.
  </Card>
</CardGroup>

***

## Tracing Fields

| Location        | Field                                                                 | What it provides                                                            |
| --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| APIs (`/evm/*`) | `_tracing_id`                                                         | Opaque per-tenant handle for the row when present in that dataset's schema. |
| SQL exports     | `_tracing_id`, `_created_at`, `_updated_at`                           | Mirror API fields for warehouses (where the table defines them).            |
| Row payloads    | `block_height`, `transaction_hash`, `log_index`, pool/token addresses | Direct anchors to chain state and protocol entities.                        |

<Note>
  Not every aggregate table includes `_tracing_id` or `tracking_ids_view[]`. Use the [data catalog](/data-catalog/evm/dataset-index) for the exact column list per table.
</Note>

***

## Lineage API

For programmatic provenance expansion, use the Historic API [Lineage](/api-reference/evm/lineage/overview) suite:

<CardGroup>
  <Card title="Record" icon="receipt" href="/api-reference/evm/lineage/record">
    `POST /evm/lineage/record` — retrieve lineage metadata for a specific row.
  </Card>

  <Card title="Parents" icon="sitemap" href="/api-reference/evm/lineage/parents">
    `POST /evm/lineage/parents` — walk the provenance graph up to parent records.
  </Card>
</CardGroup>


# Verification
Source: https://docs.blockdb.io/data-catalog/overview/data-verification

Verification processes that guarantee integrity across BlockDB's public datasets.

## Overview

BlockDB's indexers do far more than persist raw blockchain payloads. Every dataset export passes through a **multi-layer cryptographic verification pipeline** — running in sequence for every block, every transaction, and every log:

<Steps>
  <Step title="Log RLP Reconstruction">
    Each log's **contract address**, **topics**, and **data** are re-encoded from scratch using RLP encoding. This ensures every byte of every event is accounted for — no truncation, no reordering, no partial processing.
  </Step>

  <Step title="Log Bloom Validation">
    Each transaction's **2048-bit bloom filter** is recomputed by hashing the emitting contract address and every indexed topic. The result is compared bit-for-bit against the on-chain value. A single differing bit fails validation — catching subtle corruption that receipt checks alone would miss.
  </Step>

  <Step title="Receipts Root Recomputation">
    The reconstructed receipts are assembled into a **Merkle Patricia Trie**. A Keccak-256 hash of the rebuilt root is compared against the chain-supplied `receiptsRoot`. Any mismatch triggers an immediate blocking incident.
  </Step>

  <Step title="Block Continuity Check">
    Block numbers are verified to increment without gaps, and every `parent_block_hash` is matched against the previous block. This guarantees a complete, unbroken chain of evidence across the entire indexed range.
  </Step>
</Steps>

These checks ensure that all exported data is *provably identical* to what was produced on-chain — not just at ingest time, but at every stage of archival and replication.

***

## Stored Evidence

Each successfully verified block writes two immutable breadcrumbs to [`blockdb_evm.b0101_blocks_v1`](/data-catalog/evm/primitives/blocks):

| Column                            | Description                                                      |
| --------------------------------- | ---------------------------------------------------------------- |
| `_computed_receipt_root`          | The receipts root recomputed from verified transaction receipts. |
| `_computed_receipt_timestamp_utc` | UTC timestamp when the recomputation occurred.                   |

These fields allow consumers and auditors to independently confirm that BlockDB's recomputation matched the chain-provided root at the time of export.

***

## Archive Re-validation

In addition to live verification, BlockDB runs **offline re-validation** of data already exported to the persistence layer — replaying all verification logic using only stored data, without depending on live node responses:

* Long-term consistency across cold storage and replicas is preserved
* Block continuity and parent hash linkage remain intact after archival compaction
* Historical reproducibility is maintained, proving that what left the exporter stays self-consistent at rest

Because this process operates solely on exported data, it confirms integrity *post-ingestion* — and can safely run on lagged replicas or analytical nodes without affecting live indexing performance.

***

## Integrity Guarantees

The combination of **Log RLP reconstruction**, **bloom validation**, **receipts-root recomputation**, and **block continuity checks** makes BlockDB's verification pipeline uniquely resistant to silent corruption:

| Safeguard                                                   | Ensures                                                                    | Prevents                                                      |
| ----------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `LogsRlp` rebuilt from each log's address, topics, and data | Log-level completeness and byte-accurate reproduction of on-chain payloads | Missing or truncated logs                                     |
| Receipts root recomputed from all transactions              | Transaction-level integrity and Merkle proof consistency                   | Missing transactions                                          |
| Block continuity validation                                 | Continuous block sequence and parent hash linkage                          | Missing or orphaned blocks                                    |
| Archive re-validation using exported database data          | Long-term consistency and reproducibility independent of live nodes        | Data drift, replica inconsistency, or corruption after export |

These layers form a **cryptographically auditable chain of evidence**, far stronger than checksum-based or row-count validation methods.

***

## De-duplication & Reorg Safety

BlockDB enforces **stable, domain-correct primary keys** to prevent duplicates across ingestion — mirroring how identity is defined on-chain and guaranteeing deterministic joins and idempotent re-ingestion:

* **`blockdb_evm.b0101_blocks_v1`** — primary key: `block_number`
* **`blockdb_evm.b0102_transactions_v1`** — primary key: `tx_hash`
* **`blockdb_evm.b0103_logs_v1`** — composite key: `(block_number, tx_index, log_index)`

Archive indexing operates with a **bounded backoff from the chain tip** (typically 3-100 blocks, chain-dependent). This buffer ensures short-range reorgs don't leak transient data into exports, and that final datasets reflect **post-reorg canonical history**.

***

## Auditing & API

BlockDB exposes dedicated verification endpoints so clients can independently validate exported data on their side:

<CardGroup>
  <Card title="Verify Receipt Root" icon="shield-check" href="/api-reference/evm/verification/verify-receipt-root">
    Recompute and compare canonical receipt trie roots against the chain-supplied value.
  </Card>

  <Card title="Verify Logs Bloom" icon="shield-halved" href="/api-reference/evm/verification/verify-logs-bloom">
    Regenerate logs bloom filters for targeted block or transaction reconciliations.
  </Card>
</CardGroup>

<Note>
  For organizations that require deeper insight into the end-to-end verification pipeline or custom validation tooling, contact us at [support@blockdb.io](mailto:support@blockdb.io).
</Note>


# Delivery
Source: https://docs.blockdb.io/data-catalog/overview/delivery

Available channels for accessing and synchronizing BlockDB datasets.

## Delivery Matrix

| Channel                    | Description                                          | Status            | Notes                                                                                                             |
| -------------------------- | ---------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| **API**                    | REST access per dataset ID (`/api-reference`)        | ✅ Supported       | Ideal for filtered pulls and low-latency queries. See <a href="/api-reference/overview/home">API intro</a>.       |
| **SFTP**                   | Managed SFTP drops with nightly dataset snapshots    | 🟡 Beta           | Includes archived data and schema manifests. See <a href="/user-guide/archive-delivery/sftp">SFTP quickstart</a>. |
| **WSS**                    | Real-time event stream (\<150 ms latency)            | 🟡 Beta           | Provides live updates for subscribers. See <a href="/wss-reference/overview/introduction">WSS reference</a>.      |
| **MCP**                    | Machine-to-Machine protocol for AI Agents            | 🔵 In Development | Enables autonomous agent data retrieval and reasoning.                                                            |
| **Amazon Redshift**        | Data sharing via Redshift Serverless                 | ✅ On Request      | See <a href="/user-guide/archive-delivery/amazon-redshift-share">Redshift Share</a>.                              |
| **Azure Blob Storage**     | ADLS Gen2 integration via service principal          | ✅ On Request      | See <a href="/user-guide/archive-delivery/azure-blob-storage">Azure Blob</a>.                                     |
| **Snowflake Share**        | Secure Data Share to your Snowflake account          | ✅ On Request      | See <a href="/user-guide/archive-delivery/snowflake-share">Snowflake Share</a>.                                   |
| **Google BigQuery**        | Authorized view or transfer service                  | ✅ On Request      | See <a href="/user-guide/archive-delivery/google-bigquery">BigQuery</a>.                                          |
| **Amazon S3**              | Cross-region replication into customer-owned buckets | ✅ On Request      | See <a href="/user-guide/archive-delivery/amazon-s3">S3</a>.                                                      |
| **Databricks Delta Share** | Native Delta Sharing tables                          | ✅ On Request      | See <a href="/user-guide/archive-delivery/databricks-delta-share">Delta Share</a>.                                |

<Callout icon="lightbulb">
  Most customers combine the **API** (for ad-hoc lookups) with one or more **bulk delivery** channels for analytics and archival needs.\
  Use the `_tracing_id` column to reconcile records consistently across delivery channels.
</Callout>

## Choosing a channel

* Real-time pipelines → API / WSS
* Historical backfills → SFTP / S3 / Azure Blob
* Analytics at scale → Snowflake / Redshift / BigQuery / Delta Share


# Overview
Source: https://docs.blockdb.io/data-catalog/overview/introduction

BlockDB data catalog — complete schema reference for EVM blockchain datasets: blocks, transactions, prices, DeFi, and transfers.

## Overview

BlockDB ships a Postgres schema for every dataset that also powers the Historic REST API. The scripts in `/BlockDb.Postgres.Tables.Public` are the canonical definitions; each dataset here mirrors the SQL `CREATE TABLE` statements, constraints, and indexes from that source.

All tables follow a `<schema>.<dataset_id>_<name>_v<major>` naming convention to support multiple chain families at scale:

* **EVM datasets** live in `blockdb_evm` (for example, `blockdb_evm.b0101_blocks_v1`)
* **SVM datasets** live in `blockdb_svm` (for example, `blockdb_svm.b0101_blocks_v1`)

Dataset IDs match the REST API identifiers (`0101` for blocks, `0201` for ERC-20 tokens, etc.) so you can map SQL exports to API payloads or lineage metadata.

## How to use this catalog

1. Choose your chain family (EVM or SVM).
2. Open the chain overview to browse datasets and review per-table documentation.
3. Use dataset IDs to map between SQL tables, API payloads, and lineage records.

<CardGroup>
  <Card title="EVM dataset index" icon="ethereum" href="/data-catalog/evm/dataset-index">
    Browse all EVM tables, grouped by domain (ledger, tokens, reserves, pricing, analytics).
  </Card>

  <Card title="SVM overview" icon="cube" href="/data-catalog/svm/overview">
    Learn about the Solana (SVM) catalog roadmap and upcoming dataset structure.
  </Card>
</CardGroup>


# Schema Governance
Source: https://docs.blockdb.io/data-catalog/overview/schema-governance

How BlockDB versions SQL assets and communicates breaking or additive changes.

## Versioning Rules

* **Semantic suffix:** Tables follow the pattern `<dataset_id>_<name>_v<major>`.
* **Additive fields:** Columns may be appended without bumping the major version; they're documented in changelogs and fully backfilled before announcement.
* **Breaking changes:** Renames, type changes, or constraint updates trigger a new table version. The previous version remains queryable for at least one quarter.

| Scenario                  | Action                                  | Communication             |
| ------------------------- | --------------------------------------- | ------------------------- |
| **New nullable column**   | Add column, update docs                 | Changelog                 |
| **Column type widening**  | Create `_v<next>` table and dual-write  | RFC via customer email    |
| **Constraint tightening** | Validate in shadow schema, then publish | Maintenance window notice |

## Deprecation Cycle

1. **Announcement (T₀)** — Publish a deprecation note in release notes and mark the dataset here.
2. **Dual writing (T₀ → T₀ + 30 d)** — Both versions populate in parallel. `_created_at` / `_updated_at` values align.
3. **Cutover (T₀ + 30 d)** — Consumers switch to the new table. Old exports freeze but remain queryable.
4. **Retirement (T₀ + 90 d)** — Old table is archived in cold storage. Contact support if you need an exception.

## Consumer Guidance

* Track schema drift by comparing SQL scripts in `BlockDb.Postgres.Tables.Public` against your internal materialized version.
* Pin ETL jobs to dataset IDs (`0101`, `0201`, etc.) rather than table names to automatically pick up new versions.
* Monitor the account-linked email for schema change notifications.

<Callout icon="lightbulb">
  Want early access to upcoming schema shifts?\
  Opt into the private pre-release program at [support@blockdb.io](mailto:support@blockdb.io).
</Callout>

## Breaking change template

When a breaking change is planned, communications include:

* Summary of change and impacted datasets
* Migration guide and mapping (old → new)
* Dual-write window dates (start/end)
* Cutover date and validation checklist
* Retirement date and archive location

## Consumer checklist

* Pin ETL by dataset IDs (e.g., `0101`) not hard-coded table names
* Watch Release Notes for additive/breaking changes
* Diff SQL in `BlockDb.Postgres.Tables.Public` against your materialized schema


# Overview
Source: https://docs.blockdb.io/data-catalog/svm/overview

Guide to Solana Virtual Machine datasets, catalog structure, and delivery options.

## Scope

The SVM catalog is designed to provide institutional-grade, canonical Solana ledger and execution metadata—mirroring the schema rigor, columnar conventions, and payload structure of the established [EVM Datasets family](/data-catalog/evm/dataset-index). This ensures cross-chain data engineering workflows can leverage the same paradigms for both EVM and SVM datasets.

<br />

<Note>
  BlockDB SVM coverage is currently in the research and engineering phase. General availability will follow after extensive validation.<br />
  For partnership opportunities, early access, or detailed requirements discussions, reach out to <a href="mailto:support@blockdb.io">[support@blockdb.io](mailto:support@blockdb.io)</a>.
</Note>


# Free Research Datasets
Source: https://docs.blockdb.io/free-datasets/home

Free, audit-grade Ethereum datasets for researchers, quants, and AI builders — 10+ years of token transfers and DEX swaps, published openly with full lineage on Hugging Face.

## Public chain data should be public

Querying Ethereum's history shouldn't require a corporate budget. The data is already on-chain — yet getting it clean, decoded, and usable still means archive nodes, tracing pipelines, or per-megabyte export bills from analytics platforms.

So we did the heavy lifting and gave it away. **10+ years of Ethereum, indexed, decoded, and lineage-tagged** — free to download, no credit card, no sales call, no API quota.

<Card title="Get the datasets on Hugging Face" icon="database" href="https://huggingface.co/collections/BlockDB/blockdb-full-evm-research-datasets-10-years">
  BlockDB Full EVM Research Datasets — 10+ years. Browse, preview, and download every published set.
</Card>

Every row carries a `_tracing_id` back to on-chain evidence. You don't have to trust us — you can verify it through the [Lineage API](/api-reference/evm/lineage/overview).

Files are partitioned Parquet, so you can pull a single token, month, or exchange instead of the full archive.

## Load it

```python theme={null}
import pandas as pd

df = pd.read_parquet(
    "hf://datasets/BlockDB/Stablecoin-Transfers-Ethereum-Cryptocurrency-Data",
)
print(df.head())
```

Full mirror of any dataset:

```bash theme={null}
huggingface-cli download BlockDB/Stablecoin-Transfers-Ethereum-Cryptocurrency-Data \
  --repo-type dataset --local-dir ./blockdb-stablecoin-transfers
```

## Licensing

* **Free to use** for research, backtesting, model training, and commercial products built on top of the data.
* **Keep the `_tracing_id` column** if you redistribute — it preserves provenance back to on-chain evidence.

## Need more than this snapshot?

These are historical snapshots. When you need to go live:

* **Filters, other tokens, or recent history** — [BlockDB Historic REST API](https://docs.blockdb.io/api-reference/overview/home).
* **Real-time streams** — [BlockDB WebSocket feed](https://docs.blockdb.io/wss-reference/overview/introduction).
* **Custom extracts** (anything we can derive from on-chain data) — [support@blockdb.io](mailto:support@blockdb.io).


# Home
Source: https://docs.blockdb.io/index

BlockDB Documentation Hub — quality DeFi data: verifiable, real-time, complete.

<section>
  <svg>
    <polygon />

    <polygon />
  </svg>

  <div>
    <div>
      <h1>
        Welcome to BlockDB Documentation
      </h1>

      <p>
        Build with verifiable, real-time, and complete DeFi data across chains.
      </p>
    </div>
  </div>
</section>

<div>
  <section>
    <h2>Knowledge Base</h2>

    <p>
      Everything you need to deploy BlockDB, integrate programmatically, and trace rows back to on-chain evidence.
    </p>
  </section>

  <section>
    <div>
      <div />

      <div />

      <div>
        <div>
          <h2>👋 New to BlockDB?</h2>

          <p>
            Follow the quickstart to connect, authenticate, and run your first query in minutes.
          </p>
        </div>

        <a href="/user-guide/about-blockdb/quick-start-guide">
          Get Started

          <svg>
            <path />
          </svg>
        </a>
      </div>
    </div>
  </section>

  <section>
    <Columns>
      <Card icon="database" href="/data-catalog/overview/introduction">
        <h3>
          Data Catalog
        </h3>

        <span>
          Browse entities and tables with stable schemas and tracing fields across supported chains.
        </span>
      </Card>

      <Card icon="rocket" href="/user-guide/about-blockdb/quick-start-guide">
        <h3>
          Quick Start Guide
        </h3>

        <span>
          Follow the quickstart to connect, authenticate, and run your first query in minutes.
        </span>
      </Card>

      <Card icon="laptop-code" href="/user-guide/query-examples">
        <h3>
          Query Cookbook
        </h3>

        <span>
          Copy-ready SQL and REST patterns for common DeFi analytics.
        </span>
      </Card>
    </Columns>
  </section>

  <section>
    <h2>API Endpoints</h2>
    <p>Programmatic access for pipelines, dashboards, and apps.</p>

    <div>
      <Columns>
        <Card icon="cloud" href="/api-reference/overview/home">
          <h3>
            REST API
          </h3>

          <span>
            Endpoints, parameters, pagination, and error semantics.
          </span>
        </Card>

        <Card icon="rss" href="/wss-reference/overview/introduction">
          <h3>
            WebSocket (WSS)
          </h3>

          <span>
            Real-time streams for blocks, swaps, and reserves.
          </span>
        </Card>

        <Card icon="key" href="/api-reference/overview/authorization">
          <h3>
            Auth & Rate Limits
          </h3>

          <span>
            API keys, headers, quotas, and retry guidance.
          </span>
        </Card>
      </Columns>
    </div>
  </section>

  <section>
    <h2>Datasets</h2>
    <p>Start with canonical references, then drill into raw blocks and token analytics.</p>

    <div>
      <Columns>
        <Card icon="table-columns" href="/data-catalog/evm/dataset-index">
          <h3>
            Dataset Index
          </h3>

          <span>
            Complete list of published datasets and SQL table names.
          </span>
        </Card>

        <Card icon="square-binary" href="/data-catalog/evm/primitives/blocks">
          <h3>
            Raw Data
          </h3>

          <span>
            Blocks, transactions, receipts, and decoded logs.
          </span>
        </Card>

        <Card icon="hexagon-vertical-nft" href="/data-catalog/evm/entities/erc20-tokens">
          <h3>
            Tokens & Pools
          </h3>

          <span>
            Token metadata, pool registries, and standardized identifiers.
          </span>
        </Card>

        <Card icon="coins" href="/data-catalog/evm/reserves/liquidity-pools-reserves">
          <h3>
            Reserves
          </h3>

          <span>
            Historical on-chain reserves with slot-level provenance.
          </span>
        </Card>

        <Card icon="tag" href="/data-catalog/evm/prices/token-to-token-prices-swap-prints">
          <h3>
            Pricing
          </h3>

          <span>
            Swap prints, OHLC, VWAP, and USD benchmarks from on-chain activity.
          </span>
        </Card>

        <Card icon="chart-line" href="/data-catalog/evm/prices/token-to-token-vwap">
          <h3>
            Pricing Analytics
          </h3>

          <span>
            VWAP, spreads, and liquidity-aware analytics.
          </span>
        </Card>
      </Columns>
    </div>
  </section>

  <section>
    <h2>Troubleshooting & Support</h2>
    <p>Resolve common issues quickly or contact the team at <a href="https://www.blockdb.io">blockdb.io</a>.</p>

    <div>
      <Columns>
        <Card icon="gear-complex-code" href="/troubleshooting/home">
          <h3>
            Troubleshooting
          </h3>

          <span>
            Connection, auth, schema, and performance fixes.
          </span>
        </Card>

        <Card icon="sparkles" href="/release-notes/home">
          <h3>
            Release Notes
          </h3>

          <span>
            What's new, improvements, and breaking changes.
          </span>
        </Card>

        <Card icon="info" href="/troubleshooting/raising-a-support-ticket">
          <h3>
            Support
          </h3>

          <span>
            Get help from BlockDB engineers.
          </span>
        </Card>
      </Columns>
    </div>
  </section>
</div>


# Pricing Plans
Source: https://docs.blockdb.io/pricing/home

BlockDB pricing — CU-based pay-as-you-go API plans and custom flat-rate real-time WebSocket subscriptions for EVM blockchain data.

## API Plans (Compute Units)

[Learn how CUs work →](/api-reference/overview/compute-units)

<div>
  | Feature                        |                          Free                         |                        Starter                        |                         Growth                        |                         Scale                         |                    Custom                    |
  | :----------------------------- | :---------------------------------------------------: | :---------------------------------------------------: | :---------------------------------------------------: | :---------------------------------------------------: | :------------------------------------------: |
  | **Price**                      |                        **\$0**                        |                      **\$250/mo**                     |                     **\$1,000/mo**                    |                     **\$2,500/mo**                    |                 Contact Sales                |
  | **Rate limit**                 |                        100 RPS                        |                        250 RPS                        |                       1,000 RPS                       |                       2,500 RPS                       |                   Unlimited                  |
  | **CU per month**               |                          100k                         |                           1M                          |                           4M                          |                          10M                          |                    Custom                    |
  | **Extra CU**                   |                           —                           |                       1M / \$250                      |                       1M / \$250                      |                       1M / \$250                      |                    Custom                    |
  | **Infrastructure & Access**    |                                                       |                                                       |                                                       |                                                       |                                              |
  | Archive Node Access (JSON-RPC) |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                 ✓ (Dedicated)                |
  | API                            |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                 ✓ (Dedicated)                |
  | Redundancy                     |                        Standard                       |                    Standard Backup                    |                    Standard Backup                    |                    Standard Backup                    |               Dedicated Backup               |
  | **Data Features**              |                                                       |                                                       |                                                       |                                                       |                                              |
  | Full Historical Coverage       |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                       ✓                      |
  | Lineage Hashes (per row)       |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                       ✓                      |
  | Schema Stability               |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                       ✓                      |
  | **Support & Integration**      |                                                       |                                                       |                                                       |                                                       |                                              |
  | Engineer to Engineer Support   |                           ✓                           |                           ✓                           |                           ✓                           |                           ✓                           |                       ✓                      |
  | Custom Datasets                |                           —                           |                           —                           |                           ✓                           |                           ✓                           |                       ✓                      |
  | **Service Level**              |                                                       |                                                       |                                                       |                                                       |                                              |
  | Uptime SLA                     |                           —                           |                           -                           |                       99.95% SLA                      |                       99.95% SLA                      |                    Custom                    |
  |                                | [Open Account →](https://accounts.blockdb.io/sign-up) | [Open Account →](https://accounts.blockdb.io/sign-up) | [Open Account →](https://accounts.blockdb.io/sign-up) | [Open Account →](https://accounts.blockdb.io/sign-up) | [Contact sales →](mailto:support@blockdb.io) |
</div>

***

## Real-Time (WSS)

Real-time delivery over **WebSockets (WSS)** is priced **flat** — not CU-based. WSS is available on a **custom plan**; pricing starts at **\$1,500/month** based on chains, datasets, and connection requirements. Low-latency delivery is a core strength of BlockDB, supported efficiently via WebSockets (WSS) including **Protobuf**.

<div>
  | Feature                      |                    Custom                    |
  | :--------------------------- | :------------------------------------------: |
  | **Price**                    |              **From \$1,500/mo**             |
  | **Chains**                   |                    Custom                    |
  | **Connections**              |                    Custom                    |
  | **Datasets**                 |                    Custom                    |
  | **Infrastructure & Access**  |                                              |
  | Archive Node Access          |                    Custom                    |
  | Redundancy                   |         Dedicated Backup (on request)        |
  | **Data Features**            |                                              |
  | Lineage Hashes               |                       ✓                      |
  | **Support & Integration**    |                                              |
  | Engineer to Engineer Support |                       ✓                      |
  | Custom Datasets              |                       ✓                      |
  | **Service Level**            |                                              |
  | Uptime SLA                   |                    Custom                    |
  |                              | [Contact sales →](mailto:support@blockdb.io) |
</div>

***

## Bulk Export (SFTP, S3, Azure & more)

Full historical data is available both through the API (CU-based) and via direct bulk delivery. For large backfills or ongoing dataset syncs, **bulk delivery is significantly cheaper than querying through the API** — you pay for the dataset and delivery method, not per-row CU costs.

Pricing is **customized for each customer**.

### Pricing Factors

* **Datasets**: Which datasets you need (blocks, transactions, logs, pricing, etc.)
* **Chains**: Number of blockchain networks (Ethereum, Polygon, Arbitrum, Base, etc.)
* **Delivery Method**: SFTP, S3, Azure Blob Storage, Snowflake Share, Redshift Share, BigQuery, or Databricks Delta Share
* **Delivery Frequency**: One-time export, daily, weekly, or monthly snapshots
* **Data Volume**: Historical depth and time range requirements

<Callout icon="lightbulb">
  Each bulk delivery configuration is unique. We work with you to design a solution that matches your data requirements, budget, and infrastructure preferences.
</Callout>

### Request a Quote

Email [support@blockdb.io](mailto:support@blockdb.io) with your dataset and delivery requirements. We'll respond with a custom quote, typically within 1-2 business days.

<Info>
  We offer 1,000-row sample exports for evaluation — contact support to request a free sample for your desired dataset and delivery method.
</Info>

***

## Related Topics

* [Compute Units](/api-reference/overview/compute-units) - How CU pricing and allowances work.
* [Contact Support](/troubleshooting/raising-a-support-ticket) - Billing and account questions.
* [Contact Support](/troubleshooting/raising-a-support-ticket) - How to reach our team.


# Release Notes
Source: https://docs.blockdb.io/release-notes/home

Changelog of BlockDB product updates, data coverage additions, and API changes.

<Update label="2026-07-06" description="Lineage API performance improvements">
  ## Highlights

  * Optimized lineage API endpoints for efficiency:
    * `POST /evm/lineage/record`
    * `POST /evm/lineage/parents`
</Update>

<Update label="2026-06-10" description="Data freshness documentation updates">
  ## Highlights

  * Updated data freshness documentation: modified chain buffer table headers and values for clarity
  * Removed outdated backfill & replay behavior section
</Update>

<Update label="2026-06-05" description="Build with AI, Free Research Datasets, navbar and banner">
  ## Highlights

  * Added **Build with AI** section with Cursor rule and Claude skill documentation
  * Introduced **Free Research Datasets** page with access details for Ethereum datasets
  * Updated navbar and site banner for the new features
</Update>

<Update label="2026-05-19" description="New EVM API endpoint: Liquidity Distribution, Dense Mode">
  ## Highlights

  * New API endpoints
    * `POST /evm/reserves/liquidity-distribution` for retrieving liquidity distribution
  * Added Dense mode to the following endpoints:
    * `POST /evm/prices/spot/crypto/ohlc`
    * `POST /evm/prices/spot/crypto/vwap`
    * `POST /evm/prices/spot/crypto/vwap-aggregate`
</Update>

<Update label="2026-04-22" description="Docs: API paths, account endpoints, API keys, shared limits">
  ## Highlights

  * **REST path references** — Aligned documentation with current routes (`POST /evm/entities/tokens/erc20`, `POST /evm/raw/blocks-summary`, `POST /evm/reserves`, `POST /evm/prices/spot/crypto/vwap-aggregate`, and related EVM/cross-links)
  * **Account & usage** — Documented `GET /v1/health` (`{ "status": "ok" }`)
  * **Authentication** — Switched public docs to **API keys** replacing OAuth/JWT/Client Credentials guidance
</Update>

<Update label="2026-02-10" description="New EVM Datasets">
  ## Highlights

  * Updated EVM Datasets IDs
  * Updated/Added datasets:
    * `0111` - Internal Transactions (`blockdb_evm.b0111_internal_transactions_v1`)
    * `0201` - ERC-20 Tokens (`blockdb_evm.b0201_erc20_tokens_v1`)
    * `0202` - ERC-721 Tokens (`blockdb_evm.b0202_erc721_tokens_v1`)
    * `0203` - ERC-1155 Tokens (`blockdb_evm.b0203_erc1155_tokens_v1`)
    * `0304` - Token Transfers (`blockdb_evm.b0304_token_transfers_v1`)
  * Updated/Added API endpoints:
    * `POST /evm/raw/internal-transactions` for retrieving internal transactions
    * `POST /evm/entities/tokens/erc20` for retrieving ERC-20 tokens
    * `POST /evm/entities/tokens/erc721` for retrieving ERC-721 tokens
    * `POST /evm/entities/tokens/erc1155` for retrieving ERC-1155 tokens
    * `POST /evm/transfers/token-transfers` for retrieving all token transfers (native, ERC-20, ERC-721, ERC-1155)
</Update>

<Update label="2026-01-17" description="Pricing Plans">
  ## Highlights

  * Added pricing plans page to the documentation
</Update>

<Update label="2026-01-09" description="WebSocket (WSS) Streams">
  ## Highlights

  * Added WebSocket (WSS) streams pages to the documentation (EVM)
</Update>

<Update label="2025-12-29" description="Data Freshness">
  ## Highlights

  * Added data freshness section to the data catalog
  * Updated Digital Exchange enumeration to include new exchanges
  * Updated Pool Types enumeration to include new pool types
</Update>

<Update label="2025-12-27" description="New Datasets: Liquidity Pool Fee Terms, Swap Fees, Yields">
  ## Highlights

  * Added dataset `0212` - Liquidity Pool Fee Terms (`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`)
  * Added dataset `0303` - Liquidity Pool Swap Fees (`blockdb_evm.b0303_liquidity_pools_swap_fees_v1`)
  * Added dataset `0411` - Liquidity Pool Yields (`blockdb_evm.b0411_liquidity_pools_yields_v1`)
  * New API endpoints:
    * `POST /evm/entities/pools/fee-terms` for retrieving liquidity pool fee terms
    * `POST /evm/swaps/fees` for retrieving swap fees
    * `POST /evm/yields` for retrieving yields
  * API Reference reorganized into category-based folders matching navigation structure
  * Data Catalog reorganized into category-based folders matching navigation structure
</Update>

<Update label="2025-12-20" description="New Dataset: Token-to-Token Prices Swap Prints">
  ## Highlights

  * Added dataset `0302` - Token-to-Token Prices Swap Prints (`blockdb_evm.b0302_token_to_token_prices_swap_prints_v1`)
  * New API endpoint: `POST /evm/prices/spot/crypto/prints` for retrieving executed swap prints with realized execution prices
  * Dataset `0501` - Token-to-Token VWAP renamed to `0405` - Token-to-Token VWAP
</Update>

<Update label="2026-01-17" description="API Reference Enhancements">
  ## Highlights

  * Pagination & Limits overview with standardized default/max limits
  * Pricing Suite updates: refreshed crypto overview and added fiat overview
  * Error Codes page rebuilt to reflect current structured error envelopes
  * Pagination controls and JSON syntax clean-up across multiple endpoints
</Update>

<Update label="2025-11-11" description="BlockDB Docs Launch">
  ## Highlights

  * Public launch of BlockDB documentation portal
  * API guides, data catalog (EVM/SVM), delivery methods, and troubleshooting runbooks now available
  * Coverage indexes and error code reference published
</Update>

<Info>
  Looking for system availability history? See <a href="https://status.blockdb.io">Status</a>.
</Info>


# API Error Codes
Source: https://docs.blockdb.io/troubleshooting/error-codes/api/home

HTTP statuses and error bodies returned by BlockDB REST endpoints.

### Format

```json theme={null}
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "from_block must be <= to_block",
    "details": { "field": "from_block" },
    "request_id": "req_01HXYZ..."
  }
}
```

### Common API Errors

| HTTP | Code               | Meaning                    | Action                                   |
| ---- | ------------------ | -------------------------- | ---------------------------------------- |
| 400  | INVALID\_ARGUMENT  | Body failed validation     | Fix the field noted in details           |
| 401  | UNAUTHENTICATED    | Missing/invalid token      | Send Authorization: Bearer token         |
| 403  | PERMISSION\_DENIED | Not allowed for plan/scope | Request access or adjust scope           |
| 404  | NOT\_FOUND         | Resource not found         | Verify endpoint or identifiers           |
| 409  | CONFLICT           | Mutually exclusive filters | Choose one filter set                    |
| 429  | RATE\_LIMITED      | Too many requests          | Backoff and retry; request higher limits |
| 500  | INTERNAL           | Unexpected error           | Retry with jitter; include request\_id   |
| 503  | UNAVAILABLE        | Temporary outage           | Retry after a short delay                |

<Note>
  Include the <code>request\_id</code> (if present), timestamp (UTC), and a minimal cURL reproduction when contacting support.
</Note>


# Error Codes Overview
Source: https://docs.blockdb.io/troubleshooting/error-codes/home

Common BlockDB error categories and where to find specific codes.

<CardGroup>
  <Card title="API Errors" icon="terminal" href="/troubleshooting/error-codes/api/home">
    HTTP statuses and structured error responses from REST endpoints.
  </Card>

  <Card title="WSS Errors" icon="wireless" href="/troubleshooting/error-codes/wss/home">
    WebSocket close codes and connection diagnostics.
  </Card>

  <Card title="SFTP Errors" icon="server" href="/troubleshooting/error-codes/sftp/home">
    Authentication and transfer failures for archive delivery.
  </Card>
</CardGroup>


# SFTP Error Codes
Source: https://docs.blockdb.io/troubleshooting/error-codes/sftp/home

Authentication and transfer diagnostics for archive delivery via SFTP.

### Common SFTP Failures

| Symptom              | Likely Cause                           | Action                                      |
| -------------------- | -------------------------------------- | ------------------------------------------- |
| Permission denied    | Key mismatched or user not provisioned | Upload correct public key; confirm username |
| Connection timed out | Firewall or wrong host/port            | Allowlist host; verify port 22              |
| No such file         | Path incorrect or share not ready      | Confirm dataset path and provisioning       |
| Transfer stalls      | Network throttling                     | Resume or use smaller chunk size            |

<Note>
  Provide your username, target path, file name, and approximate timestamp when reporting SFTP issues.
</Note>


# WSS Error Codes
Source: https://docs.blockdb.io/troubleshooting/error-codes/wss/home

WebSocket close codes and connection troubleshooting for BlockDB streams.

### Close Codes

| Code | Name              | Meaning            | Action                                 |
| ---- | ----------------- | ------------------ | -------------------------------------- |
| 1000 | NORMAL\_CLOSURE   | Graceful shutdown  | Reconnect                              |
| 1001 | GOING\_AWAY       | Server restart     | Reconnect with backoff                 |
| 1008 | POLICY\_VIOLATION | Invalid auth/scope | Refresh token; verify scope            |
| 1011 | INTERNAL\_ERROR   | Server error       | Reconnect with jitter                  |
| 1013 | TRY\_AGAIN\_LATER | Backpressure       | Increase backoff; reduce subscriptions |

<Note>
  Use exponential backoff: 1s, 2s, 4s, 8s (max 30s)
</Note>


# Support Hub
Source: https://docs.blockdb.io/troubleshooting/home

Central place for troubleshooting, FAQs, and getting help with BlockDB.

<Card title="Contact support" icon="inbox" href="mailto:support@blockdb.io">
  Email us for help with incidents, access, or account issues.
</Card>

<CardGroup>
  <Card title="API troubleshooting" icon="terminal" href="/api-reference/guides/troubleshoot-api-errors">
    Diagnose common API errors and learn how to resolve them.
  </Card>

  <Card title="System status" icon="signal-bars" href="https://status.blockdb.io">
    Check real-time service availability and incident history.
  </Card>
</CardGroup>

<br />

<AccordionGroup>
  <Accordion title="What information should I include in a support ticket?">
    * **Request ID or correlation ID**: if available from response headers
    * **Endpoint and method**: e.g., GET /api/evm/blocks
    * **Timestamps and environment**: when it occurred and where (prod/stage)
    * **Samples**: redacted request/response bodies and headers
  </Accordion>

  <Accordion title="Expected response times">
    * **P1 (service down)**: immediate triage
    * **P2 (degraded/partial)**: within business hours
    * **P3 (usage/questions)**: next business day
  </Accordion>
</AccordionGroup>


# Raising a Support Ticket
Source: https://docs.blockdb.io/troubleshooting/raising-a-support-ticket

How to submit effective BlockDB support tickets for faster resolution.

<Info>
  For incidents and real-time service information, check <a href="https://status.blockdb.io">status.blockdb.io</a>. For access, billing, or technical issues email <a href="mailto:support@blockdb.io">[support@blockdb.io](mailto:support@blockdb.io)</a>.
</Info>

## Ticket Content Guidelines

Include the following details to help BlockDB engineers diagnose quickly and accurately:

<CardGroup>
  <Card title="Issue Description" icon="message-dots">
    Explain what you were doing when the issue occurred and how to reproduce it. Include the affected dataset(s) or endpoint(s) — for example: <code>POST /evm/logs</code>, <code>dataset: 0103\_logs</code>.
  </Card>

  <Card title="Error Messages" icon="circle-exclamation">
    Paste exact errors from responses, logs, or UI. Include HTTP status, error codes, and any response values if present.
  </Card>

  <Card title="Timing Information" icon="clock">
    Provide the time window (with timezone) when the issue occurred. Example: <code>2025-11-11 14:15-14:20 UTC</code>.
  </Card>

  <Card title="User Impact" icon="users">
    Clarify scope: single user, team, or production pipeline. Note whether it's blocking or degraded.
  </Card>

  <Card title="Document Reference" icon="link">
    Link to the relevant docs page or object identifiers (addresses, pool UIDs, tx hashes) that illustrate the problem.
  </Card>

  <Card title="Visual Evidence" icon="image">
    Add screenshots or short screen recordings showing the failure and settings used.
  </Card>
</CardGroup>

<Tip>
  If possible, include a minimal cURL that reproduces the issue:
</Tip>

```bash cURL theme={null}
curl -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chain_id": 1, "from_block": 123, "to_block": 456}'
```

## Understanding Priority Levels

Select the appropriate priority so we can triage effectively:

<AccordionGroup>
  <Accordion title="Low Priority" icon="arrow-down">
    Non-critical, no impact on daily work.

    * General questions
    * Feature requests
    * Future roadmap inquiries
  </Accordion>

  <Accordion title="Normal Priority" icon="arrow-right">
    Partial impact or inconvenience.

    * Minor bugs
    * Intermittent issues
    * Workarounds available
  </Accordion>

  <Accordion title="High Priority" icon="arrow-up">
    Significant impact on usage or timelines.

    * Production job degradation
    * Critical queries failing for a subset of inputs
    * No viable workaround
  </Accordion>

  <Accordion title="Urgent Priority" icon="alarm-exclamation">
    Immediate, business-critical impact.

    * Outage or complete stop of production workloads
    * Data corruption risk
    * Security concerns
  </Accordion>
</AccordionGroup>

<Note>
  Accurate priority helps the team triage efficiently. Over-escalation may delay truly critical responses across the queue.
</Note>


# Runbook · API Authentication Failures
Source: https://docs.blockdb.io/troubleshooting/runbooks/api-authentication-failures

Step-by-step recovery for 401/403 and API key access issues.

<Steps>
  <Step title="Verify Authorization header">
    Ensure requests include <code>Authorization: Bearer \<API\_KEY></code> and no stray whitespace or quotes around the key.
  </Step>

  <Step title="Check key and entitlements">
    Confirm the key is not revoked, copied fully from [dashboard.blockdb.io](https://dashboard.blockdb.io), and that your plan includes the datasets and chains you are calling. Create a new key or rotate if unsure.
  </Step>

  <Step title="Test with minimal cURL">
    <RequestExample>
      ```bash cURL theme={null}
      curl -i -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
        -H "Authorization: Bearer $BLOCKDB_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"chain_id":1,"from_block":1,"to_block":2}'
      ```
    </RequestExample>
  </Step>

  <Step title="Escalate with context">
    Share timestamp (UTC), <code>request\_id</code>, and a minimal reproduction to <a href="mailto:support@blockdb.io">support</a>.
  </Step>
</Steps>


# Runbook · Archive Delivery Failures
Source: https://docs.blockdb.io/troubleshooting/runbooks/archive-delivery-failures

Resolve SFTP and warehouse share issues for bulk datasets.

<Steps>
  <Step title="Confirm provisioning">
    Verify your organization and dataset access are active. Check onboarding email and share invites.
  </Step>

  <Step title="Validate credentials">
    For SFTP, ensure the correct username is registered. For warehouse shares, accept the share in your account.
  </Step>

  <Step title="Test connectivity">
    Attempt a directory listing and capture errors/timestamps to include in tickets.
  </Step>

  <Step title="Escalate with context">
    Provide hostname, path, sample filename, and the exact error output to support.
  </Step>
</Steps>


# Runbook · WSS Connection Issues
Source: https://docs.blockdb.io/troubleshooting/runbooks/wss-connection-issues

Stabilize WebSocket connections and interpret close codes.

<Steps>
  <Step title="Validate URL and TLS">
    Confirm the WSS endpoint, chain/stream, and TLS (wss\://) are correct.
  </Step>

  <Step title="Implement exponential backoff">
    Use 1s, 2s, 4s, 8s (max 30s), and add jitter to reduce thundering herd.
  </Step>

  <Step title="Authenticate promptly">
    Send any required auth message immediately after connect to avoid policy timeouts (1008).
  </Step>

  <Step title="Review close code">
    See <a href="/troubleshooting/error-codes/wss/home">WSS error codes</a> for guidance and actions.
  </Step>
</Steps>


# Service Limits
Source: https://docs.blockdb.io/troubleshooting/service-limits/home

Default rate limits and payload constraints; how to request increases.

### Defaults

* REST: concurrency and RPS are **plan-specific and account-wide**; they are **shared across all API keys** on the account (see [Rate limiting](/api-reference/overview/rate-limiting)). Responses include standard rate headers when applicable.
* Payload: request body and response size limits protect service stability.

<Note>
  Contact <a href="mailto:support@blockdb.io">support</a> for production increases. Provide expected RPS, concurrency, and dataset mix.
</Note>

### Best Practices

* Paginate queries using cursors
* Implement retries with backoff for 429/503 responses


# First-day FAQs
Source: https://docs.blockdb.io/user-guide/about-blockdb/first-day-faqs

Answers to the most common onboarding questions: access, authentication, limits, and support.

<AccordionGroup>
  <Accordion title="How do I get access?">
    Open a free account at <a href="https://accounts.blockdb.io/sign-up">Open Account</a>. You can sign up and get API keys on your own. For organization-specific or custom delivery setup, email <a href="mailto:support@blockdb.io">[support@blockdb.io](mailto:support@blockdb.io)</a>.
  </Accordion>

  <Accordion title="How do I authenticate API requests?">
    Use the `Authorization: Bearer YOUR_API_KEY` header. See <a href="/api-reference/overview/home">API Reference → Introduction</a> for examples.
  </Accordion>

  <Accordion title="What are the rate limits?">
    Your **requests-per-second (RPS)** limit depends on your **subscription plan**. See <a href="/pricing/home">Pricing</a> for what each plan includes.
  </Accordion>

  <Accordion title="How do I receive historical data in bulk?">
    Use Archive Delivery: SFTP, S3, Azure Blob, or warehouse shares (Snowflake, Redshift, BigQuery, Databricks). Start at <a href="/user-guide/archive-delivery/introduction">Archive Delivery</a>.
  </Accordion>

  <Accordion title="How fresh is the data?">
    See <a href="/data-catalog/overview/data-freshness">Data Freshness</a>. Real-time endpoints stream new blocks and logs as they arrive; archives update on defined SLAs.
  </Accordion>

  <Accordion title="Where can I see data schemas?">
    Browse the <a href="/data-catalog/evm/dataset-index">Dataset Index</a> and detailed EVM pages (Blocks, Transactions, Logs, Contracts, Function Results).
  </Accordion>

  <Accordion title="How do I report an incident or bug?">
    Open a ticket via email with endpoint, timestamps, request ID (if present), and sample request/response. See <a href="/troubleshooting/home">Support Hub</a>.
  </Accordion>
</AccordionGroup>

<Info>
  New to BlockDB? Start with the <a href="/user-guide/about-blockdb/quick-start-guide">Quick Start Guide</a>.
</Info>


# Quick Start Guide
Source: https://docs.blockdb.io/user-guide/about-blockdb/quick-start-guide

Get started with BlockDB in minutes — connect, authenticate, run your first onchain data query, and verify lineage.

## Video walkthrough

**BlockDB Free Account, API Key & First Query in 2 Minutes** — sign up, create a key, and run your first query:

<iframe title="BlockDB Free Account, API Key & First Query in 2 Minutes" />

<Steps>
  <Step title="Open account and create an API key">
    Open a free account at [accounts.blockdb.io](https://accounts.blockdb.io/sign-up) to create an **API key**.

    <Check>
      You can have up to **five** active keys per account—use separate keys for production and staging when possible. Store keys only in environment variables or a secret manager (for example `BLOCKDB_API_KEY`) and never commit them to version control. See [Authorization](/api-reference/overview/authorization) for key rotation and [Rate Limiting](/api-reference/overview/rate-limiting) for RPS and compute units.
    </Check>
  </Step>

  <Step title="Call the API with your key">
    Use **`Authorization: Bearer <API_KEY>`** on every request. No token endpoint and no refresh flow—the key from the dashboard is the credential. Example: query a small block range on Ethereum mainnet:

    ```bash theme={null}
    curl -X POST https://api.blockdb.io/v1/evm/raw/blocks \
      -H "Authorization: Bearer $BLOCKDB_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "chain_id": 1,
        "from_block": 21000000,
        "to_block": 21000001,
        "limit": 1
      }'
    ```

    A successful response returns `{ "data": [...], "cursor": null, "page_count": 1 }`. If you get a `401`, confirm the key is copied correctly, not revoked, and still allowed for that dataset (see [Authorization](/api-reference/overview/authorization)).

    <Check>
      You received a JSON response with a `data` array containing block records.
    </Check>
  </Step>

  <Step title="Explore the data catalog">
    Use the [Dataset Index](/data-catalog/evm/dataset-index) to find the tables and schemas relevant to your use case. Each dataset page documents available fields, lineage keys, and example queries.
  </Step>
</Steps>

<Tip>
  For bulk workloads, start with an archive backfill, then switch to API/WebSocket for deltas.
</Tip>


# What is BlockDB?
Source: https://docs.blockdb.io/user-guide/about-blockdb/what-is-blockdb

BlockDB delivers verifiable, real-time onchain data for quant funds and AI teams. EVM/SVM datasets, delivery options, and traceable row identifiers.

<CardGroup>
  <Card title="Institutional-grade data" icon="database">
    Curated EVM/SVM datasets engineered for accuracy, coverage, and time-series analysis.
  </Card>

  <Card title="Multiple delivery modes" icon="cloud-download">
    Archive bulk exports, warehouse shares, real-time APIs, WebSocket streams, and visualization connectors.
  </Card>

  <Card title="Traceable data" icon="shield-check">
    Stable identifiers and on-chain coordinates so you can reconcile exports and APIs with blocks, transactions, and logs.
  </Card>
</CardGroup>

## How BlockDB works

<Frame>
  <img alt="How BlockDB works — from raw on-chain events through indexing, verification, and delivery to end users." />
</Frame>

## Who uses BlockDB

* **Quants**: backtest strategies with deep historical liquidity, prices, and market microstructure
* **Web3 developers**: build apps with reliable On-chain Data Access Layer
* **Analysts**: monitor markets, volatility, and flows with verified datasets across chains

## What data is available

* **Raw chain data**: blocks, transactions, logs, contracts, function results
* **Tokens & pools**: ERC-20, liquidity pools and reserves
* **Pricing**: swap prints, token-to-token OHLC and VWAP, token-to-USD VWAP
* **Analytics**: pool yields, TVL, flash loans, arbitrage paths and opportunities

<Note>
  See the <a href="/data-catalog/evm/dataset-index">Dataset Index</a> for a complete list.
</Note>

## How you can access it

* **Archive bulk delivery**: SFTP, S3, Azure Blob, Snowflake/Redshift/BigQuery shares, Databricks Delta
* **Real time**: REST API, WebSocket, and MCP
* **Visualization**: Tableau and Power BI connectors

<Check>
  New to the platform? Start with <a href="/user-guide/about-blockdb/quick-start-guide">Quick Start Guide</a> or open an account at [Open Account](https://accounts.blockdb.io/sign-up) to get started.
</Check>


# Amazon Redshift Share
Source: https://docs.blockdb.io/user-guide/archive-delivery/amazon-redshift-share

Access BlockDB blockchain archives via Redshift Serverless data sharing — no file handling or ETL required.

## Overview

Redshift data sharing gives you ready-to-query BlockDB tables inside your AWS account. BlockDB operates a producer cluster that exposes schemas (blocks, transactions, pricing, etc.) to your Redshift workgroups, keeping them synchronized without manual ETL.

## Getting Access

1. Provide your AWS account ID and Redshift namespace/ workgroup name to [support@blockdb.io](mailto:support@blockdb.io).
2. BlockDB creates a datashare (e.g., `blockdb_archive_share`) and associates it with your namespace.
3. In your account, run:

```sql theme={null}
CREATE DATABASE blockdb_prod FROM DATASHARE blockdb_archive_share OF ACCOUNT '123456789012';
```

4. Grant usage to teams/roles that need the data.

## Table Details

* Tables mirror the schemas in `/BlockDb.Postgres.Tables.Public` including `_tracing_id`.
* Views are provided for common aggregations (e.g., daily price bars) so you can query immediately.
* Because the data lives in the producer account, you only pay for compute when you query it.

## Operational Considerations

* Use materialized views or `COPY` into your own schemas if you need write access or to join with private data.
* Track freshness with queries against `_updated_at`; compare against [Data Freshness](/data-catalog/overview/data-freshness) expectations.
* If you require extra datasets or regions, coordinate with BlockDB—shares can span multiple AWS regions with AWS RAM.

<Callout icon="lightbulb">
  For workloads that also need streaming CDC, combine the Redshift share with [Real Time Channels](/user-guide/real-time-delivery/introduction) so inserts land in your lakehouse or event bus.
</Callout>


# Amazon S3 Archive Delivery
Source: https://docs.blockdb.io/user-guide/archive-delivery/amazon-s3

BlockDB writes EVM blockchain dataset exports directly to your S3 bucket — scheduled, partitioned, and lifecycle-controlled.

## Why S3

* Keep ownership of the data inside your AWS account.
* Apply lifecycle, encryption, or replication policies that match your governance model.
* Land both full-history archives and incremental refreshes in the same layout you use internally.

## Delivery Model

| Item             | Details                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **Format**       | Parquet (default) or CSV; schema aligned with `/BlockDb.Postgres.Tables.Public`.              |
| **Partitioning** | `dataset_id=/0101/chain_id=1/date=2024-01-01/part-*.parquet`.                                 |
| **Access**       | BlockDB assumes an IAM role (`sts:AssumeRole`) or uses access keys scoped to a folder prefix. |
| **Integrity**    | Each object has an accompanying `.manifest.json` listing row counts and SHA-256 hashes.       |

## Setup Steps

1. Create (or reuse) an S3 bucket in the region closest to your workloads; enable versioning if you want change history.
2. Provision an IAM role with `s3:PutObject`, `s3:AbortMultipartUpload`, and `s3:ListBucket` on the target prefix. Share the ARN with BlockDB.
3. Send dataset IDs, chain coverage, and initial backfill ranges to [support@blockdb.io](mailto:support@blockdb.io).
4. Optionally enable cross-region replication or Glacier policies—BlockDB's writes respect your bucket policy.

## Consuming the Data

* Use AWS Glue or dbt to catalog the partitions and hydrate warehouse tables created from the BlockDB SQL scripts.
* Track ingestion by reading the manifest files and comparing against `_tracing_id` ranges.
* If you need mutable tables or streaming CDC, pair S3 archives with the [Real Time Channels](/user-guide/real-time-delivery/introduction) strategy.

<Callout icon="lightbulb">
  Coordinate bucket naming and encryption (SSE-KMS, SSE-S3, or client-side) before the first drop. KMS keys must grant BlockDB's IAM role encrypt/decrypt permissions.
</Callout>


# Azure Blob Archive Delivery
Source: https://docs.blockdb.io/user-guide/archive-delivery/azure-blob-storage

Receive BlockDB EVM blockchain datasets through ADLS Gen2 containers secured with service principals — partitioned, lifecycle-managed.

## Overview

Azure Blob Storage mirrors the S3 experience but keeps data inside your Azure subscription. BlockDB writes archives into an ADLS Gen2 container using a dedicated service principal so you can pipe the files into Synapse, Fabric, or Databricks.

## Delivery Specs

* **Containers:** One per environment (e.g., `blockdb-prod-archives`). BlockDB targets a specific path such as `/datasets/0101_blocks_v1/`.
* **Authentication:** OAuth client credentials (service principal) with `Storage Blob Data Contributor` on the container.
* **Formats:** Parquet (recommended) or CSV; naming matches `dataset_id=0101/date=2024-01-01/part-*.parquet`.
* **Metadata:** Manifests stored alongside the data with row counts, checksums, and `_tracing_id` ranges.

## Provisioning Checklist

1. Create the storage account (enable hierarchical namespace for ADLS Gen2).
2. Register a service principal and grant it access to the container path.
3. Share the tenant ID, client ID, and secret plus the target container URL with [support@blockdb.io](mailto:support@blockdb.io).
4. Specify datasets, chains, and start/end timestamps; BlockDB schedules the first export drop.

## Integrating Downstream

* Use Synapse Pipelines or Azure Data Factory to copy the data into dedicated SQL pools.
* Mount the container to Databricks and hydrate tables defined in `/BlockDb.Postgres.Tables.Public`.
* Monitor ingestion by reading the manifest blobs and reconciling counts with your warehouse.

<Callout icon="lightbulb">
  If you enforce customer-managed keys, grant the service principal `get` permissions on the Key Vault secret so BlockDB can encrypt uploads.
</Callout>


# Databricks Delta Share
Source: https://docs.blockdb.io/user-guide/archive-delivery/databricks-delta-share

Consume BlockDB blockchain datasets natively in Delta format via Databricks Unity Catalog — no ETL or file handling required.

## Benefits

* Zero-copy sharing: BlockDB exposes tables through Delta Sharing so you query them from any Databricks workspace (or other compatible client).
* Unity Catalog integration: Access is enforced via share-level permissions, keeping audits centralized.
* Supports both archive snapshots and incremental change data (`table_changes()`), ideal for lakehouse pipelines.

## Getting Connected

1. Provide your Unity Catalog metastore ID and share invite email to [support@blockdb.io](mailto:support@blockdb.io).
2. BlockDB sends a Delta Share invitation (e.g., `blockdb_archive`).
3. Accept the share in Databricks:

```sql theme={null}
CREATE SHARE IF NOT EXISTS blockdb_archive SHARE_ID 'xxxxxxxx-xxxx';
CREATE RECIPIENT IF NOT EXISTS blockdb_team USING IDENTITY 'your-uc-principal';
GRANT USAGE ON SHARE blockdb_archive TO RECIPIENT blockdb_team;
```

4. Create a catalog in your workspace to expose the shared tables.

## Table Layout

* Each dataset (blocks, transactions, pricing, etc.) appears as a Delta table with the same schema as `/BlockDb.Postgres.Tables.Public`.
  -, `_tracing_id`, `_created_at`, `_updated_at`, and verification columns are preserved.
* Change data can be accessed via:

```sql theme={null}
SELECT * FROM table_changes(blockdb_archive.blocks_0101, 'latest');
```

## Operational Guidance

* Use Auto Loader or streaming jobs to merge the shared tables into your production catalogs if you need custom partitioning.
* Monitor `_updated_at` and compare against [Data Freshness](/data-catalog/overview/data-freshness) commitments.
* Keep an eye on Unity Catalog grants to ensure only intended principals can read the shared datasets.

<Callout icon="lightbulb">
  If you also rely on cloud buckets (S3/Azure/GCS), Delta Share can coexist—use it for analytics while buckets feed downstream archival storage.
</Callout>


# Google BigQuery Archive Delivery
Source: https://docs.blockdb.io/user-guide/archive-delivery/google-bigquery

Access BlockDB EVM blockchain datasets in Google BigQuery via Authorized Views or scheduled Transfer Service loads — no ETL required.

## Delivery Modes

| Mode                 | When to Choose                                                                   | How It Works                                                    |
| -------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Authorized View**  | Need always-fresh tables without owning storage.                                 | BlockDB shares a dataset in its project; you query it directly. |
| **Transfer Service** | Want the data inside your own project for transformation or long-term retention. | Scheduled jobs copy tables/partitions into your project.        |

At launch, datasets `0101-0105` (ledger/execution) are GA; pricing datasets follow shortly.

## Onboarding Steps

1. Share your GCP project ID and region with [support@blockdb.io](mailto:support@blockdb.io).
2. For Authorized Views, grant BlockDB's service account `bigquery.dataViewer` on the consuming project. For Transfer Service, grant `bigquery.admin` on the target dataset or create a dedicated service account.
3. Confirm dataset list, chain coverage, and schedule (daily/hourly).
4. BlockDB configures the share or transfer job; you receive dataset names like `blockdb_prod.ledger_0101_blocks_v1`.

## Usage Patterns

* Join BlockDB tables with your proprietary data in BigQuery SQL; leverage `_tracing_id` for lineage.
* Export slices to GCS if you need to interop with other warehouses.
* Use scheduled queries or dbt to materialize curated marts downstream.

## Validation & Monitoring

* Compare row counts with the [Dataset Index](/data-catalog/evm/dataset-index) or manifest metadata delivered via auxiliary tables.
* Alert when `_updated_at` drifts from the SLAs in [Access & SLA](/data-catalog/overview/access-and-sla).
* For Transfer Service, monitor job status in Cloud Console and set up notifications for failures.

<Callout icon="lightbulb">
  If you require low-latency updates, combine BigQuery archive loads with REST API polling or streaming buckets described under [Real Time Channels](/user-guide/real-time-delivery/introduction).
</Callout>


# Introduction
Source: https://docs.blockdb.io/user-guide/archive-delivery/introduction

Bootstrap your warehouse with BlockDB's historical exports before enabling live feeds.

## Delivery Options

| Channel                    | Best for                                              | Status       | Guide                                                                         |
| -------------------------- | ----------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- |
| **REST API**               | Filtered pulls and low-latency ad-hoc queries         | ✅ Supported  | [REST API](/user-guide/archive-delivery/rest-api)                             |
| **SFTP**                   | Managed nightly drops with schema manifests           | 🟡 Beta      | [SFTP](/user-guide/archive-delivery/sftp)                                     |
| **Amazon S3**              | Cross-region replication into customer-owned buckets  | ✅ On Request | [Amazon S3](/user-guide/archive-delivery/amazon-s3)                           |
| **Azure Blob Storage**     | ADLS Gen2 integration via service principal           | ✅ On Request | [Azure Blob Storage](/user-guide/archive-delivery/azure-blob-storage)         |
| **Snowflake Share**        | Zero-copy Secure Data Share to your Snowflake account | ✅ On Request | [Snowflake Share](/user-guide/archive-delivery/snowflake-share)               |
| **Amazon Redshift**        | Data sharing via Redshift Serverless                  | ✅ On Request | [Amazon Redshift](/user-guide/archive-delivery/amazon-redshift-share)         |
| **Google BigQuery**        | Authorized view or transfer service                   | ✅ On Request | [Google BigQuery](/user-guide/archive-delivery/google-bigquery)               |
| **Databricks Delta Share** | Native Delta Sharing tables                           | ✅ On Request | [Databricks Delta Share](/user-guide/archive-delivery/databricks-delta-share) |

<Note>
  Most customers start with a full-history archive drop to bootstrap their warehouse, then layer on Managed Bucket Slices or CDC Streams for ongoing freshness. Use `_tracing_id` to reconcile records consistently across channels.
</Note>


# MCP
Source: https://docs.blockdb.io/user-guide/archive-delivery/mcp

BlockDB MCP integration — let autonomous AI agents request live EVM blockchain data via secure MCP sessions. LLM-ready onchain data.

## What Is MCP?

Model Context Protocol (MCP) is BlockDB's secure channel for AI agents and service accounts that need curated responses rather than raw streams. MCP sessions expose high-level operations (e.g., “fetch liquidity deltas for pool X”) and return structured payloads derived from the same datasets documented in the Data Catalog.


# REST API
Source: https://docs.blockdb.io/user-guide/archive-delivery/rest-api

BlockDB Historic REST API — cursor-based, pull-based blockchain data delivery for EVM datasets. Low-latency and paginated.

## Why Use the REST API

* Sub-second access to any dataset supported by the [EVM API suite](/api-reference/overview/home).
* Works behind outbound-only firewalls—no need to expose webhooks.
* Fine-grained filters reduce egress costs; pull only the chains, blocks, or pools you need.

## Core Concepts

* **Endpoints:** Each dataset has a dedicated path (e.g., `/evm/raw/blocks`, `/evm/prices/spot/crypto/ohlc`). All requests are `POST`.
* **Pagination:** Responses contain `cursor` and `count`. Pass the `cursor` from the previous response to request the next page.
* **Ordering:** Use range filters (`range.from`/`range.to`, `_updated_at` windows, sequence numbers) to advance chronologically.
* **Authentication:** API keys (`Authorization: Bearer <API_KEY>`), managed in [dashboard.blockdb.io](https://dashboard.blockdb.io). Rotate or revoke keys per your security policy.

## Example Poller

```bash theme={null}
curl -X POST https://api.blockdb.io/v1/evm/raw/blocks \
  -H "Authorization: Bearer $BLOCKDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": 1,
    "range": {"from": 19000000},
    "fields": ["number","hash","timestamp","_tracing_id"],
    "cursor": "'$CURSOR'"
  }'
```

Pseudo-loop:

1. Call the endpoint with `cursor=null` to seed the stream.
2. Persist the returned `cursor` and latest `_updated_at`.
3. Re-run every few seconds/minutes; include `cursor` to continue where you left off.
4. On failure, replay using the last committed cursor (idempotent).

## Best Practices

* **Backoff:** Implement exponential backoff and respect rate limits documented in your contract.
* **Schema evolution:** Subscribe to [Schema Governance](/data-catalog/overview/schema-governance) so pollers can handle new fields gracefully.
* **Verification:** Periodically reconcile sampled `_tracing_id` values and block anchors with on-chain data or your archival copies.
* **Upserts:** Merge by dataset-specific key + `_tracing_id` to avoid duplication.

<Callout icon="lightbulb">
  Use separate pollers per dataset family (ledger, pricing, lineage) to prevent one noisy workload from blocking another.
</Callout>


# SFTP Archive Delivery
Source: https://docs.blockdb.io/user-guide/archive-delivery/sftp

BlockDB delivers nightly EVM blockchain dataset snapshots via managed SFTP — fast historical backfills, no cloud infrastructure required.

## When to Use

Choose SFTP when you want a simple, firewall-friendly way to ingest BlockDB archives without wiring up cloud object storage. Each nightly drop includes the full dataset partitions you requested plus manifest files with row counts and checksums.

## Delivery Characteristics

* **Cadence:** Nightly (hourly bursts available for priority datasets).
* **Format:** Compressed Parquet or CSV files that mirror the schemas in `/BlockDb.Postgres.Tables.Public`.
* **Retention:** Files remain available for 30 days on the SFTP server; sync them to cold storage if you need longer retention.

## Setup Checklist

1. Provide an allow-listed IP, SSH public key, and desired folder layout to [support@blockdb.io](mailto:support@blockdb.io).
2. Confirm the dataset IDs and chains you need (use the [Dataset Index](/data-catalog/evm/dataset-index) + [Coverage](/data-catalog/overview/coverage)).
3. Harden your internal user account—BlockDB provisions read-only SFTP access scoped to your datasets.

## File Layout

```
/0101_blocks_v1/
  2024-01-01/
    part-000.gz.parquet
    part-001.gz.parquet
  manifest.json
/0102_transactions_v1/
  ...
```

* `manifest.json` lists row counts, SHA-256 hashes, and `_tracing_id` ranges per file.
* Files are partitioned by export date; use `_updated_at` if you need to detect late-arriving records.

## Post-Ingest Validation

1. Load the data using the DDL scripts in `/BlockDb.Postgres.Tables.Public`.
2. Compare row counts against the manifest and spot-check `_tracing_id` / block anchors against your own node or [support@blockdb.io](mailto:support@blockdb.io).
3. Record ingestion status in your observability system so you can layer [Real Time Delivery](/user-guide/real-time-delivery/introduction) on top once archives are stable.


# Snowflake Share
Source: https://docs.blockdb.io/user-guide/archive-delivery/snowflake-share

Access BlockDB blockchain datasets natively in Snowflake via Secure Data Sharing — no ETL required, CDC streams available.

## BlockDB on Snowflake Marketplace

Browse and request access to BlockDB datasets directly from the Snowflake Marketplace:

<Card title="BlockDB on Snowflake Marketplace" icon="snowflake" href="https://app.snowflake.com/marketplace/providers/GZ1MFZQTCWF/BlockDB">
  View all available BlockDB datasets, request a trial, and subscribe — no file handling or ETL required.
</Card>

## Why Use Snowflake Share

* Avoid managing raw files—datasets appear as ready-to-query tables inside your Snowflake account.
* Gain access to change streams for incremental processing without building your own CDC logic.
* Keep data in sync automatically; BlockDB operates the provider account and updates propagate in minutes.

## Provisioning Flow

1. Provide your Snowflake account locator (e.g., `xy12345.us-east-1`) to [support@blockdb.io](mailto:support@blockdb.io).
2. BlockDB creates a share containing the dataset schemas (`0101_blocks_v1`, `0102_transactions_v1`, etc.) and grants it to your account.
3. You create a database from the share:

```sql theme={null}
CREATE DATABASE blockdb_prod FROM SHARE blockdb_org.blockdb_share;
```

4. (Optional) Enable streams on critical tables:

```sql theme={null}
CREATE OR REPLACE STREAM block_stream ON TABLE blockdb_prod.public."0101_blocks_v1";
```

## Table Structure

* Column names and types match the SQL in `/BlockDb.Postgres.Tables.Public`.
* `_tracing_id`, `_created_at`, `_updated_at`, and verification columns are included for lineage.
* Each dataset sits in its own schema so you can apply RBAC at a granular level.

## Operational Tips

* Use Snowpipe or tasks to copy data from the shared tables into your production schema if you need transformations.
* Streams capture inserts/updates so you can power near-real-time analytics or downstream event buses.
* Monitor freshness by comparing `_updated_at` against the SLAs defined in [Access & SLA](/data-catalog/overview/access-and-sla).

<Callout icon="lightbulb">
  Pair the Snowflake share with your own reconciliation queries or [support@blockdb.io](mailto:support@blockdb.io) to validate `_tracing_id` samples before critical reporting runs.
</Callout>


# Introduction
Source: https://docs.blockdb.io/user-guide/real-time-delivery/introduction

Keep BlockDB datasets current with incremental feeds and verification hooks.

## Delivery Options

| Channel       | Best for                                               | Status       | Guide                                                 |
| ------------- | ------------------------------------------------------ | ------------ | ----------------------------------------------------- |
| **WebSocket** | Push-based live streams with sub-150 ms latency        | 🟡 Beta      | [WebSocket](/user-guide/real-time-delivery/websocket) |
| **Protobuf**  | Binary-encoded WebSocket streams for ultra-low latency | ✅ On Request | [Protobuf](/user-guide/real-time-delivery/protobuf)   |

<Note>
  All streams preserve `_tracing_id` so you can correlate live events back to archive records. See [Data Lineage](/data-catalog/overview/data-lineage) for details.
</Note>


# Protobuf
Source: https://docs.blockdb.io/user-guide/real-time-delivery/protobuf

Binary-encoded WebSocket streams using Protocol Buffers — available on request for latency-critical and high-frequency trading applications.

## Overview

BlockDB's WebSocket channel already delivers real-time EVM data with sub-150 ms latency. For latency-critical applications — high-frequency trading, co-located execution, or ultra-low-latency signal pipelines — JSON serialization overhead can become a bottleneck.

Because the transport layer is already WebSocket, switching to **Protocol Buffers (Protobuf)** binary encoding requires no infrastructure change on either side. The same streams, the same subscription protocol, the same `chain_id` and `dataset_id` identifiers — with a binary payload instead of JSON.

***

## Why Protobuf for HFT

<CardGroup>
  <Card title="Smaller payloads" icon="minimize">
    Binary encoding typically reduces message size by 30-70% compared to JSON, reducing bandwidth and kernel buffer pressure at high throughput.
  </Card>

  <Card title="Faster deserialization" icon="gauge-max">
    Protobuf deserialization is significantly faster than JSON parsing — measurable in microseconds per message at the volumes HFT systems process.
  </Card>

  <Card title="Schema-defined contracts" icon="file-contract">
    `.proto` definitions give you a typed, versioned contract for every stream payload — no runtime field discovery, no string parsing.
  </Card>
</CardGroup>

***

## Availability

Protobuf encoding is available **on request**. To enable it for your account:

1. Contact [support@blockdb.io](mailto:support@blockdb.io) with the subject **"Protobuf stream access"**
2. Specify the chain IDs and dataset IDs you need
3. BlockDB will provide the `.proto` schema files and a binary-mode endpoint

<Note>
  Protobuf streams share the same subscription lifecycle as JSON WebSocket streams. See the [WebSocket page](/user-guide/real-time-delivery/websocket) for connection, authentication, and subscription details.
</Note>

***

## What Changes vs JSON WebSocket

|                       | JSON WebSocket                   | Protobuf WebSocket                 |
| :-------------------- | :------------------------------- | :--------------------------------- |
| Encoding              | UTF-8 JSON                       | Binary (Protobuf wire format)      |
| Message size          | Baseline                         | \~30-70% smaller                   |
| Deserialization       | JSON parser                      | Generated Protobuf bindings        |
| Schema                | Documented in data catalog       | `.proto` files provided by BlockDB |
| Transport             | `wss://api.blockdb.io/v1/evm/`   | Dedicated binary endpoint          |
| Subscription protocol | JSON `subscribe` / `unsubscribe` | Same JSON control messages         |

***

## Contact

To request Protobuf stream access or discuss throughput requirements for your HFT setup, reach out at [support@blockdb.io](mailto:support@blockdb.io).


# WebSocket
Source: https://docs.blockdb.io/user-guide/real-time-delivery/websocket

Push-based blockchain data streams via WebSocket — EVM blocks, logs, liquidity & pricing events with sub-150 ms latency.

## Overview

The WebSocket channel (beta) delivers real-time payloads as soon as BlockDB finalizes them — ideal for trading, monitoring, or alerting stacks that can't wait for polling intervals. Events mirror the schemas in the [data catalog](/data-catalog/evm/dataset-index) and preserve `_tracing_id` so you can reconcile back to archives.

<Frame>
  <img alt="BlockDB WebSocket processing time — end-to-end latency from on-chain finalization to payload delivery." />
</Frame>

<Note>
  WebSocket delivery is currently in beta. For issues or throughput requirements, contact [support@blockdb.io](mailto:support@blockdb.io).
</Note>

***

## Endpoint & Authentication

| Environment | Protocol | Endpoint                       |
| :---------- | :------- | :----------------------------- |
| Production  | `WSS`    | `wss://api.blockdb.io/v1/evm/` |

Authenticate during the WebSocket handshake using a Bearer token:

```http theme={null}
GET /v1/evm/ HTTP/1.1
Host: api.blockdb.io
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer <YOUR_API_KEY>
```

If your client cannot send custom headers during the handshake, pass the key as a query parameter:

```
wss://api.blockdb.io/v1/evm/?api_key=YOUR_API_KEY
```

***

## Quickstart

### 1) Connect & subscribe

<CodeGroup>
  ```bash bash theme={null}
  export BLOCKDB_API_KEY="..."
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'
  ```

  ```python Python theme={null}
  import os, json, websocket

  def on_open(ws):
      ws.send(json.dumps({
          "action": "subscribe",
          "chain_id": 1,
          "dataset_id": "0101",
          "params": {}
      }))

  def on_message(ws, msg):
      print(msg)

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_open=on_open,
      on_message=on_message,
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { Authorization: `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      chain_id: 1,
      dataset_id: '0101',
      params: {}
    }));
  });

  ws.on('message', (data) => console.log(data.toString()));
  ```
</CodeGroup>

### 2) Server acknowledgement

```json theme={null}
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}
```

### 3) Live update message

Every data payload follows this envelope:

```json theme={null}
{
  "chain_id": 1,
  "dataset_id": "0101",
  "is_reorg": false,
  "data": {
    "block_number": 12345678,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "timestamp_utc": "2025-11-11T18:42:15.123Z",
    "_tracing_id": "010100000000000000000000000000000000",
    "_is_reorg": false
  }
}
```

### 4) Unsubscribe

Stop a stream without closing the connection:

```json theme={null}
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101"
}
```

***

## Available Streams

Subscribe using `dataset_id` — IDs match the [data catalog](/data-catalog/evm/dataset-index) and REST API identifiers.

| Dataset ID | Stream                                                                       |
| :--------- | :--------------------------------------------------------------------------- |
| `0101`     | [Blocks](/wss-reference/evm/primitives/blocks)                               |
| `0102`     | [Transactions](/wss-reference/evm/primitives/transactions)                   |
| `0103`     | [Logs](/wss-reference/evm/primitives/logs)                                   |
| `0111`     | [Internal transactions](/wss-reference/evm/primitives/internal-transactions) |
| `0121`     | [Contracts](/wss-reference/evm/primitives/contracts)                         |
| `0122`     | [Function results](/wss-reference/evm/primitives/function-results)           |
| `0201`     | [ERC-20 tokens](/wss-reference/evm/entities/tokens-erc20)                    |
| `0202`     | [ERC-721 tokens](/wss-reference/evm/entities/tokens-erc721)                  |
| `0203`     | [ERC-1155 tokens](/wss-reference/evm/entities/tokens-erc1155)                |
| `0211`     | [Liquidity pools](/wss-reference/evm/entities/pools)                         |
| `0212`     | [Fee terms](/wss-reference/evm/entities/fee-terms)                           |
| `0301`     | [Reserves](/wss-reference/evm/reserves/reserves)                             |
| `0302`     | [Swap prints](/wss-reference/evm/prices/crypto/prices-spot-prints)           |
| `0303`     | [Swap fees](/wss-reference/evm/swaps/swap-fees)                              |
| `0304`     | [Token transfers](/wss-reference/evm/transfers/token-transfers)              |
| `0305`     | [Flash loan prints](/wss-reference/evm/flash-loans/flash-loan-prints)        |
| `0404`     | [OHLC](/wss-reference/evm/prices/crypto/prices-spot-ohlc)                    |
| `0405`     | [VWAP](/wss-reference/evm/prices/crypto/prices-spot-vwap)                    |
| `0501`     | [Fiat VWAP (USD)](/wss-reference/evm/prices/fiat/prices-spot-vwap-fiat)      |
| `0601`     | [TVL USD](/wss-reference/evm/tvl/tvl-usd)                                    |
| `0701`     | [Arb paths](/wss-reference/evm/arbitrage/arb-paths)                          |
| `0702`     | [Arb path status](/wss-reference/evm/arbitrage/arb-path-status)              |
| `0801`     | [Arb opportunities](/wss-reference/evm/arbitrage/arb-opportunities)          |
| `0411`     | [Yields](/wss-reference/evm/yields/yields)                                   |

***

## Connection Behavior

| Behavior             | Detail                                                                                                                                                      |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Heartbeats**       | Server sends periodic `ping` frames. Respond with `pong` (most libraries handle this automatically). Connections idle for more than 60 s may be terminated. |
| **Reconnection**     | On disconnect, implement exponential backoff before reconnecting.                                                                                           |
| **Message ordering** | Messages within a single stream are delivered in processing order.                                                                                          |
| **Reorg handling**   | When a chain reorganization occurs, affected messages include `"_is_reorg": true`. Use `_tracing_id` to correlate with archive records.                     |

***

## Full Reference

<CardGroup>
  <Card title="WSS Introduction" icon="book-open" href="/wss-reference/overview/introduction">
    Protocol details: authentication, subscription lifecycle, and message format.
  </Card>

  <Card title="Quickstart" icon="rocket-launch" href="/wss-reference/overview/quickstart">
    Full code examples in bash, Python, Node.js, Go, .NET, and C.
  </Card>

  <Card title="EVM Streams Overview" icon="list" href="/wss-reference/evm/overview">
    Complete stream matrix with links to per-dataset schema pages.
  </Card>

  <Card title="Protobuf (HFT)" icon="bolt" href="/user-guide/real-time-delivery/protobuf">
    Binary-encoded streams for latency-critical and high-frequency trading applications.
  </Card>
</CardGroup>


# Arbitrage Opportunities
Source: https://docs.blockdb.io/wss-reference/evm/arbitrage/arb-opportunities

Subscribe to arbitrage opportunity snapshots (per-path profit estimates at on-chain positions).

## Overview

* **Dataset ID:** [`0901 - Arbitrage Opportunities`](/data-catalog/evm/arbitrage/arb-opportunities)
* **Description:** Opportunities computed for active paths at a specific `(block_number, tx_index, log_index)`; ties to `path_id` and `is_reversed`.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Arb-Opportunities)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filters: 32-byte `path_id` values (hex string, no `0x` prefix).
</ParamField>

## Message Fields

Payload fields mirror `blockdb_evm.b0901_arb_opportunities_v1` (addresses and binary ids as hex strings without `0x` in JSON).

<ResponseField name="block_number" type="number">
  Observation block.
</ResponseField>

<ResponseField name="block_time" type="string">
  UTC timestamp of the observation (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="path_id" type="string">
  32-byte path id (hex).
</ResponseField>

<ResponseField name="is_reversed" type="boolean">
  `true` if the path was evaluated in the reversed direction.
</ResponseField>

<ResponseField name="pool_uids" type="string[]">
  Pool UIDs in evaluated (directional) order (hex).
</ResponseField>

<ResponseField name="token_path" type="string[]">
  Token addresses in evaluated order (hex).
</ResponseField>

<ResponseField name="amounts" type="string[]">
  Per-hop amounts as decimal strings, aligned with `token_path`.
</ResponseField>

<ResponseField name="profit_in_tokens" type="string">
  Estimated profit in `token_path[0]` units (decimal string).
</ResponseField>

<ResponseField name="token_vwap_usd" type="string">
  USD price of `token_path[0]` (decimal string).
</ResponseField>

<ResponseField name="profit_in_usd" type="string">
  Estimated profit in USD (decimal string).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row tracing id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent tracing ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Last update timestamp (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0901", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0901\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0901\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0901",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0901',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0901", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0901",
    "is_reorg": false,
    "data": {
      "block_number": 21000500,
      "block_time": "2025-11-11T12:00:00Z",
      "tx_index": 8,
      "log_index": 4,
      "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
      "is_reversed": false,
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "11b815acc87f6f89741a636d1ebfcea40876f8f0000000000000000000000000"
      ],
      "token_path": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
      ],
      "amounts": [
        "1000000000000000000",
        "3500000000",
        "1000500000000000000"
      ],
      "profit_in_tokens": "50000000000000000",
      "token_vwap_usd": "3200.50",
      "profit_in_usd": "160.025",
      "_tracing_id": "0901c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0801c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T12:00:05Z",
      "_updated_at": "2025-11-11T12:00:05Z"
    }
  }
  ```
</CodeGroup>


# Arbitrage Path Status
Source: https://docs.blockdb.io/wss-reference/evm/arbitrage/arb-path-status

Subscribe to path active/inactive status events.

## Overview

* **Dataset ID:** [`0802 - Arb Path Status`](/data-catalog/evm/arbitrage/arb-paths#arb-path-status-b0801_arb_path_status_v1)
* **Description:** Path status events (`b0801_arb_path_status_v1`): active/inactive transitions keyed by `(path_id, block_number, tx_index, log_index)`; `trigger_pool_uid` identifies the pool whose TVL/state change produced the event.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Arb-Path-Status)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filters: 32-byte `path_id` values (hex string, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="path_id" type="string">
  Path id (hex); FK to `b0801_arb_paths_v1.path_id`.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block of the status event.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Path active flag after the event.
</ResponseField>

<ResponseField name="trigger_pool_uid" type="string">
  Pool whose change triggered the status event (hex).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Unique tracing ID (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent tracing IDs (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0802", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0802\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0802\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0802",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0802',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0802", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0802",
    "is_reorg": false,
    "data": {
      "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
      "block_number": 21000800,
      "block_time": "2025-11-11T14:00:00Z",
      "tx_index": 5,
      "log_index": 2,
      "is_active": true,
      "trigger_pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "_tracing_id": "0802c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0801c0ffee000000000000000000000000000000000000000000000000000001"
      ]
    }
  }
  ```
</CodeGroup>


# Arbitrage Paths
Source: https://docs.blockdb.io/wss-reference/evm/arbitrage/arb-paths

Subscribe to new arbitrage path definitions (cycle topology).

## Overview

* **Dataset ID:** [`0801 - Arbitrage Paths`](/data-catalog/evm/arbitrage/arb-paths)
* **Description:** Path definitions (`b0801_arb_paths_v1`): each `path_id` is a 32-byte hash for an undirected cycle; `pool_uids` and `token_cycle` in canonical order.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Arb-Paths)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filters: 32-byte `path_id` values (hex string, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="path_id" type="string">
  32-byte hash identifying the undirected path (cycle) (hex).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block when the path was first observed.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="pool_uids" type="string[]">
  Pool UIDs in canonical cycle order (hex).
</ResponseField>

<ResponseField name="token_cycle" type="string[]">
  Token cycle in canonical order (hex addresses).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Unique tracing ID (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent tracing IDs (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0801", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0801\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0801\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0801",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0801',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0801", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0801",
    "is_reorg": false,
    "data": {
      "path_id": "a1b2c3d4e5f6789012345678901234567890abcd1234567890abcdef12345678",
      "block_number": 21000500,
      "block_time": "2025-11-11T12:00:00Z",
      "tx_index": 3,
      "log_index": 12,
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
        "11b815acc87f6f89741a636d1ebfcea40876f8f0000000000000000000000000"
      ],
      "token_cycle": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
      ],
      "_tracing_id": "0801c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T12:00:05Z",
      "_updated_at": "2025-11-11T12:00:05Z"
    }
  }
  ```
</CodeGroup>


# Arbitrage Overview
Source: https://docs.blockdb.io/wss-reference/evm/arbitrage/overview

WebSocket streams for arbitrage paths, status, and opportunities.

| Stream                                                              | Dataset | REST                                                                            |
| ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| [Arb paths](/wss-reference/evm/arbitrage/arb-paths)                 | `0701`  | [`POST /evm/arb/paths`](/api-reference/evm/arbitrage/arb-paths)                 |
| [Arb path status](/wss-reference/evm/arbitrage/arb-path-status)     | `0702`  | [`POST /evm/arb/path-status`](/api-reference/evm/arbitrage/arb-path-status)     |
| [Arb opportunities](/wss-reference/evm/arbitrage/arb-opportunities) | `0801`  | [`POST /evm/arb/opportunities`](/api-reference/evm/arbitrage/arb-opportunities) |


# Pool Fee Terms
Source: https://docs.blockdb.io/wss-reference/evm/entities/fee-terms

Subscribe to real-time updates for AMM pool fee configurations.

## Overview

* **Dataset ID:** [`0212 - Liquidity Pool Fee Terms`](/data-catalog/evm/entities/liquidity-pools-fee-terms)
* **Description:** Per-pool fee configuration (total fee + split between user/LP, protocol, and extra recipients).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Fee-Terms-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter updates to specific BlockDB pool identifiers.
</ParamField>

<ParamField type="number[]">
  Filter updates by exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height where the fee-terms record is anchored.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="total_fee" type="string | null">
  Total fee fraction (e.g., `0.003` = 0.30%). String to preserve `NUMERIC(18,18)` precision.
</ResponseField>

<ResponseField name="user_fee" type="string | null">
  Absolute fee fraction allocated to LPs/users (same units as `total_fee`).
</ResponseField>

<ResponseField name="protocol_fee" type="string | null">
  Absolute fee fraction allocated to protocol/treasury (same units as `total_fee`).
</ResponseField>

<ResponseField name="extra_fee" type="string | null">
  Absolute fee fraction allocated to extra destinations (same units as `total_fee`).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0212", "chain_id": 1, "params": {"pool_uids": ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"]}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0212\", \"chain_id\": 1, \"params\": {\"pool_uids\": [\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"]}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0212\", \"chain_id\": 1, \"params\": {\"pool_uids\": [\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\"]}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0212",
          "chain_id": 1,
          "params": {
              "pool_uids": ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"]
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0212',
      chain_id: 1,
      params: {
        pool_uids: ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"]
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0212", "chain_id": 1, "params": {"pool_uids": ["88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"]}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0212",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "total_fee": "0.003000000000000000",
      "user_fee": "0.003000000000000000",
      "protocol_fee": "0.000000000000000000",
      "extra_fee": "0.000000000000000000",
      "_tracing_id": "0212c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  }
  ```
</CodeGroup>


# Tokens & Liquidity Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/entities/overview

Subscribe to real-time updates for tokens and liquidity pools metadata.

## Overview

The Tokens & Liquidity streams provide real-time notifications for new ERC-20 token registrations and AMM pool deployments.

## Stream Matrix

| Stream                                                    | Summary                                             | Dataset ID |
| :-------------------------------------------------------- | :-------------------------------------------------- | :--------- |
| [ERC-20 Tokens](/wss-reference/evm/entities/tokens-erc20) | Real-time notifications for new token registrations | `0201`     |
| [AMM Pools](/wss-reference/evm/entities/pools)            | Notifications for new pool deployments across DEXs  | `0203`     |
| [Fee Terms](/wss-reference/evm/entities/fee-terms)        | Real-time updates to pool fee configurations        | `0204`     |

## Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

### Filters

* **ERC-20 Tokens**: `address` (filter to a specific token).
* **AMM Pools**: `exchange_ids`, `pool_type_ids`.
* **Fee Terms**: `pool_uids`, `exchange_ids`.

## Usage Guidance

* **New Asset Discovery** — Use these streams to discover new tokens and pools as soon as they are deployed.
* **Join with Reserves** — Use the `pool_uid` from a new pool event to subscribe to its [Reserves](/wss-reference/evm/reserves/reserves) stream.

## See Also

* [EVM Entities Reference](/api-reference/evm/entities/overview) — For static metadata details.
* [Introduction](/wss-reference/overview/introduction) — Protocol and authentication details.


# AMM Pools
Source: https://docs.blockdb.io/wss-reference/evm/entities/pools

Subscribe to real-time notifications for new AMM pool deployments.

## Overview

* **Dataset ID:** [`0211 - Liquidity Pools`](/data-catalog/evm/entities/liquidity-pools)
* **Description:** Canonical list of pools; child time-series tables FK to blockdb\_evm.b0211\_liquidity\_pools\_v1(pool\_uid).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="number[]">
  Filter notifications to specific exchange identifiers. *See the [DigitalExchange](/api-reference/enumerations/digital-exchange) enumeration.*
</ParamField>

<ParamField type="number[]">
  Filter pools by archetype.
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  BlockDB internal pool identifier (32-byte hex).
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height containing the pool creation / genesis record.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="factory" type="string">
  Factory or pool-manager contract address (20-byte hex).
</ResponseField>

<ResponseField name="tokens" type="string[]">
  Token contract addresses that compose the pool.
</ResponseField>

<ResponseField name="contract_id" type="string | null">
  Incarnation id for v2/v3 pools; null for v4-style pools.
</ResponseField>

<ResponseField name="contract_address" type="string | null">
  Pool contract address when applicable (20-byte hex).
</ResponseField>

<ResponseField name="pool_id" type="string | null">
  Protocol-specific pool id (e.g. Uniswap V4), when applicable.
</ResponseField>

<ResponseField name="pairnum" type="number | null">
  Internal pair ordinal, when applicable.
</ResponseField>

<ResponseField name="asset_managers" type="string[] | null">
  Asset manager addresses for Balancer-style pools, when applicable.
</ResponseField>

<ResponseField name="amp" type="number | null">
  Amplification parameter for stable pools, when applicable.
</ResponseField>

<ResponseField name="weights" type="number[] | null">
  Token weights for weighted pools, when applicable.
</ResponseField>

<ResponseField name="tick_spacing" type="number | null">
  Tick spacing for concentrated-liquidity pools, when applicable.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0211", "chain_id": 1, "params": {"exchange_ids": [1, 2]}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0211\", \"chain_id\": 1, \"params\": {\"exchange_ids\": [1, 2]}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0211\", \"chain_id\": 1, \"params\": {\"exchange_ids\": [1, 2]}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0211",
          "chain_id": 1,
          "params": {
              "exchange_ids": [1, 2]
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0211',
      chain_id: 1,
      params: {
        exchange_ids: [1, 2]
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0211", "chain_id": 1, "params": {"exchange_ids": [1, 2]}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0211",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 2,
      "block_number": 567890,
      "block_time": "2018-07-07T12:34:56.000Z",
      "tx_index": 4,
      "log_index": 2,
      "factory": "1f98431c8ad98523631ae4a59f267346ea31f984",
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "contract_id": "0000000000000000000000000000000000000000000000000000",
      "contract_address": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "pool_id": null,
      "pairnum": 42,
      "asset_managers": null,
      "amp": null,
      "weights": [
        0.5,
        0.5
      ],
      "tick_spacing": null,
      "_tracing_id": "0211000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# ERC-1155 Tokens
Source: https://docs.blockdb.io/wss-reference/evm/entities/tokens-erc1155

Subscribe to real-time ERC-1155 multi-token contract registry updates.

## Overview

* **Dataset ID:** [`0203 - ERC-1155 Tokens`](/data-catalog/evm/entities/erc1155-tokens)
* **Description:** Catalog of ERC-1155 Multi Token contracts (EIP-1155); one contract can have many token types.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/ERC1155-Tokens-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string">
  Optional filter: one contract address (20-byte hex, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex).
</ResponseField>

<ResponseField name="contract_address" type="string">
  ERC-1155 contract address (20-byte hex).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block where the contract was recognized.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="name" type="string | null">
  Contract-level name when present.
</ResponseField>

<ResponseField name="symbol" type="string | null">
  Contract-level symbol when present.
</ResponseField>

<ResponseField name="decimals" type="number | null">
  Decimals when exposed by the contract.
</ResponseField>

<ResponseField name="uri" type="string | null">
  URI from `uri(uint256)` (optional ERC1155Metadata\_URI).
</ResponseField>

<ResponseField name="supports_metadata_uri" type="boolean | null">
  Whether the contract supports the ERC1155Metadata\_URI extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0203", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0203\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0203\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0203",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0203',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0203", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0203",
    "is_reorg": false,
    "data": {
      "contract_id": "0000000000000000000000000000000000000000000000000000",
      "contract_address": "495f947276749ce646f68ac8c248420045cb7b5e",
      "block_number": 11579209,
      "block_time": "2021-10-15T12:00:00Z",
      "tx_index": 42,
      "name": "OpenSea Shared Storefront",
      "symbol": "OPENSTORE",
      "decimals": null,
      "uri": "https://api.opensea.io/api/v1/metadata/{id}",
      "supports_metadata_uri": true,
      "_tracing_id": "0203000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# ERC-20 Tokens
Source: https://docs.blockdb.io/wss-reference/evm/entities/tokens-erc20

Subscribe to real-time notifications for new ERC-20 token registrations.

## Overview

* **Dataset ID:** [`0201 - ERC-20 Tokens`](/data-catalog/evm/entities/erc20-tokens)
* **Description:** Catalog of ERC-20 token contracts (EIP-20).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/ERC20-Tokens-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  Filter notifications to a specific ERC-20 token address (hex string, 20 bytes, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex).
</ResponseField>

<ResponseField name="contract_address" type="string">
  Token contract address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block where the token was first recognized.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="name" type="string | null">
  Token name from `name()` (optional in EIP-20).
</ResponseField>

<ResponseField name="symbol" type="string | null">
  Token symbol from `symbol()` (optional in EIP-20).
</ResponseField>

<ResponseField name="decimals" type="number | null">
  Token decimals from `decimals()` (optional in EIP-20).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0201", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0201\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0201\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0201",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0201',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0201", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0201",
    "is_reorg": false,
    "data": {
      "contract_id": "0000000000000000000000000000000000000000000000000000",
      "contract_address": "0000000000000000000000000000000000000001",
      "block_number": 567890,
      "block_time": "2018-07-07T12:34:56Z",
      "tx_index": 4,
      "name": "Token Name",
      "symbol": "TOKEN",
      "decimals": 18,
      "_tracing_id": "0201000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# ERC-721 Tokens
Source: https://docs.blockdb.io/wss-reference/evm/entities/tokens-erc721

Subscribe to real-time ERC-721 collection registry updates.

## Overview

* **Dataset ID:** [`0202 - ERC-721 Tokens`](/data-catalog/evm/entities/erc721-tokens)
* **Description:** Catalog of ERC-721 NFT collection contracts (EIP-721).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/ERC721-Tokens-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string">
  Optional filter: one collection contract (20-byte hex, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="contract_id" type="string">
  Unique contract incarnation ID (26 bytes hex).
</ResponseField>

<ResponseField name="contract_address" type="string">
  Collection contract address (20-byte hex).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block where the collection was first recognized.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="name" type="string | null">
  Collection name from `name()` (ERC721Metadata, optional).
</ResponseField>

<ResponseField name="symbol" type="string | null">
  Collection symbol from `symbol()` (ERC721Metadata, optional).
</ResponseField>

<ResponseField name="token_uri" type="string | null">
  Representative sample from the discovery probe.
</ResponseField>

<ResponseField name="supports_metadata" type="boolean | null">
  Whether the contract supports the ERC721Metadata extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="supports_enumerable" type="boolean | null">
  Whether the contract supports the ERC721Enumerable extension; null when detection was via fallback.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0202", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0202\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0202\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0202",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0202',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0202", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0202",
    "is_reorg": false,
    "data": {
      "contract_id": "0000000000000000000000000000000000000000000000000000",
      "contract_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
      "block_number": 12287507,
      "block_time": "2021-04-22T23:43:17Z",
      "tx_index": 114,
      "name": "BoredApeYachtClub",
      "symbol": "BAYC",
      "token_uri": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/",
      "supports_metadata": true,
      "supports_enumerable": true,
      "_tracing_id": "0202000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Flash Loan Prints
Source: https://docs.blockdb.io/wss-reference/evm/flash-loans/flash-loan-prints

Subscribe to flash loan borrow/repay events.

## Overview

* **Dataset ID:** [`0305 - Flash Loan Prints`](/data-catalog/evm/flash-loans/flash-loan-prints)
* **Description:** One row per borrowed token per on-chain flash loan event (V2-style flash swap, V3 Flash event, Balancer V2 Vault, etc.). `pool_uid` is NULL for vault-level events not tied to a single pool.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Flash-Loan-Prints)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filters: pool UIDs (32-byte hex, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Optional filters: emitter contracts (pool or vault), 20-byte hex without `0x`.
</ParamField>

<ParamField type="string[]">
  Optional filters: borrowed token addresses (hex, no `0x`).
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string | null">
  Pool id when pool-scoped; null for vault-level events.
</ResponseField>

<ResponseField name="exchange_id" type="number | null">
  Exchange identifier when pool-scoped.
</ResponseField>

<ResponseField name="type_id" type="number | null">
  Pool type identifier when pool-scoped.
</ResponseField>

<ResponseField name="flash_loan_source" type="string">
  Address of the contract that emitted the event (hex).
</ResponseField>

<ResponseField name="token" type="string">
  Borrowed token address (hex).
</ResponseField>

<ResponseField name="amount_borrowed" type="string">
  Raw borrowed amount (decimal string).
</ResponseField>

<ResponseField name="amount_repaid" type="string">
  Raw repaid amount (decimal string).
</ResponseField>

<ResponseField name="fee_amount" type="string">
  Raw fee paid: `amount_repaid − amount_borrowed` (decimal string).
</ResponseField>

<ResponseField name="block_number" type="number">
  Event block.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0305", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0305\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0305\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0305",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0305',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0305", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0305",
    "is_reorg": false,
    "data": {
      "block_number": 19000050,
      "block_time": "2025-11-11T10:00:00Z",
      "tx_index": 12,
      "log_index": 3,
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "flash_loan_source": "88e6a0c2ddd26feeb64f039a2c41296fcb3f564",
      "token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "amount_borrowed": "1000000000000000000",
      "amount_repaid": "1003000000000000000",
      "fee_amount": "3000000000000000",
      "_tracing_id": "0305c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T10:00:05Z",
      "_updated_at": "2025-11-11T10:00:05Z"
    }
  }
  ```
</CodeGroup>


# Flash Loans Overview
Source: https://docs.blockdb.io/wss-reference/evm/flash-loans/overview

WebSocket stream for flash loan prints.

| Stream                                                                | Dataset |
| --------------------------------------------------------------------- | ------- |
| [Flash loan prints](/wss-reference/evm/flash-loans/flash-loan-prints) | `0305`  |

REST: [`POST /evm/flash-loans/prints`](/api-reference/evm/flash-loans/flash-loan-prints).


# Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/overview

Index of BlockDB WebSocket (WSS) streams for real-time EVM data.

## Overview

WebSocket streams mirror Historic REST datasets. Subscribe with `action`, `chain_id`, `dataset_id`, and `params` as in [Introduction](/wss-reference/overview/introduction). Dataset IDs match [Dataset ID](/api-reference/enumerations/dataset-id).

## Stream matrix

| Dataset | Stream                                                                       |
| :------ | :--------------------------------------------------------------------------- |
| `0101`  | [Blocks](/wss-reference/evm/primitives/blocks)                               |
| `0102`  | [Transactions](/wss-reference/evm/primitives/transactions)                   |
| `0103`  | [Logs](/wss-reference/evm/primitives/logs)                                   |
| `0111`  | [Internal transactions](/wss-reference/evm/primitives/internal-transactions) |
| `0121`  | [Contracts](/wss-reference/evm/primitives/contracts)                         |
| `0122`  | [Function results](/wss-reference/evm/primitives/function-results)           |
| `0201`  | [ERC-20](/wss-reference/evm/entities/tokens-erc20)                           |
| `0202`  | [ERC-721](/wss-reference/evm/entities/tokens-erc721)                         |
| `0203`  | [ERC-1155](/wss-reference/evm/entities/tokens-erc1155)                       |
| `0211`  | [Pools](/wss-reference/evm/entities/pools)                                   |
| `0212`  | [Fee terms](/wss-reference/evm/entities/fee-terms)                           |
| `0301`  | [Reserves](/wss-reference/evm/reserves/reserves)                             |
| `0302`  | [Swap prints](/wss-reference/evm/prices/crypto/prices-spot-prints)           |
| `0303`  | [Swap fees](/wss-reference/evm/swaps/swap-fees)                              |
| `0304`  | [Token transfers](/wss-reference/evm/transfers/token-transfers)              |
| `0305`  | [Flash loan prints](/wss-reference/evm/flash-loans/flash-loan-prints)        |
| `0404`  | [OHLC](/wss-reference/evm/prices/crypto/prices-spot-ohlc)                    |
| `0405`  | [VWAP](/wss-reference/evm/prices/crypto/prices-spot-vwap)                    |
| `0501`  | [Fiat VWAP (USD)](/wss-reference/evm/prices/fiat/prices-spot-vwap-fiat)      |
| `0601`  | [TVL USD](/wss-reference/evm/tvl/tvl-usd)                                    |
| `0701`  | [Arb paths](/wss-reference/evm/arbitrage/arb-paths)                          |
| `0702`  | [Arb path status](/wss-reference/evm/arbitrage/arb-path-status)              |
| `0801`  | [Arb opportunities](/wss-reference/evm/arbitrage/arb-opportunities)          |
| `0411`  | [Yields](/wss-reference/evm/yields/yields)                                   |


# Pricing Suite (Crypto) Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/prices/crypto/overview

WebSocket streams for swap prints, OHLC, and VWAP.

## Stream matrix

| Stream                                                             | Dataset ID |
| :----------------------------------------------------------------- | :--------- |
| [Swap prints](/wss-reference/evm/prices/crypto/prices-spot-prints) | `0302`     |
| [OHLC](/wss-reference/evm/prices/crypto/prices-spot-ohlc)          | `0404`     |
| [VWAP](/wss-reference/evm/prices/crypto/prices-spot-vwap)          | `0405`     |

## Conventions

Use `chain_id`, `dataset_id`, and endpoint-specific `params` (e.g. `pool_uids`, token addresses) as on each stream page. See [Introduction](/wss-reference/overview/introduction).

## See also

* [REST · Crypto pricing](/api-reference/evm/prices/crypto/overview)


# Spot OHLC
Source: https://docs.blockdb.io/wss-reference/evm/prices/crypto/prices-spot-ohlc

Subscribe to real-time OHLC candlestick bars from on-chain AMM swap aggregates (`0404`).

## Overview

* **Dataset ID:** [`0404 - Token-to-Token OHLC`](/data-catalog/evm/prices/token-to-token-prices-ohlc)
* **Description:** Time-bucketed OHLC bars (1m..1d) per pool and token pair direction.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-To-Token-Prices-OHLC)

## Subscription Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  Candle width, expressed as an ISO-8601 duration shorthand (`1m`, `5m`, `1h`, `1d`). Default is `1m`.
</ParamField>

## Message Fields (`data`)

Top-level fields: `chain_id`, `dataset_id`, `is_reorg`, `data` (object). The `data` object mirrors **`b0404_token_to_token_prices_ohlc_v1`**:

<ResponseField name="data.pool_uid" type="string">
  `BYTEA` — Pool id (hex).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.type_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  `TIMESTAMPTZ` — Inclusive UTC bucket start.
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  `TIMESTAMPTZ` — Exclusive UTC bucket end (`bucket_start + bucket_seconds`).
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.token_in" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.token_out" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.open" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.high" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.low" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.close" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.volume_in_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountIn` values.
</ResponseField>

<ResponseField name="data.volume_in" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_in` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.volume_out_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountOut` values.
</ResponseField>

<ResponseField name="data.volume_out" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_out` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.trades_count" type="number">
  `BIGINT`
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  `BYTEA[]` — Optional parent lineage references.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0404", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "aggregation_interval": "1m"}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0404\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", \"aggregation_interval\": \"1m\"}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0404\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", \"aggregation_interval\": \"1m\"}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0404",
          "chain_id": 1,
          "params": {
              "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "aggregation_interval": "1m"
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0404',
      chain_id: 1,
      params: {
        base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        aggregation_interval: "1m"
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0404", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "aggregation_interval": "1m"}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0404",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "bucket_start": "2025-11-11T00:00:00.000Z",
      "bucket_end": "2025-11-11T00:01:00.000Z",
      "bucket_seconds": 60,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "open": "3010.112233445566778899",
      "high": "3033.998877665544332211",
      "low": "3008.001122334455667788",
      "close": "3025.219821481234567890",
      "volume_in_raw": "420000000000000000000",
      "volume_in": "420.000000000000000000",
      "volume_out_raw": "1269000000000",
      "volume_out": "1269000.000000000000000000",
      "trades_count": 128,
      "_tracing_id": "0404000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T00:01:05.000Z",
      "_updated_at": "2025-11-11T00:01:05.000Z"
    }
  }
  ```
</CodeGroup>


# Spot Prints
Source: https://docs.blockdb.io/wss-reference/evm/prices/crypto/prices-spot-prints

Subscribe to real-time realized swap prices and execution sizes.

## Overview

* **Dataset ID:** [`0302 - Token-to-Token Swap Prints`](/data-catalog/evm/prices/token-to-token-prices-swap-prints)
* **Description:** Executed swap prints (realized token\_in → token\_out price & sizes) per on-chain swap event.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-To-Token-Prices-Swap-Prints)

## Subscription Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  Pool identifier.
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height where the swap occurred.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="token_in" type="string">
  Address of the input token.
</ResponseField>

<ResponseField name="token_out" type="string">
  Address of the output token.
</ResponseField>

<ResponseField name="amount_in" type="string">
  Amount of `token_in` (raw units, integer string).
</ResponseField>

<ResponseField name="amount_out" type="string">
  Amount of `token_out` (raw units, integer string).
</ResponseField>

<ResponseField name="exec_price" type="string | null">
  Realized execution price: `token_out` per 1 `token_in` (decimals-adjusted). May be `null`.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0302", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0302\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0302\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0302",
          "chain_id": 1,
          "params": {
              "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0302',
      chain_id: 1,
      params: {
        base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0302", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0302",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 18930123,
      "block_time": "2025-11-11T18:15:30.000Z",
      "tx_index": 5,
      "log_index": 12,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount_in": "10000000000000000000",
      "amount_out": "30241122334455667788990",
      "exec_price": "3024.112233445566778899",
      "_tracing_id": "0302000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0203000000000000000000000000000000000000"
      ],
      "_created_at": "2025-11-11T18:15:35.000Z",
      "_updated_at": "2025-11-11T18:15:35.000Z"
    }
  }
  ```
</CodeGroup>


# Spot VWAP
Source: https://docs.blockdb.io/wss-reference/evm/prices/crypto/prices-spot-vwap

Subscribe to real-time volume-weighted average price (VWAP) updates.

## Overview

* **Dataset ID:** [`0405 - Token-to-Token VWAP`](/data-catalog/evm/prices/token-to-token-vwap)
* **Description:** Volume-weighted average price (1m..1d) per pool and token pair direction.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-To-Token-VWAP)

## Subscription Parameters

<ParamField type="number">
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

## Message Fields (`data`)

Top-level fields: `chain_id`, `dataset_id`, `is_reorg`, `data` (object). The `data` object mirrors **`b0405_token_to_token_vwap_v1`**:

<ResponseField name="data.pool_uid" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.type_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  `TIMESTAMPTZ` — Inclusive UTC bucket start.
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  `TIMESTAMPTZ` — Exclusive UTC bucket end (`bucket_start + bucket_seconds`).
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.token_in" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.token_out" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.price_vwap" type="string | null">
  `NUMERIC(78,18)` — VWAP (token\_out per 1 token\_in); `null` if undefined.
</ResponseField>

<ResponseField name="data.total_volume_in_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountIn` values.
</ResponseField>

<ResponseField name="data.total_volume_in" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_in` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.total_volume_out_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountOut` values.
</ResponseField>

<ResponseField name="data.total_volume_out" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_out` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.trade_count" type="number">
  `BIGINT`
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  `BYTEA[]` — Optional parent lineage references.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0405", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0405\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0405\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0405",
          "chain_id": 1,
          "params": {
              "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0405',
      chain_id: 1,
      params: {
        base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0405", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0405",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "bucket_start": "2025-11-11T18:00:00.000Z",
      "bucket_end": "2025-11-11T19:00:00.000Z",
      "bucket_seconds": 3600,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "price_vwap": "3024.112233445566778899",
      "total_volume_in_raw": "580000000000000000000",
      "total_volume_in": "580.000000000000000000",
      "total_volume_out_raw": "1750000000000",
      "total_volume_out": "1750000.000000000000000000",
      "trade_count": 142,
      "_tracing_id": "0405000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T19:00:05.000Z",
      "_updated_at": "2025-11-11T19:00:05.000Z"
    }
  }
  ```
</CodeGroup>


# Pricing Suite (Fiat) Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/prices/fiat/overview

WebSocket stream for token-to-USD VWAP.

## Stream matrix

| Stream                                                              | Dataset ID |
| :------------------------------------------------------------------ | :--------- |
| [VWAP (Fiat)](/wss-reference/evm/prices/fiat/prices-spot-vwap-fiat) | `0501`     |

`0501` maps to `blockdb_evm.b0501_token_to_fiat_vwap`.

## See also

* [REST · Fiat pricing](/api-reference/evm/prices/fiat/overview)
* [Introduction](/wss-reference/overview/introduction)


# Spot VWAP (Fiat)
Source: https://docs.blockdb.io/wss-reference/evm/prices/fiat/prices-spot-vwap-fiat

Subscribe to real-time fiat-denominated volume-weighted average price (VWAP) updates.

## Overview

* **Dataset ID:** [`0605 - Token-to-Fiat VWAP (USD)`](/data-catalog/evm/prices/token-to-fiat-vwap)
* **Description:** Token-to-USD VWAP (1m..1d) per token, derived from token-to-token VWAP via stablecoin anchoring.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-To-Fiat-VWAP)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string">
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string">
  ISO-4217 fiat currency code (e.g., `USD`, `EUR`).
</ParamField>

## Message Fields (`data`)

Top-level fields: `chain_id`, `dataset_id`, `is_reorg`, `data` (object). The `data` object mirrors **`b0605_token_to_fiat_vwap`**:

<ResponseField name="data.first_block_number" type="number">
  `BIGINT`
</ResponseField>

<ResponseField name="data.first_block_time" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data.first_tx_index" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.first_log_index" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.last_block_number" type="number">
  `BIGINT`
</ResponseField>

<ResponseField name="data.last_block_time" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data.last_tx_index" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.last_log_index" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.token_address" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.price_usd" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.total_notional_usd" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.hops" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.sources_count" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[]">
  `BYTEA[]` (nullable by default; can be large)
</ResponseField>

<ResponseField name="data._created_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0605", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_currency_code": "USD"}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0605\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_currency_code\": \"USD\"}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0605\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_currency_code\": \"USD\"}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0605",
          "chain_id": 1,
          "params": {
              "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "quote_currency_code": "USD"
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0605',
      chain_id: 1,
      params: {
        base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        quote_currency_code: "USD"
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0605", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_currency_code": "USD"}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0605",
    "is_reorg": false,
    "data": {
      "first_block_number": 18930000,
      "first_block_time": "2025-11-11T18:00:11.000Z",
      "first_tx_index": 12,
      "first_log_index": 5,
      "last_block_number": 18939999,
      "last_block_time": "2025-11-11T18:59:48.000Z",
      "last_tx_index": 44,
      "last_log_index": 2,
      "bucket_start": "2025-11-11T18:00:00.000Z",
      "bucket_seconds": 3600,
      "token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "price_usd": "3024.112233445566778899",
      "total_notional_usd": "1750000.000000000000000000",
      "hops": 2,
      "sources_count": 4,
      "_tracing_id": "0605000000000000000000000000000000000001",
      "_created_at": "2025-11-11T19:00:05.000Z",
      "_updated_at": "2025-11-11T19:00:05.000Z"
    }
  }
  ```
</CodeGroup>


# Blocks
Source: https://docs.blockdb.io/wss-reference/evm/primitives/blocks

Subscribe to real-time canonical EVM block headers and integrity metadata.

## Overview

* **Dataset ID:** [`0101 - Blocks`](/data-catalog/evm/primitives/blocks)
* **Description:** Canonical block headers with BlockDB integrity metadata.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Blocks-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

## Message Fields

Each message in the stream follows the standard block schema:

<ResponseField name="block_number" type="number">
  Sequential block height.
</ResponseField>

<ResponseField name="block_hash" type="string">
  Keccak-256 hash of the block header (32 bytes, hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="parent_block_hash" type="string">
  Keccak-256 hash of the parent block.
</ResponseField>

<ResponseField name="miner" type="string">
  Fee recipient / coinbase address.
</ResponseField>

<ResponseField name="timestamp_utc" type="string">
  Timestamp when the block was mined.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Tracing identifier for the canonical block record.
</ResponseField>

<ResponseField name="is_reorg" type="boolean">
  If `true`, this message is a reorg correction and should be treated as an overwrite of previously emitted state at the same natural key (for blocks: `block_number`).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0101", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0101\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0101\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0101",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0101',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0101", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0101",
    "is_reorg": false,
    "data": {
      "block_number": 12345678,
      "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
      "parent_block_hash": "f78e26c5959a94d6a62ed3837f5dcecf0d3761bf0a502e12a08fd7bc44c8568d",
      "receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
      "miner": "0000000000000000000000000000000000000000",
      "gas_limit": 30000000,
      "extra_data": "636c61737369635f657468657265756d",
      "size": 124836,
      "timestamp_utc": "2025-11-11T18:42:15.123Z",
      "_tracing_id": "010200000000000000000000000000000000",
      "_computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
      "_computed_receipt_timestamp_utc": "2025-11-11T18:43:00.000Z",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Contracts
Source: https://docs.blockdb.io/wss-reference/evm/primitives/contracts

Subscribe to real-time contract deployment notifications and metadata.

## Overview

* **Dataset ID:** [`0121 - Contracts`](/data-catalog/evm/primitives/contracts)
* **Description:** Smart contracts discovered via CREATE/CREATE2 internal transactions. Uses `contract_id` (26 bytes = address + creation\_block + tx\_index) as primary key to support metamorphic contracts (e.g. CREATE-SELFDESTRUCT-CREATE2 in the same block).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Contracts-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter notifications to specific deployed contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

## Message Fields

Payload fields mirror `blockdb_evm.b0121_contracts_v1` (binary fields as hex strings without `0x` in JSON).

<ResponseField name="contract_id" type="string">
  Contract incarnation ID (hex, 26 bytes): 20 bytes address + 4 bytes creation block + 2 bytes tx index.
</ResponseField>

<ResponseField name="contract_address" type="string">
  Deployed contract address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height containing the contract creation.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Zero-based index of the deployment transaction within the block.
</ResponseField>

<ResponseField name="trace_address" type="string">
  Position in the call tree (e.g., `"0"`, `"0.0"`, `"0.1.2"`).
</ResponseField>

<ResponseField name="creator_address" type="string">
  Address that deployed the contract (msg.sender of CREATE/CREATE2). Hex string, 20 bytes, no `0x` prefix.
</ResponseField>

<ResponseField name="creation_call_type" type="string">
  Creation call type (`CREATE` or `CREATE2`).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0121", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0121\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0121\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0121",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0121',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0121", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0121",
    "is_reorg": false,
    "data": {
      "contract_id": "1234567890abcdef1234567890abcdef1234567800121a0700",
      "contract_address": "1234567890abcdef1234567890abcdef12345678",
      "block_number": 18934221,
      "block_time": "2024-04-01T12:34:56Z",
      "tx_index": 7,
      "trace_address": "0",
      "creator_address": "0000000000000000000000000000000000000000",
      "creation_call_type": "CREATE2",
      "_tracing_id": "0121000000000000000000000000000000000001",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Function Results
Source: https://docs.blockdb.io/wss-reference/evm/primitives/function-results

Subscribe to real-time cached function execution outputs enriched with traces and gas usage.

## Overview

* **Dataset ID:** [`0122 - Function Results`](/data-catalog/evm/primitives/function-results)
* **Description:** On-chain function call return values versioned by block. Uses `contract_id` (26 bytes) to support metamorphic contracts; primary key is `(contract_id, block_number, call_data)`.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Function-Results-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by contract addresses (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by 4-byte function selectors (e.g., `0902f1ac`).
</ParamField>

## Message Fields

Payload fields mirror `blockdb_evm.b0122_function_results_v1` (binary fields as hex strings without `0x` in JSON).

<ResponseField name="contract_id" type="string">
  Contract incarnation ID (hex, 26 bytes).
</ResponseField>

<ResponseField name="block_number" type="number">
  Snapshot block height when the value was observed.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="call_data" type="string">
  Hex-encoded calldata sent to the contract.
</ResponseField>

<ResponseField name="signature_hash" type="string">
  4-byte function selector (hex).
</ResponseField>

<ResponseField name="result" type="string | null">
  Hex-encoded return payload, or `null`.
</ResponseField>

<ResponseField name="timestamp_utc" type="string">
  Observation timestamp (ISO-8601).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0122", "chain_id": 1, "params": {"signature_hashes": ["0902f1ac"]}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0122\", \"chain_id\": 1, \"params\": {\"signature_hashes\": [\"0902f1ac\"]}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0122\", \"chain_id\": 1, \"params\": {\"signature_hashes\": [\"0902f1ac\"]}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0122",
          "chain_id": 1,
          "params": {
              "signature_hashes": ["0902f1ac"]
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0122',
      chain_id: 1,
      params: {
        signature_hashes: ["0902f1ac"]
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0122", "chain_id": 1, "params": {"signature_hashes": ["0902f1ac"]}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0122",
    "is_reorg": false,
    "data": {
      "contract_id": "1234567890abcdef1234567890abcdef1234567800121a0700",
      "block_number": 18934560,
      "block_time": "2024-04-01T12:34:56.000Z",
      "call_data": "0902f1ac",
      "signature_hash": "0902f1ac",
      "result": "0000000000000000000000000000000000000000000000000de0b6b3a7640000",
      "timestamp_utc": "2024-04-01T12:34:56.000Z",
      "_tracing_id": "0122000000000000000000000000000000000001",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Internal Transactions
Source: https://docs.blockdb.io/wss-reference/evm/primitives/internal-transactions

Subscribe to real-time internal transaction (call trace) updates.

## Overview

* **Dataset ID:** [`0111 - Internal Transactions`](/data-catalog/evm/primitives/internal-transactions)
* **Description:** Internal transactions (call traces) from debug\_traceTransaction.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Internal-Transactions-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filter: caller addresses (hex, no `0x`).
</ParamField>

<ParamField type="string[]">
  Optional filter: callee addresses (hex, no `0x`).
</ParamField>

<ParamField type="string[]">
  Optional filter: `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2`.
</ParamField>

## Message Fields

Payload mirrors `blockdb_evm.b0111_internal_transactions_v1` (addresses and `BYTEA` fields as hex strings without `0x` in JSON).

<ResponseField name="block_number" type="number">
  Parent transaction block.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index in block.
</ResponseField>

<ResponseField name="trace_address" type="string">
  Call tree position (e.g. `0`, `0.1`).
</ResponseField>

<ResponseField name="call_type" type="string">
  `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, or `CREATE2`.
</ResponseField>

<ResponseField name="from_address" type="string">
  Caller (20-byte hex).
</ResponseField>

<ResponseField name="to_address" type="string | null">
  Callee (20-byte hex); null when not applicable.
</ResponseField>

<ResponseField name="value_wei" type="string">
  Value transferred in wei (decimal string).
</ResponseField>

<ResponseField name="gas" type="string">
  Gas allocated for this call frame (integer string).
</ResponseField>

<ResponseField name="gas_used" type="string">
  Gas consumed by this call frame (integer string).
</ResponseField>

<ResponseField name="input" type="string | null">
  Calldata (hex string); `null` when not applicable.
</ResponseField>

<ResponseField name="output" type="string | null">
  Return data (hex string); `null` if reverted.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error string if reverted; `null` otherwise.
</ResponseField>

<ResponseField name="tx_success" type="boolean">
  Whether the underlying transaction succeeded.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0111", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0111\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0111\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0111",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0111',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0111", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0111",
    "is_reorg": false,
    "data": {
      "block_number": 12345680,
      "block_time": "2025-10-29T00:01:23Z",
      "tx_index": 5,
      "trace_address": "0",
      "call_type": "CALL",
      "from_address": "0000000000000000000000000000000000000000",
      "to_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "value_wei": "1000000000000000000",
      "gas": "100000",
      "gas_used": "63546",
      "input": "a9059cbb000000000000000000000000",
      "output": "0000000000000000000000000000000000000000000000000000000000000001",
      "error": null,
      "tx_success": true,
      "_tracing_id": "0111000000000000000000000000000000000001",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Logs
Source: https://docs.blockdb.io/wss-reference/evm/primitives/logs

Subscribe to real-time decoded EVM log events with flexible topic filters.

## Overview

* **Dataset ID:** [`0103 - Logs`](/data-catalog/evm/primitives/logs)
* **Description:** Event logs emitted by contract transactions.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Logs-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by emitting contract address (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by the primary event topic (e.g., `Transfer`, `Swap` signature hashes).
</ParamField>

## Message Fields

Payload mirrors `blockdb_evm.b0103_logs_v1` (binary fields as hex strings without `0x` in JSON).

<ResponseField name="contract_address" type="string">
  Address of the emitting contract.
</ResponseField>

<ResponseField name="topic_zero" type="string">
  Primary topic hash identifying the event (32 bytes). `null` for anonymous events.
</ResponseField>

<ResponseField name="data_topics" type="string[]">
  Subsequent event topics (indexed parameters).
</ResponseField>

<ResponseField name="data" type="string">
  Raw event data payload (hex string (no `0x` prefix)).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height containing the log.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Tracing identifier for lineage correlation.
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0103", "chain_id": 1, "params": {"topic_zeros": ["ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0103\", \"chain_id\": 1, \"params\": {\"topic_zeros\": [\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"]}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0103\", \"chain_id\": 1, \"params\": {\"topic_zeros\": [\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"]}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0103",
          "chain_id": 1,
          "params": {
              "topic_zeros": ["ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0103',
      chain_id: 1,
      params: {
        topic_zeros: ["ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0103", "chain_id": 1, "params": {"topic_zeros": ["ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0103",
    "is_reorg": false,
    "data": {
      "block_number": 12345678,
      "block_time": "2025-11-11T18:42:15.123Z",
      "tx_index": 4,
      "log_index": 0,
      "contract_address": "0000000000000000000000000000000000000000",
      "topic_zero": "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "data_topics": [
        "0000000000000000000000000000000000000000000000000000000000000000",
        "0000000000000000000000000000000000000000000000000000000000000001"
      ],
      "data": "00000000000000000000000000000000000000000000000000000000000003e8",
      "_tracing_id": "0103000000000000000000000000000000000000",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Raw Data Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/primitives/overview

Subscribe to canonical blockchain primitives in real-time: blocks, transactions, logs, and more.

## Overview

The Raw Data streams provide push-based access to on-chain execution artifacts as they are finalized. These streams deliver the foundational blockchain primitives that power all derived datasets.

## Stream Matrix

| Stream                                                                       | Summary                                   | Dataset ID |
| :--------------------------------------------------------------------------- | :---------------------------------------- | :--------- |
| [Blocks](/wss-reference/evm/primitives/blocks)                               | Real-time canonical EVM block headers     | `0101`     |
| [Transactions](/wss-reference/evm/primitives/transactions)                   | Executed transactions with gas accounting | `0102`     |
| [Logs](/wss-reference/evm/primitives/logs)                                   | Decoded event logs with topic filters     | `0103`     |
| [Internal transactions](/wss-reference/evm/primitives/internal-transactions) | Call traces                               | `0111`     |
| [Contracts](/wss-reference/evm/primitives/contracts)                         | Contract deployment metadata              | `0121`     |
| [Function results](/wss-reference/evm/primitives/function-results)           | Deterministic contract call outputs       | `0122`     |

## Parameter Conventions

All primitive streams support the following parameters in the `subscribe` message:

<ParamField type="number">
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

### Filters

* **Blocks**: No additional filters.
* **Transactions**: `from_addresses`, `to_addresses`, `status_success`.
* **Logs**: `contract_addresses`, `topic_zeros`.
* **Internal transactions**: `from_addresses`, `to_addresses`, `call_types`.
* **Contracts**: `contract_addresses`.
* **Function results**: `contract_addresses`, `signature_hashes`.

## Usage Guidance

* **Reorg Awareness** — Streams handle reorgs by emitting update or delete events when the canonical chain changes.
* **Lineage** — Each record includes a `_tracing_id` to correlate with archive data.
* **Filtering** — Use topic filters for logs to reduce bandwidth for high-volume contracts.

## See Also

* [Introduction](/wss-reference/overview/introduction) — Protocol and authentication details.
* [WSS Error Codes](/troubleshooting/error-codes/wss/home) — Connection troubleshooting.


# Transactions
Source: https://docs.blockdb.io/wss-reference/evm/primitives/transactions

Subscribe to real-time canonical transactions with execution metadata and gas accounting.

## Overview

* **Dataset ID:** [`0102 - Transactions`](/data-catalog/evm/primitives/transactions)
* **Description:** Transactions included in blocks.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Raw-Transactions-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter by sender address (20 bytes, hex string, no `0x` prefix).
</ParamField>

<ParamField type="string[]">
  Filter by recipient address (20 bytes, hex string, no `0x` prefix).
</ParamField>

<ParamField type="boolean">
  Filter by execution status (`true` = success, `false` = revert).
</ParamField>

## Message Fields

<ResponseField name="tx_hash" type="string">
  Keccak-256 hash of the transaction (hex string, 32 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height containing the transaction.
</ResponseField>

<ResponseField name="block_time" type="string">
  UTC timestamp of the block (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Zero-based index of the transaction within the block.
</ResponseField>

<ResponseField name="from_address" type="string">
  Sender address (hex string, 20 bytes, no `0x` prefix).
</ResponseField>

<ResponseField name="to_address" type="string | null">
  Recipient address (hex string, 20 bytes, no `0x` prefix). `null` for contract creation.
</ResponseField>

<ResponseField name="created_contract_address" type="string | null">
  Address of the contract created by this transaction. `null` for non-creation transactions.
</ResponseField>

<ResponseField name="gas_used" type="string">
  Gas consumed by the transaction (string to preserve `NUMERIC(78)` precision).
</ResponseField>

<ResponseField name="effective_gas_price_wei" type="string">
  Effective gas price paid in wei (string to preserve `NUMERIC(78)` precision).
</ResponseField>

<ResponseField name="status_success" type="boolean">
  Execution status: `true` = success, `false` = revert, `null` for pre-Byzantium blocks.
</ResponseField>

<ResponseField name="root" type="string | null">
  Pre-Byzantium: state root after tx execution; `null` for Byzantium+.
</ResponseField>

<ResponseField name="tx_type" type="number">
  Transaction type identifier (e.g., `2` = EIP-1559, `1` = legacy).
</ResponseField>

<ResponseField name="trace_failed" type="boolean | null">
  `true` if trace failed, `false` if trace succeeded, `null` if trace not available.
</ResponseField>

<ResponseField name="value_wei" type="string">
  Value transferred in wei (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="input" type="string">
  Calldata sent with the transaction (hex string, no `0x` prefix).
</ResponseField>

<ResponseField name="nonce" type="number">
  Sender nonce.
</ResponseField>

<ResponseField name="gas_limit" type="string">
  Gas limit provided by the sender (string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="gas_price_wei" type="string">
  Gas price in wei (legacy, string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="max_fee_per_gas_wei" type="string">
  Max fee per gas in wei (EIP-1559, string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="max_priority_fee_per_gas_wei" type="string">
  Max priority fee per gas in wei (EIP-1559, string to preserve `NUMERIC` precision).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Tracing identifier for cross-referencing with other datasets.
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation timestamp.
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update timestamp.
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0102", "chain_id": 1, "params": {"status_success": true}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0102\", \"chain_id\": 1, \"params\": {\"status_success\": true}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0102\", \"chain_id\": 1, \"params\": {\"status_success\": true}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0102",
          "chain_id": 1,
          "params": {"status_success": True}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0102',
      chain_id: 1,
      params: { status_success: true }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0102", "chain_id": 1, "params": {"status_success": true}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0102",
    "is_reorg": false,
    "data": {
      "block_number": 12345678,
      "block_time": "2025-11-11T18:42:15.123Z",
      "tx_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
      "tx_index": 4,
      "from_address": "0000000000000000000000000000000000000000",
      "to_address": "0000000000000000000000000000000000000001",
      "created_contract_address": null,
      "gas_used": "21000",
      "effective_gas_price_wei": "1234567890123456789",
      "status_success": true,
      "root": null,
      "tx_type": 2,
      "trace_failed": null,
      "value_wei": "0",
      "input": "",
      "nonce": 1,
      "gas_limit": "21000",
      "gas_price_wei": "1234567890123456789",
      "max_fee_per_gas_wei": "0",
      "max_priority_fee_per_gas_wei": "0",
      "_tracing_id": "010200000000000000000000000000000000",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Pools Reserves Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/reserves/overview

Subscribe to real-time normalized pool reserve snapshots.

## Overview

The Reserves stream provides push-based, real-time snapshots of AMM pool liquidity states. Data is normalized across different pool types (constant-product, concentrated liquidity, weighted pools).

## Stream Matrix

| Stream                                           | Summary                                     | Dataset ID |
| :----------------------------------------------- | :------------------------------------------ | :--------- |
| [Reserves](/wss-reference/evm/reserves/reserves) | Real-time normalized pool reserve snapshots | `0301`     |

## Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network.
</ParamField>

<ParamField type="string[]">
  Filter by specific BlockDB pool identifiers.
</ParamField>

<ParamField type="boolean">
  Include tick-range or bin-level liquidity breakdowns for concentrated liquidity pools.
</ParamField>

<Note>
  **Tick range coverage:** When `include_details` is enabled, detail rows cover a **±1% range around the current price tick** by default. If you need a wider tick range or full tick coverage, [contact us](mailto:support@blockdb.io).
</Note>

## Usage Guidance

* **Low-Latency Arbitrage** — Real-time reserve updates enable fast calculation of execution prices for trading.
* **Liquidity Monitoring** — Monitor concentrated liquidity distributions in real-time.

## See Also

* [Reserves Reference](/api-reference/evm/reserves/reserves) — For detailed schema descriptions.
* [Introduction](/wss-reference/overview/introduction) — Protocol and authentication details.


# Reserves
Source: https://docs.blockdb.io/wss-reference/evm/reserves/reserves

Subscribe to real-time normalized pool reserve snapshots.

## Overview

* **Dataset ID:** [`0301 - Liquidity Pool Reserves`](/data-catalog/evm/reserves/liquidity-pools-reserves)
* **Description:** Pool reserve snapshots (`b0301_liquidity_pools_reserves_v1`); tick/bin detail rows in `b0301_liquidity_pools_reserves_details_v1`. `pool_uid` → `blockdb_evm.b0211_liquidity_pools_v1`.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Liquidity-Pool-Reserves)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter updates to specific BlockDB pool identifiers.
</ParamField>

<ParamField type="boolean">
  Include tick-range or bin-level liquidity breakdowns for concentrated liquidity pools.
</ParamField>

<Note>
  **Tick range coverage:** When `include_details` is enabled, detail rows cover a **±1% range around the current price tick** by default. If you need a wider tick range or full tick coverage, [contact us](mailto:support@blockdb.io).
</Note>

## Message Fields

<ResponseField name="pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height where the reserve change occurred.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="reserves" type="string[]">
  Raw token reserves for even-liquidity pools (one entry per token).
</ResponseField>

<ResponseField name="current_tick" type="number | null">
  Current tick for concentrated-liquidity pools.
</ResponseField>

<ResponseField name="current_sqrt_price" type="string | null">
  Q64.96 sqrt price integer string.
</ResponseField>

<ResponseField name="current_bin" type="number | null">
  Current bin id for bin-style AMMs.
</ResponseField>

<ResponseField name="details" type="object[] | null">
  Optional tick/bin/range detail rows (enabled by subscription params).
</ResponseField>

<ResponseField name="details[].tick" type="number | null">
  Single-tick locator (v3-style).
</ResponseField>

<ResponseField name="details[].lower_tick" type="number | null">
  Range lower bound.
</ResponseField>

<ResponseField name="details[].upper_tick" type="number | null">
  Range upper bound.
</ResponseField>

<ResponseField name="details[].bin_id" type="number | null">
  Single-bin locator.
</ResponseField>

<ResponseField name="details[].liquidity" type="string">
  Engine-native liquidity (integer string).
</ResponseField>

<ResponseField name="details[].amount0" type="string">
  Token0 raw amount at locator (integer string).
</ResponseField>

<ResponseField name="details[].amount1" type="string">
  Token1 raw amount at locator (integer string).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0301", "chain_id": 1, "params": {"include_details": true}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0301\", \"chain_id\": 1, \"params\": {\"include_details\": true}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0301\", \"chain_id\": 1, \"params\": {\"include_details\": true}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0301",
          "chain_id": 1,
          "params": {
              "include_details": True
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0301',
      chain_id: 1,
      params: {
        include_details: true
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0301", "chain_id": 1, "params": {"include_details": true}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0301",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 18934567,
      "block_time": "2025-11-11T18:42:15.123Z",
      "tx_index": 4,
      "log_index": 2,
      "reserves": [
        "169649594140000000000000",
        "60446403492000000000"
      ],
      "current_tick": 210130,
      "current_sqrt_price": "14614467034852101032872730522039888223787",
      "current_bin": null,
      "details": [
        {
          "tick": 210130,
          "lower_tick": 210120,
          "upper_tick": 210140,
          "bin_id": null,
          "liquidity": "123456789000000000000000000000000",
          "amount0": "1000000000000000000",
          "amount1": "2500000000"
        }
      ],
      "_tracing_id": "0301000000000000000000000000000000000000",
      "_parent_tracing_ids": [
        "0203000000000000000000000000000000000000"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# Swaps Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/swaps/overview

Subscribe to real-time per-swap fee accounting events.

## Overview

The Swaps stream provides real-time fee accounting for AMM pools, including executed amounts and fee splits.

## Stream Matrix

| Stream                                          | Summary                                  | Dataset ID |
| :---------------------------------------------- | :--------------------------------------- | :--------- |
| [Swap Fees](/wss-reference/evm/swaps/swap-fees) | Real-time per-swap fee accounting events | `0303`     |

## Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network.
</ParamField>

<ParamField type="string[]">
  Filter by specific BlockDB pool identifiers.
</ParamField>

<ParamField type="string[]">
  Filter by input token addresses.
</ParamField>

## See Also

* [Swaps Reference](/api-reference/evm/swaps/swap-fees) — For detailed schema descriptions.
* [Introduction](/wss-reference/overview/introduction) — Protocol and authentication details.


# Swap Fees
Source: https://docs.blockdb.io/wss-reference/evm/swaps/swap-fees

Subscribe to real-time per-swap fee accounting for pool economics and yield modeling.

## Overview

* **Dataset ID:** [`0303 - Liquidity Pool Swap Fees`](/data-catalog/evm/swaps/liquidity-pools-swap-fees)
* **Description:** Per-swap fee accounting: executed swap sizes plus computed fee amounts using the pool's fee terms (`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="string[]">
  Filter updates to specific BlockDB pool identifiers.
</ParamField>

<ParamField type="string[]">
  Filter by input token addresses (hex strings, 20 bytes, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height where the swap occurred.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="token_in" type="string">
  Address of the input token.
</ResponseField>

<ResponseField name="token_out" type="string">
  Address of the output token.
</ResponseField>

<ResponseField name="fee_token" type="string">
  Token address the fee is denominated in.
</ResponseField>

<ResponseField name="amount_in" type="string">
  Executed input amount (raw units, integer string).
</ResponseField>

<ResponseField name="amount_out" type="string">
  Executed output amount (raw units, integer string).
</ResponseField>

<ResponseField name="fee_amount_total" type="string">
  Total fee amount in `fee_token` units.
</ResponseField>

<ResponseField name="fee_amount_user" type="string | null">
  User/LP share of fees (raw units, nullable).
</ResponseField>

<ResponseField name="fee_amount_protocol" type="string | null">
  Protocol share of fees (raw units, nullable).
</ResponseField>

<ResponseField name="fee_amount_extra" type="string | null">
  Extra destination share of fees (raw units, nullable).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0303", "chain_id": 1, "params": {"token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0303\", \"chain_id\": 1, \"params\": {\"token_in_addresses\": [\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"]}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0303\", \"chain_id\": 1, \"params\": {\"token_in_addresses\": [\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"]}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0303",
          "chain_id": 1,
          "params": {
              "token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0303',
      chain_id: 1,
      params: {
        token_in_addresses: ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0303", "chain_id": 1, "params": {"token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0303",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19000042,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 15,
      "log_index": 88,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "amount_in": "5.000000000000000000",
      "amount_out": "15850.000000000000000000",
      "fee_amount_total": "0.015000000000000000",
      "fee_amount_user": "0.012000000000000000",
      "fee_amount_protocol": "0.003000000000000000",
      "fee_amount_extra": "0.000000000000000000",
      "_tracing_id": "0303c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0103c0ffee000000000000000000000000000000000000000000000000000001",
        "0204c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  }
  ```
</CodeGroup>


# Transfers Overview
Source: https://docs.blockdb.io/wss-reference/evm/transfers/overview

WebSocket streams for token transfer events.

## Endpoints

| Stream                                                          | Dataset | Table                                  |
| --------------------------------------------------------------- | ------- | -------------------------------------- |
| [Token transfers](/wss-reference/evm/transfers/token-transfers) | `0304`  | `blockdb_evm.b0304_token_transfers_v1` |

REST counterpart: [`POST /evm/transfers/token-transfers`](/api-reference/evm/transfers/token-transfers).


# Token Transfers
Source: https://docs.blockdb.io/wss-reference/evm/transfers/token-transfers

Subscribe to real-time token transfer events.

## Overview

* **Dataset ID:** [`0304 - Token Transfers`](/data-catalog/evm/transfers/token-transfers)
* **Description:** Token transfer events (native ETH, ERC-20, ERC-721, ERC-1155) produced by TokenTransfersEngine from transactions, internal transactions, and transfer logs.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-Transfers-Ethereum-And-EVM-Cryptocurrency-Data)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filter: sender addresses (hex, no `0x`).
</ParamField>

<ParamField type="string[]">
  Optional filter: recipient addresses (hex, no `0x`).
</ParamField>

<ParamField type="string[]">
  Optional filter: token contract addresses (hex, no `0x`); omit for native transfers where applicable.
</ParamField>

<ParamField type="string[]">
  Optional filter: transfer kinds (e.g. `native`, `erc20`, `erc721`, `erc1155`).
</ParamField>

## Message Fields

<ResponseField name="block_number" type="number">
  Block containing the transfer.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="log_index" type="number | null">
  Log index when sourced from a log; null when not applicable.
</ResponseField>

<ResponseField name="trace_address" type="string | null">
  Trace address for internal tx transfers (e.g. `"0"`, `"0.1"`); null for other types.
</ResponseField>

<ResponseField name="from_address" type="string">
  Sender address (hex).
</ResponseField>

<ResponseField name="to_address" type="string">
  Recipient address (hex).
</ResponseField>

<ResponseField name="token_address" type="string | null">
  Token contract; null for native ETH transfers.
</ResponseField>

<ResponseField name="amount_raw" type="string">
  Raw amount (integer string in token/native units).
</ResponseField>

<ResponseField name="amount_adj" type="string | null">
  Decimal-adjusted amount; null if decimals unknown or NFT.
</ResponseField>

<ResponseField name="token_id" type="string | null">
  NFT / ERC-1155 id when applicable.
</ResponseField>

<ResponseField name="transfer_type" type="integer">
  Transfer mechanism as integer enum (see [Transfer Type](/api-reference/enumerations/transfer-type)).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row lineage id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0304", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0304\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0304\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0304",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0304',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0304", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0304",
    "is_reorg": false,
    "data": {
      "block_number": 12345680,
      "block_time": "2025-10-29T00:01:23Z",
      "tx_index": 5,
      "log_index": 2,
      "trace_address": null,
      "from_address": "0000000000000000000000000000000000000000",
      "to_address": "0000000000000000000000000000000000000001",
      "token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "amount_raw": "1000000000000000000",
      "amount_adj": "1.0",
      "token_id": null,
      "transfer_type": 2,
      "_tracing_id": "0304000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0102000000000000000000000000000000000001",
        "0201000000000000000000000000000000000001"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>


# TVL Overview
Source: https://docs.blockdb.io/wss-reference/evm/tvl/overview

WebSocket stream for pool TVL (USD) snapshots.

## Stream

| Page                                      | Dataset | Table                                          |
| ----------------------------------------- | ------- | ---------------------------------------------- |
| [TVL USD](/wss-reference/evm/tvl/tvl-usd) | `0601`  | `blockdb_evm.b0601_liquidity_pools_tvl_usd_v1` |

REST: [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd).


# TVL USD
Source: https://docs.blockdb.io/wss-reference/evm/tvl/tvl-usd

Subscribe to real-time pool TVL snapshots in USD.

## Overview

* **Dataset ID:** [`0701 - Liquidity Pool TVL (USD)`](/data-catalog/evm/tvl/liquidity-pools-tvl-usd)
* **Description:** Pool TVL (Total Value Locked) snapshots in USD, computed from reserves multiplied by fiat prices. Grain: one row per (pool, event triple); `pool_uid` → `blockdb_evm.b0211_liquidity_pools_v1`.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-TVL-USD)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

<ParamField type="string[]">
  Optional filters: pool UIDs (32-byte hex, no `0x` prefix).
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  Pool identifier (hex).
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Observation block.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="token_amounts" type="string[]">
  Decimals-adjusted token amounts (decimal strings), aligned with pool token order.
</ResponseField>

<ResponseField name="tvl_usd" type="string">
  Total value locked in USD (decimal string).
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Lineage id (hex).
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0701", "chain_id": 1, "params": {}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0701\", \"chain_id\": 1, \"params\": {}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0701\", \"chain_id\": 1, \"params\": {}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0701",
          "chain_id": 1,
          "params": {}
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0701',
      chain_id: 1,
      params: {}
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0701", "chain_id": 1, "params": {}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0701",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "token_amounts": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "tvl_usd": "8750000.00",
      "_tracing_id": "0701c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  }
  ```
</CodeGroup>


# Yields Streams Overview
Source: https://docs.blockdb.io/wss-reference/evm/yields/overview

Subscribe to real-time rolling pool yield and ROI predictions.

## Overview

The Yields stream provides real-time updates to rolling yield/ROI predictions per pool.

## Stream Matrix

| Stream                                     | Summary                              | Dataset ID |
| :----------------------------------------- | :----------------------------------- | :--------- |
| [Yields](/wss-reference/evm/yields/yields) | Real-time pool yield/ROI predictions | `0411`     |

## Parameter Conventions

<ParamField type="number">
  Chain identifier for the target EVM network.
</ParamField>

<ParamField type="number">
  Target prediction horizon (e.g., 1, 7, 30).
</ParamField>

<ParamField type="string[]">
  Filter by specific BlockDB pool identifiers.
</ParamField>

## See Also

* [Yields Reference](/api-reference/evm/yields/yields) — For detailed schema descriptions.
* [Introduction](/wss-reference/overview/introduction) — Protocol and authentication details.


# Yields
Source: https://docs.blockdb.io/wss-reference/evm/yields/yields

Subscribe to real-time rolling pool yield and ROI predictions.

## Overview

* **Dataset ID:** [`0411 - Liquidity Pool Yields`](/data-catalog/evm/yields/liquidity-pools-yields)
* **Description:** Rolling yield/ROI predictions per pool over fixed horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D), based on historical swap fees (blockdb\_evm.b0303\_liquidity\_pools\_swap\_fees\_v1) and current reserves (latest blockdb\_evm.b0301\_liquidity\_pools\_reserves\_v1 snapshot).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Yields)

## Subscription Parameters

<ParamField type="number">
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField type="number">
  Target horizon in days (e.g., 1, 7, 30).
</ParamField>

<ParamField type="string[]">
  Filter updates to specific BlockDB pool identifiers.
</ParamField>

## Message Fields

<ResponseField name="pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="exchange_id" type="number">
  Exchange/DEX identifier.
</ResponseField>

<ResponseField name="type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="block_number" type="number">
  Block height of the prediction anchor.
</ResponseField>

<ResponseField name="block_time" type="string">
  Block time (ISO-8601).
</ResponseField>

<ResponseField name="tx_index" type="number">
  Transaction index.
</ResponseField>

<ResponseField name="log_index" type="number">
  Log index.
</ResponseField>

<ResponseField name="target_period_days" type="number">
  Target horizon in days.
</ResponseField>

<ResponseField name="observed_period_days" type="number">
  History actually used (must be `> 0` and `<= target_period_days`).
</ResponseField>

<ResponseField name="is_full_period" type="boolean">
  `true` when `observed_period_days == target_period_days`.
</ResponseField>

<ResponseField name="is_extrapolated" type="boolean">
  `true` when the row is scaled from shorter history.
</ResponseField>

<ResponseField name="extrapolation_factor" type="string">
  Scaling factor applied when extrapolating (string to preserve precision).
</ResponseField>

<ResponseField name="window_start_time" type="string">
  Start time of the observed window.
</ResponseField>

<ResponseField name="window_end_time" type="string">
  End time of the observed window.
</ResponseField>

<ResponseField name="tokens" type="string[]">
  Pool token addresses (aligned arrays index by this order).
</ResponseField>

<ResponseField name="current_reserves" type="string[]">
  Current reserves per token (decimals-adjusted).
</ResponseField>

<ResponseField name="volume_observed" type="string[]">
  Observed traded volume per token in the window.
</ResponseField>

<ResponseField name="volume_predicted" type="string[]">
  Predicted traded volume per token for the target horizon.
</ResponseField>

<ResponseField name="user_fees_observed" type="string[]">
  Observed user/LP fees per token in the window.
</ResponseField>

<ResponseField name="user_fees_predicted" type="string[]">
  Predicted user/LP fees per token for the target horizon.
</ResponseField>

<ResponseField name="roi_predicted" type="string[]">
  Predicted ROI fraction per token for the target horizon.
</ResponseField>

<ResponseField name="_tracing_id" type="string">
  Row-level lineage hash for correlation.
</ResponseField>

<ResponseField name="_parent_tracing_ids" type="string[]">
  Parent lineage ids (hex).
</ResponseField>

<ResponseField name="_created_at" type="string">
  Record creation time (ISO-8601).
</ResponseField>

<ResponseField name="_updated_at" type="string">
  Record last update time (ISO-8601).
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0411", "chain_id": 1, "params": {"target_period_days": 7}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 512];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0411\", \"chain_id\": 1, \"params\": {\"target_period_days\": 7}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0411\", \"chain_id\": 1, \"params\": {\"target_period_days\": 7}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0411",
          "chain_id": 1,
          "params": {
              "target_period_days": 7
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0411',
      chain_id: 1,
      params: {
        target_period_days: 7
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0411", "chain_id": 1, "params": {"target_period_days": 7}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0411",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "target_period_days": 30,
      "observed_period_days": 30,
      "is_full_period": true,
      "is_extrapolated": false,
      "extrapolation_factor": "1.000000",
      "window_start_time": "2025-11-20T12:34:56Z",
      "window_end_time": "2025-12-20T12:34:56Z",
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "current_reserves": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "volume_observed": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "volume_predicted": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_observed": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_predicted": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "roi_predicted": [
        "0.028800000000000000",
        "0.000000000000000000"
      ],
      "_tracing_id": "0411c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0303c0ffee000000000000000000000000000000000000000000000000000001",
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  }
  ```
</CodeGroup>


# Connection Management
Source: https://docs.blockdb.io/wss-reference/overview/connection-management

Heartbeats, timeouts, reconnection, and backpressure best practices for BlockDB WSS clients.

## Heartbeats (ping/pong)

BlockDB sends periodic WebSocket `ping` frames. Clients must respond with `pong` to keep the connection alive.

<Note>
  Most WebSocket libraries handle `ping`/`pong` automatically. If yours does not, enable keepalives or implement `pong` responses.
</Note>

## Idle timeout

Connections with no active subscriptions (or missing heartbeat responses) may be terminated after an idle period.

* **Recommendation**: subscribe soon after connecting and keep `ping`/`pong` enabled.
* **If you intentionally idle**: close the socket gracefully and reconnect when needed.

## Reconnection strategy

You should assume transient disconnects (network, deploys, backpressure). Use exponential backoff with jitter:

* 1s → 2s → 4s → 8s … (cap at \~30s)
* add random jitter (e.g., ±20%)

<CodeGroup>
  ```bash bash theme={null}
  # Reconnect loop with exponential backoff (cap 30s).
  # Note: wscat is interactive; when the socket closes, the command exits and the loop retries.
  attempt=0
  while true; do
    delay=$((2 ** attempt))
    if [ "$delay" -gt 30 ]; then delay=30; fi

    echo "Connecting (attempt=$attempt)..."
    wscat -c wss://api.blockdb.io/v1/evm/ \
      -H "Authorization: Bearer $BLOCKDB_API_KEY" \
      -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'

    echo "Disconnected. Sleeping ${delay}s..."
    sleep "$delay"
    attempt=$((attempt + 1))
  done
  ```

  ```c C theme={null}
  // Sketch: reconnect with backoff and resubscribe (pseudocode-ish)
  #include <stdio.h>
  #include <unistd.h>

  int main(void) {
      int attempt = 0;
      for (;;) {
          int delay = 1 << attempt;
          if (delay > 30) delay = 30;

          // connect_ws("wss://api.blockdb.io/v1/evm/");
          // send("{\"action\":\"subscribe\",\"chain_id\":1,\"dataset_id\":\"0101\",\"params\":{}}");
          // while (connected) { read_messages(); }

          fprintf(stderr, "disconnected; retrying in %ds\n", delay);
          sleep(delay);
          attempt++;
      }
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          var subMsg = "{\"action\":\"subscribe\",\"chain_id\":1,\"dataset_id\":\"0101\",\"params\":{}}";

          for (var attempt = 0; ; attempt++) {
              var delayMs = Math.Min(30_000, (int)(1000 * Math.Pow(2, attempt)));
              try {
                  using var ws = new ClientWebSocket();
                  ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable(\"BLOCKDB_API_KEY\")}");
                  await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

                  await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

                  var buffer = new byte[1024 * 32];
                  while (ws.State == WebSocketState.Open) {
                      var res = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
                      if (res.MessageType == WebSocketMessageType.Close) break;
                      Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, res.Count));
                  }
              } catch (Exception ex) {
                  Console.WriteLine(ex.Message);
              }

              await Task.Delay(delayMs);
          }
      }
  }
  ```

  ```python Python theme={null}
  # pip install websocket-client
  import json
  import os
  import random
  import time
  import websocket

  SUB = {"action": "subscribe", "chain_id": 1, "dataset_id": "0101", "params": {}}

  def run_once():
      def on_open(ws):
          ws.send(json.dumps(SUB))

      def on_message(ws, message):
          # Handle subscribe_response/unsubscribe_response/update
          print(message)

      ws = websocket.WebSocketApp(
          "wss://api.blockdb.io/v1/evm/",
          header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
          on_open=on_open,
          on_message=on_message,
      )
      ws.run_forever()

  attempt = 0
  while True:
      run_once()
      base = min(30, 2 ** attempt)
      time.sleep(base * (0.8 + random.random() * 0.4))
      attempt += 1
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const URL = 'wss://api.blockdb.io/v1/evm/';
  const SUBS = [
    { action: 'subscribe', chain_id: 1, dataset_id: '0101', params: {} }
  ];

  function connect(attempt = 0) {
    const ws = new WebSocket(URL, {
      headers: { Authorization: `Bearer ${process.env.BLOCKDB_API_KEY}` }
    });

    ws.on('open', () => {
      attempt = 0;
      for (const msg of SUBS) ws.send(JSON.stringify(msg));
    });

    ws.on('message', (data) => {
      // Handle subscribe_response/unsubscribe_response/update
      // Keep this handler fast; offload heavy work.
    });

    ws.on('close', () => {
      const base = Math.min(30_000, 1000 * 2 ** attempt);
      const jitter = base * (0.8 + Math.random() * 0.4);
      setTimeout(() => connect(attempt + 1), jitter);
    });
  }

  connect();
  ```

  ```go Go theme={null}
  package main

  import (
  	"log"
  	"math/rand"
  	"net/http"
  	"os"
  	"time"

  	"github.com/gorilla/websocket"
  )

  func main() {
  	sub := []byte(`{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}`)

  	for attempt := 0; ; attempt++ {
  		header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  		c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  		if err != nil {
  			sleepWithBackoff(attempt)
  			continue
  		}

  		_ = c.WriteMessage(websocket.TextMessage, sub)
  		for {
  			_, msg, err := c.ReadMessage()
  			if err != nil {
  				break
  			}
  			log.Printf("%s\n", msg)
  		}
  		_ = c.Close()
  		sleepWithBackoff(attempt)
  	}
  }

  func sleepWithBackoff(attempt int) {
  	base := 1 << attempt
  	if base > 30 {
  		base = 30
  	}
  	jitter := 0.8 + rand.Float64()*0.4
  	time.Sleep(time.Duration(float64(base)*jitter) * time.Second)
  }
  ```
</CodeGroup>

## Resubscribe after reconnect

The WebSocket connection state is not preserved across reconnects. Maintain a local list of active subscriptions and re-send `subscribe` messages after `open`.

For data continuity and reconciliation (especially around reorgs), see: [Reliability & Reorgs](/wss-reference/overview/reliability-and-reorgs).

## Backpressure & rate control

If the server cannot deliver messages fast enough (or your client cannot process them fast enough), the connection may be closed to protect the system.

* Common signal: **close code 1013 `TRY_AGAIN_LATER`**
* What to do:
  * reconnect with **longer backoff** (and jitter)
  * **reduce** subscription count
  * add or tighten **filters** (`params`) on high-volume streams
  * move heavy processing off the receive loop

See: [WSS Error Codes](/troubleshooting/error-codes/wss/home)

## Logging & support

When debugging connection stability, always log:

* close code + reason (if provided)
* timestamp (UTC)
* the last `subscribe` message(s) you sent (redact API key)

## See also

* [Quickstart](/wss-reference/overview/quickstart)
* [Errors](/wss-reference/overview/errors)
* [Runbook · WSS Connection Issues](/troubleshooting/runbooks/wss-connection-issues)
* [WSS Error Codes](/troubleshooting/error-codes/wss/home)


# Errors
Source: https://docs.blockdb.io/wss-reference/overview/errors

Error responses and WebSocket close codes for BlockDB WSS streams.

## Where errors appear

BlockDB WSS errors can surface in two places:

* **Handshake / connection layer**: the server may refuse the upgrade (HTTP error) or close the socket with a WebSocket close code.
* **Protocol layer**: the server acknowledges `subscribe` / `unsubscribe` with a `*_response` message. Failures are returned as `status: "error"` with a structured `error` object.

## Protocol errors (subscribe/unsubscribe)

If a request is invalid (bad parameters, auth scope, limits), you'll receive a response message:

<CodeGroup>
  ```json subscribe_response (error) theme={null}
  {
    "action": "subscribe",
    "chain_id": 1,
    "dataset_id": "0101",
    "status": "error",
    "error": {
      "code": "BAD_REQUEST",
      "message": "The request contains invalid or missing parameters.",
      "hint": "Ensure 'params' matches the stream filters and that addresses are 20-byte hex strings with no 0x prefix.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          { "name": "params.topic_zeros[0]", "reason": "invalid_format" }
        ]
      },
      "docs_url": "https://docs.blockdb.io/wss-reference/overview/errors"
    }
  }
  ```

  ```json unsubscribe_response (error) theme={null}
  {
    "action": "unsubscribe",
    "chain_id": 1,
    "dataset_id": "0101",
    "status": "error",
    "error": {
      "code": "NOT_SUBSCRIBED",
      "message": "No active subscription exists for this chain_id + dataset_id on the connection.",
      "severity": "warning",
      "retryable": false
    }
  }
  ```
</CodeGroup>

## Error object fields

The `error` object is a stable schema designed for both humans and machines.

<ResponseField name="code" type="string">
  Machine-readable error code.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable summary of what went wrong.
</ResponseField>

<ResponseField name="hint" type="string">
  Optional diagnostic hint that points to the most common fix.
</ResponseField>

<ResponseField name="severity" type="string">
  One of `info`, `warning`, `error`, `critical`.
</ResponseField>

<ResponseField name="retryable" type="boolean">
  Whether retrying the same operation can succeed (typically with backoff).
</ResponseField>

<ResponseField name="details" type="object">
  Optional structured metadata (e.g., invalid field list, limit values, allowed enums).
</ResponseField>

<ResponseField name="docs_url" type="string">
  Optional documentation link relevant to this error.
</ResponseField>

## WebSocket close codes

Some failures are communicated by closing the WebSocket (especially auth/policy and backpressure).

* See: [WSS Error Codes](/troubleshooting/error-codes/wss/home)
* Typical handling:
  * **1008 POLICY\_VIOLATION**: verify API key / scope, then reconnect.
  * **1013 TRY\_AGAIN\_LATER**: treat as backpressure; back off and reduce subscriptions/filters.
  * **1011 INTERNAL\_ERROR**: retry with jitter; contact support if persistent.

## Practical handling guidance

* **If `status: "error"` and `retryable: false`**: fix the request (usually `chain_id`, `dataset_id`, or `params` formatting).
* **If `status: "error"` and `retryable: true`**: retry with exponential backoff and jitter.
* **If the socket closes**: use the close code to decide whether to refresh credentials, reduce load, or retry later.

## See also

* [Quickstart](/wss-reference/overview/quickstart)
* [Connection Management](/wss-reference/overview/connection-management)
* [WSS Error Codes](/troubleshooting/error-codes/wss/home)


# Introduction
Source: https://docs.blockdb.io/wss-reference/overview/introduction

Protocol details for BlockDB's WebSocket (WSS) feed: authentication, subscription lifecycle, and reliability.

## Overview

BlockDB WebSocket (WSS) streams provide low-latency, push-based access to real-time blockchain events. Unlike REST APIs that require polling, WSS streams deliver data as soon as it is processed by our ingestion engine—typically under 150 ms from the block being seen on the P2P network.

<Note>
  BlockDB's WebSocket delivery is currently in the development and testing phase. If you encounter issues or have specific throughput requirements, please contact us at [support@blockdb.io](mailto:support@blockdb.io).
</Note>

## Endpoints

We provide a unified streaming endpoint for all EVM datasets.

| Environment    | Protocol | Endpoint                       |
| :------------- | :------- | :----------------------------- |
| **Production** | `WSS`    | `wss://api.blockdb.io/v1/evm/` |

## Authentication

Authentication is performed during the WebSocket handshake using a Bearer token in the `Authorization` header.

```http theme={null}
GET /v1/evm/stream HTTP/1.1
Host: api.blockdb.io
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer <YOUR_API_KEY>
```

Alternatively, for clients that do not support custom headers during the handshake, you can pass the API key via the `api_key` query parameter:
`wss://api.blockdb.io/v1/evm/?api_key=YOUR_API_KEY`

## Subscription Lifecycle

Once connected, you must send a JSON message to subscribe to specific datasets. The server will acknowledge your request with a status message.

### 1. Subscribe

To start receiving data, send a `subscribe` action with the target `chain_id`, `dataset_id`, and any optional filters in `params`.

```json theme={null}
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "params": {}
}
```

**Response Example (Success):**

```json theme={null}
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "subscribe",
  "status": "success"
}
```

**Response Example (Error):**

```json theme={null}
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "subscribe",
  "status": "error",
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request contains invalid or missing parameters.",
    "hint": "Ensure 'chain_id' is provided and valid.",
    "severity": "error",
    "retryable": false,
    "details": {
      "invalid_parameters": [
        {
          "name": "chain_id",
          "reason": "missing"
        }
      ]
    },
    "docs_url": "https://docs.blockdb.io/wss-reference/overview/introduction"
  }
}
```

### 2. Unsubscribe

To stop receiving data from a stream without closing the connection:

```json theme={null}
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101"
}
```

**Response Example (Success):**

```json theme={null}
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "unsubscribe",
  "status": "success"
}
```

## Message Format

Every data message delivered by the stream follows a consistent envelope:

<ResponseField name="chain_id" type="number">
  The identifier of the EVM network.
</ResponseField>

<ResponseField name="dataset_id" type="string">
  The identifier of the dataset (e.g., `0101` for Blocks).
</ResponseField>

<ResponseField name="data" type="object">
  The payload containing the actual record. See specific stream pages for schema details.
</ResponseField>

## Connection Management

* **Heartbeats**: The server sends periodic `ping` frames. Clients must respond with `pong` frames to keep the connection alive. Most WebSocket libraries handle this automatically.
* **Idle Timeout**: Connections with no active subscriptions or heartbeat responses for more than 60 seconds may be terminated.
* **Reconnection**: In the event of a disconnect, clients should implement exponential backoff.

## Reliability & Reorgs

* **Ordering**: Messages within a single stream are delivered in the order they are processed.
* **Reorganizations**: BlockDB is reorg-aware. When a chain reorganization occurs, the stream will emit messages with `is_reorg: true` to indicate that the update is a canonical correction.
* **Lineage**: Every message includes a `_tracing_id`, which can be used to correlate real-time events with historical archive data.


# Quickstart
Source: https://docs.blockdb.io/wss-reference/overview/quickstart

Connect, subscribe, receive updates, and unsubscribe from BlockDB WSS streams in minutes.

## What you'll do

* **Connect** to `wss://api.blockdb.io/v1/evm/`
* **Authenticate** with `Authorization: Bearer <API_KEY>` (or `?api_key=` fallback)
* **Subscribe** to a dataset (example: Blocks `dataset_id: "0101"`)
* **Receive** `update` messages
* **Unsubscribe** cleanly without closing the socket

## Prerequisites

* A valid BlockDB API key (set as `BLOCKDB_API_KEY`)
* A WebSocket client (CLI or SDK)

## 1) Connect

<CodeGroup>
  ```bash bash theme={null}
  # CLI: connect (wscat)
  export BLOCKDB_API_KEY="..."
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY"
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              printf("connected\n");
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %.*s\n", (int)len, (const char *)in);
              break;
          case LWS_CALLBACK_CLIENT_CONNECTION_ERROR:
              printf("connection error\n");
              break;
          default:
              break;
      }
      return 0;
  }

  static struct lws_protocols protocols[] = {
      { "blockdb", callback_blockdb, 0, 4096, 0, NULL, 0 },
      { NULL, NULL, 0, 0, 0, NULL, 0 }
  };

  int main(void) {
      struct lws_context_creation_info info;
      memset(&info, 0, sizeof(info));
      info.port = CONTEXT_PORT_NO_LISTEN;
      info.protocols = protocols;

      struct lws_context *context = lws_create_context(&info);
      if (!context) return 1;

      struct lws_client_connect_info ccinfo;
      memset(&ccinfo, 0, sizeof(ccinfo));
      ccinfo.context = context;
      ccinfo.address = "api.blockdb.io";
      ccinfo.port = 443;
      ccinfo.path = "/v1/evm/?api_key=YOUR_API_KEY"; // fallback for clients without custom headers
      ccinfo.host = ccinfo.address;
      ccinfo.origin = ccinfo.address;
      ccinfo.ssl_connection = LCCSCF_USE_SSL;

      if (!lws_client_connect_via_info(&ccinfo)) return 1;

      while (lws_service(context, 0) >= 0) {}
      lws_context_destroy(context);
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);
          Console.WriteLine("connected");
      }
  }
  ```

  ```python Python theme={null}
  # pip install websocket-client
  import os
  import websocket

  def on_open(ws):
      print("connected")

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_open=on_open,
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  // npm i ws
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { Authorization: `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => console.log('connected'));
  ws.on('close', (code, reason) => console.log('closed', code, reason?.toString?.()));
  ws.on('error', (err) => console.error('error', err));
  ```

  ```go Go theme={null}
  package main

  import (
  	"log"
  	"net/http"
  	"os"

  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()
  	log.Println("connected")
  }
  ```
</CodeGroup>

<Note>
  If your client cannot send headers during the handshake, use the query parameter fallback:
  `wss://api.blockdb.io/v1/evm/?api_key=YOUR_API_KEY`
</Note>

## 2) Subscribe (client → server)

This starts a stream. You must provide:

* `action: "subscribe"`
* `chain_id` (EVM chain)
* `dataset_id` (stream dataset)
* `params` (stream-specific filters; use `{}` if none)

<CodeGroup>
  ```bash bash theme={null}
  # Subscribe to Blocks (dataset_id 0101) on Ethereum mainnet (chain_id 1)
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 256];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\":\"subscribe\",\"chain_id\":1,\"dataset_id\":\"0101\",\"params\":{}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %.*s\n", (int)len, (const char *)in);
              break;
          default:
              break;
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\":\"subscribe\",\"chain_id\":1,\"dataset_id\":\"0101\",\"params\":{}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);
      }
  }
  ```

  ```python Python theme={null}
  import json

  def on_open(ws):
      ws.send(json.dumps({
          "action": "subscribe",
          "chain_id": 1,
          "dataset_id": "0101",
          "params": {}
      }))
  ```

  ```javascript Node.js theme={null}
  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      chain_id: 1,
      dataset_id: '0101',
      params: {}
    }));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"log"
  	"net/http"
  	"os"

  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}`
  	if err := c.WriteMessage(websocket.TextMessage, []byte(sub)); err != nil {
  		log.Fatal("write:", err)
  	}
  }
  ```
</CodeGroup>

## 3) Handle messages (server → client)

After subscribing you will receive:

* `subscribe_response` (ack, success or error)
* `update` messages (the live data)

```json subscribe_response (success) theme={null}
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}
```

```json update theme={null}
{
  "chain_id": 1,
  "dataset_id": "0101",
  "is_reorg": false,
  "data": {
    "block_number": 12345678,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "timestamp_utc": "2025-11-11T18:42:15.123Z",
    "_tracing_id": "010100000000000000000000000000000000"
  }
}
```

## 4) Unsubscribe (client → server)

Unsubscribe stops a stream without closing the WebSocket.

<CodeGroup>
  ```bash bash theme={null}
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action":"unsubscribe","chain_id":1,"dataset_id":"0101"}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 256];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\":\"unsubscribe\",\"chain_id\":1,\"dataset_id\":\"0101\"}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
          default:
              break;
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var msg = "{\"action\":\"unsubscribe\",\"chain_id\":1,\"dataset_id\":\"0101\"}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(msg)), WebSocketMessageType.Text, true, CancellationToken.None);
      }
  }
  ```

  ```python Python theme={null}
  import json

  def unsubscribe(ws):
      ws.send(json.dumps({
          "action": "unsubscribe",
          "chain_id": 1,
          "dataset_id": "0101"
      }))
  ```

  ```javascript Node.js theme={null}
  ws.send(JSON.stringify({
    action: 'unsubscribe',
    chain_id: 1,
    dataset_id: '0101'
  }));
  ```

  ```go Go theme={null}
  package main

  import (
  	"log"
  	"net/http"
  	"os"

  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	unsub := `{"action":"unsubscribe","chain_id":1,"dataset_id":"0101"}`
  	if err := c.WriteMessage(websocket.TextMessage, []byte(unsub)); err != nil {
  		log.Fatal("write:", err)
  	}
  }
  ```
</CodeGroup>

**unsubscribe\_response (success):**

```json theme={null}
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}
```

## Next steps

* Browse available streams: [EVM Streams Overview](/wss-reference/evm/overview)
* Common error patterns and payload shape: [Errors](/wss-reference/overview/errors)
* Reconnect strategy and timeouts: [Connection Management](/wss-reference/overview/connection-management)


# Reliability & Reorgs
Source: https://docs.blockdb.io/wss-reference/overview/reliability-and-reorgs

Ordering guarantees, deduplication, and how to handle EVM chain reorganizations in BlockDB WSS streams.

## Delivery Model

BlockDB WebSocket (WSS) streams are optimized for **real-time, low-latency delivery**. They are intended to trigger actions and update local caches, not to serve as a persistent, gap-free historical archive.

* **Idempotency is Required**: Messages can occasionally be redelivered after a reconnection.
* **Connection Loss**: Standard WebSocket connections do not buffer messages while a client is offline.
* **Completeness**: While we aim for 100% delivery, mission-critical systems should reconcile WSS data with our [REST APIs](/api-reference/evm/overview) or [Bulk Exports](/pricing/home#bulk-export-sftp-s3-azure--more).

## Standard Update Envelope

Every data update sent by the server follows a consistent envelope. This allows you to route messages to the correct handler before parsing the stream-specific `data` payload.

<ResponseField name="chain_id" type="number">
  The EVM network identifier.
</ResponseField>

<ResponseField name="dataset_id" type="string">
  The 4-digit ID of the stream (e.g., `0101` for Blocks).
</ResponseField>

<ResponseField name="is_reorg" type="boolean">
  If `true`, this message is a **reorg correction**. It indicates that a previously emitted record at this height/index has been eclipsed and this new message contains the updated canonical state.
</ResponseField>

<ResponseField name="data" type="object">
  The stream-specific payload.
</ResponseField>

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0101",
    "is_reorg": false,
    "data": {
      "block_number": 12345678,
      "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
      "parent_block_hash": "f78e26c5959a94d6a62ed3837f5dcecf0d3761bf0a502e12a08fd7bc44c8568d",
      "miner": "0000000000000000000000000000000000000000",
      "gas_limit": 30000000,
      "size": 124836,
      "timestamp_utc": "2025-11-11T18:42:15.123Z",
      "_tracing_id": "010100000000000000000000000000000000",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  }
  ```
</CodeGroup>

## Ordering & Deduplication

### Ordering Guarantees

* **Per-Stream**: Messages within a single `dataset_id` on a specific `chain_id` are delivered in the exact order they are processed by our ingestion engine.
* **Cross-Stream**: There is **no global ordering** guarantee across different datasets. For example, a `Logs` message might arrive slightly before or after the `Blocks` message for the same height.

### Deduplication

Most `data` payloads include a `_tracing_id`. This is a unique, deterministic hash of the record.

* **Strategy**: Maintain a small LRU cache of recently seen `_tracing_id`s to skip duplicates.
* **Alternative**: If a stream lacks `_tracing_id`, use the natural primary key (e.g., `tx_hash` + `log_index`).

## Handling Chain Reorganizations (Reorgs)

EVM chains are probabilistic; blocks can be "reorged" out of the canonical chain after they are mined. BlockDB is reorg-aware and provides explicit signals so your application stays in sync with the canonical chain.

### The `is_reorg` Signal

When a reorg occurs, BlockDB emits a new message for the affected record with **`is_reorg: true`**.

1. **Detection**: Your handler sees `is_reorg: true`.
2. **Action**: Treat this as an **overwrite**. If you have already stored or processed a record at this `block_number` (or `tx_hash`), replace it with the data in the new message.
3. **Propagation**: If you have derived state (e.g., a user's balance), you may need to recalculate it using the new canonical data.

<Tip>
  **Maximum Reorg Depth**: You can find the maximum expected reorg depth for each chain on the [Data Freshness](/data-catalog/overview/data-freshness) page. This is usually the window within which corrections may occur.
</Tip>

## Practical Implementation Guidance

To build a production-grade stream consumer, we recommend the following patterns:

* **Upsert Logic**: Design your database/cache handlers to perform `UPSERT` operations. This naturally handles both duplicates and reorg corrections.
* **Stateless Triggers**: If using WSS to trigger external actions (like sending an email), consider waiting for a specific number of block confirmations or verify the event via REST API before executing.
* **The Reconciliation Loop**:
  * Use WSS for **Real-time UI** and **Low-latency actions**.
  * Periodically (e.g., every 5 minutes) query the [REST API](/api-reference/evm/overview) for the last few blocks to ensure no messages were missed during transient network blips.

## See Also

* [Quickstart](/wss-reference/overview/quickstart) - Connect and subscribe in minutes.
* [Connection Management](/wss-reference/overview/connection-management) - Heartbeats and reconnection.
* [Dataset ID](/api-reference/enumerations/dataset-id) — How `dataset_id` maps to tables and `_tracing_id` joins rows across exports.