# Catalog-first quickstart

To obtain blockchain data with Testril, discover a supported metric, bind the requested scope, check coverage, materialize missing blocks, read values, and verify provenance. Materialization and reading have separate payment gates; confirm spending before settlement. First [connect and discover the live contract](/agents/connection/).

## 1. Discover the chain and template

Call `inspect` with `subject: "chains"`, then `subject: "functions"`. Confirm the requested chain is configured. Select a template whose semantics match the operator's request.

For example, **if advertised**:

```json
{"tool":"inspect","arguments":{"subject":"function","function_slug":"erc20.token_balance"}}
```

Read its `params` and `row` schemas, descriptions, and defaults. The catalog's Function names are metric templates; they are not MCP tools.

## 2. Bind the scope

The following addresses and chain are placeholders. Substitute operator-supplied values, and use exactly the parameter names advertised by the selected template.

```json
{"tool":"bind","arguments":{"function_slug":"erc20.token_balance","chain_id":1,"params":{"reads":{"tokens":["<TOKEN_ADDRESS>"],"owners":["<WALLET_ADDRESS>"]}}}}
```

Proceed only on `outcome: "success"`. Save the returned `bound_function_id`. Binding creates an identity and scope, not an indexed dataset. `created: false` does not prove the requested window is covered.

## 3. Check coverage and choose the window

```json
{"tool":"inspect","arguments":{"subject":"bound_function","bound_function_id":"<BOUND_FUNCTION_ID>"}}
```

Read `materialized`, `materializing`, and `active_jobs`. Choose a requested half-open block interval `[from_block, to_block)` using the correct chain's `head` and the operator's intended period. The head is not a finality guarantee. Example block numbers below illustrate syntax; they do not prescribe a useful query window.

## 4. Materialize missing blocks

```json
{"tool":"materialize","arguments":{"bound_function_id":"<BOUND_FUNCTION_ID>","from_block":100,"to_block":110}}
```

If payment is required, read x402 `PaymentRequired` from
`structuredContent`/`content[0]` and the quote `{quote_id, amount, lines}` from
`content[1]` of the MCP error result. Inspect `lines`, `amount`, and `accepts`,
obtain spending authorization, and prepare the signed PaymentPayload for an
offered rail.
Read exact quote values from `amount.atoms` and line-item atom values; use each
money object's `usd` only for display. The x402 `accepts[].amount` field remains
a bare atom string and must equal the quoted charge.

```json
{"tool":"materialize","arguments":{"bound_function_id":"<BOUND_FUNCTION_ID>","from_block":100,"to_block":110},"_meta":{"x402/payment":{"x402Version":2,"scheme":"<OFFERED_SCHEME>","accepted":"<ACCEPTS_ROW>","payload":"<SIGNED_FIELDS>"}}}
```

The host attaches `_meta`; do not put a private key in tool arguments. Preserve
the returned `_meta["x402/payment-response"]` receipt.

A successful accepted job can still be running. Inspect the returned `job.job_id` and the bound function's coverage before reading. Start paid execution within the quote's 120-second lifetime.

## 5. Read values

```json
{"tool":"read","arguments":{"bound_function_id":"<BOUND_FUNCTION_ID>","from_block":100,"to_block":110}}
```

Reading has its own pay gate. If payment is required, retry the same `read`
arguments with the signed PaymentPayload attached in MCP transport metadata.

A successful read returns bare `values`, one row per block and key with all its attributes, typed by the Function’s `row` schema from inspect. Within fully covered blocks, absent rows follow the Function's declared emission rules; an unavailable window is not a zero balance.

## 6. Verify the source window

Use the same bound identity and exact half-open window; there is no attribute selector:

```json
{"tool":"provenance","arguments":{"bound_function_id":"<BOUND_FUNCTION_ID>","from_block":100,"to_block":110}}
```

Keep the result identity, exact window, values, source block hashes, and applicable digest together. See [provenance verification](/agents/provenance/) for limits and interpretation.