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

# 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>