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 <JWT_OR_API_KEY>` |
| **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.
- **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 → **Lineage** and **Verification** (`/api-reference/evm/lineage/overview`, `/api-reference/evm/verification/overview`).

---

## 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 token → fix `Authorization: Bearer <token>`.
- **403** (FORBIDDEN): Key lacks permission → check plan/scope.
- **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. 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, start from `/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).