# Verifiable agent answers

This guide shows how an AI agent can give an answer built on Arche data that its
reader can check for themselves, without an Arche account.

## The problem

When an agent writes "Apple earned 24.78 billion dollars in its second fiscal
quarter of 2025", the
reader has no way to tell whether the figure came from a filing, from another
source, or from the model itself. A link to a filing helps, but it does not show
that the agent read that filing on that date.

A replay token closes that gap. It names one query, at one point in time, and
the exact result Arche returned for it. Anyone holding the token can ask Arche
to run the query again and say whether it still returns the same data.

## Get a replay token

The [MCP](https://docs.arche.fi/mcp) as-of tools, `provenance_as_of` and
`financials_get_as_of_snapshot`, return a `replay_token` and a `verify_url`
with every page of statements, beside `snapshot_hash`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "provenance_as_of",
    "arguments": {
      "cik": "AAPL",
      "as_of": "2025-06-30",
      "statement_type": "INCOME_STATEMENT"
    }
  }
}
```

```json
{
  "replay_token": "f111746faeaa0c647c2032f58e8aeaa84287bc44c4484b834c813e5e613d973b",
  "verify_url": "https://arche.fi/verify/f111746faeaa0c647c2032f58e8aeaa84287bc44c4484b834c813e5e613d973b"
}
```

The token covers the statements on that page and their values. Over HTTP, the
same token comes from `POST /v1/query/execute`; see
[Deterministic replay](https://docs.arche.fi/coverage#deterministic-replay).

`replay_token` is `null` on the rare page for which a token could not be
created. Quote the figures with their accessions as usual in that case.

## Quote the token

Have the agent quote three things with each figure it reports:

1. the figure itself
2. the SEC accession number of the filing it came from
3. the `verify_url`

For example:

> Apple's net income for the second quarter of fiscal 2025 was 24,780 million
> dollars, on revenue of 95,359 million (accession 0000320193-25-000057).
> Verify:
> <https://arche.fi/verify/f111746f…>

An instruction in the agent's system prompt is enough: "When you quote a figure
from Arche, give its accession number and the `verify_url` from the same
result."

## Verify without a key

The reader opens the `verify_url`. The page re-runs the query and shows whether
it still matches, with each filing it read linked to sec.gov.

The page reads a public route that needs no API key:

```bash
curl "https://api.arche.fi/v1/query/verify/REPLAY_TOKEN"
```

```json
{
  "data": {
    "replay_token": "f111746faeaa0c647c2032f58e8aeaa84287bc44c4484b834c813e5e613d973b",
    "verdict": "MATCHES",
    "matches_original_result": true,
    "query_type": "financials_as_of_page",
    "parameters": {
      "cik": "0000320193",
      "statement_type": "INCOME_STATEMENT",
      "latest_only": true,
      "audit_mode": false,
      "limit": 20,
      "offset": 0
    },
    "as_of_date": "2025-06-30",
    "created_at": "2026-10-13T12:24:46Z",
    "result_hash": "243efd1ffb986914dbd89f432f67764af5dd169b5eec1306e163936360f3f94d",
    "recomputed_result_hash": "243efd1ffb986914dbd89f432f67764af5dd169b5eec1306e163936360f3f94d",
    "accessions": ["0000320193-25-000057"],
    "verified_at": "2026-10-13T12:50:14Z"
  }
}
```

The response names the query, its hashes and the accession numbers of the
filings the answer was read from. It returns no figures: the reader compares the
agent's figures with the filings themselves on sec.gov. To read the original
figures back, replay the token with an API key at
[`GET /v1/query/replay/{replay_token}`](https://docs.arche.fi/coverage#deterministic-replay).

An unknown token returns `404` with `QUERY_REPLAY_NOT_FOUND`. The route counts
against the snapshot [rate limit](https://docs.arche.fi/rate-limits), by caller address rather than
by key.

## Reading the verdict

- `MATCHES` (verdict): Re-running the query returns the same data the agent was given.
  `matches_original_result` says whether it is identical byte for byte.
- `DOES_NOT_MATCH` (verdict): The query returns different data today from the data the agent was given.
  Compare the agent's figures with the filings named in `accessions`.
- `NOT_RECOMPUTED` (verdict): The query can no longer be re-run. The record of the original result is
  still held, and the keyed replay route still returns it.

## Verify from an agent

An agent can run the same check with the `replay_verify` MCP tool, which takes
`replay_token` and returns the verdict, the query, its hashes, the accessions
and `verify_url`. Use it when one agent checks another's answer, or to confirm
a token before quoting it.

## Tokens from code

Code that does not use MCP gets a token from `POST /v1/query/execute` with the
`financials_as_of_page` query type, which selects statements as the as-of page
route does. With the same parameters the MCP tool used, it returns the same
token:

```bash
curl -X POST "https://api.arche.fi/v1/query/execute" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "query_type": "financials_as_of_page",
    "as_of_date": "2025-06-30",
    "include_result": true,
    "parameters": {
      "cik": "0000320193",
      "statement_type": "INCOME_STATEMENT",
      "latest_only": true,
      "audit_mode": false,
      "offset": 0,
      "limit": 20
    }
  }'
```

`data.manifest.replay_token` is
`f111746faeaa0c647c2032f58e8aeaa84287bc44c4484b834c813e5e613d973b`, the token in
the MCP example above, and `data.result` holds the statements. A token names its
parameters exactly, so leaving one out, even at its default, names a different
query and gives a different token. The other query types listed under
[Deterministic replay](https://docs.arche.fi/coverage#deterministic-replay) return tokens the same
way, and the verify route checks any of them.

## What a token covers

- **One result.** A token covers the statements and values of one page from the
  MCP as-of tools, or of one executed query. Paging with `cursor` gives each
  page its own token, so keep the token of each page whose figures you quote.
- **Values, not presentation.** `detail` and `include_usd` change how a
  statement is shown, not which statements or values it holds, so the token is
  the same with or without them.
- **Its boundary.** A token made with a timestamp `as_of` records the timestamp
  and re-runs at it; one made with a date re-runs at that date.
- **No figures in the check.** The verify page and route show the query, the
  filings and the verdict, so sharing a token shares no figures.

> **Note:** Replay tokens, the `replay_verify` tool and the verify page are available on
> every plan, including Free.

## Next steps

- [Restatement drift](https://docs.arche.fi/guides/restatement-drift): Show how restatements change historical results when data is not queried point-in-time.
- [Point-in-time research](https://docs.arche.fi/guides/point-in-time-research): Build research workflows that preserve historical knowability and reproducibility.
- [Rebuild a historical view](https://docs.arche.fi/guides/rebuild-historical-view): Reconstruct what a company statement looked like on a specific date.