LLM Onboarding

# 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>", "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 `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.