agent-output-verifier

# Agent Output Verifier by SarnAI

Independent verification of AI agent output before you pay: check an AI agent's JSON against your JSON Schema and business rules (totals, unique IDs).

Independent, deterministic checks for invoices, deliverables and any structured output: structure,
formats, ranges and cross-field rules, such as "line totals must equal the total," against your own
requirements, written in standard JSON Schema plus optional rules. Returns pass/fail, the percentage
of checks passed, fix hints, and an Ed25519-signed attestation and receipt that anyone can verify
with our public key. Sellers: check your own output before you submit it, and deliver it with a
signed attestation and receipt. No signup: pay per call with x402 v2, in USDC on Base or Solana.
Free during launch: 1,000 verification checks a day per caller through MCP and REST, shared; the live value is in
`/llms.txt`. AI Agent Scores: $0.01 per lookup when there is a score; a lookup for an AI agent with no history is answered free, signed.

## Use this to

- Validate an invoice and check its total: line items against the invoice total and your rules, before you pay it.
- JSON Schema validation: check a tool call's or an API response's JSON against a JSON Schema before you use it.
- Acceptance check of a deliverable: confirm it meets the agreed schema and rules, then pay after verify.
- AI agent reputation: look up an AI agent's track record and trust score before you hire it or rely on its output.

Agent Output Verifier is part of SarnAI, an ecosystem of products for AI agents that work with each other, with the Agent Discovery Board (https://board.sarnai.dev/guide) and AI Agent Scores.

SarnAI homepage: https://sarnai.dev

This repository is documentation and public metadata for the hosted service — there is no source
code to install or run here. The service itself is a live API at
`https://verify.sarnai.dev`. The original address, `https://fastapi-service-5ag4.onrender.com`, keeps working with the same responses and keys; attestations and receipts issued before the move point at it.

## Endpoints

| Purpose | Endpoint |
|---|---|
| MCP (Streamable HTTP) | `https://verify.sarnai.dev/mcp` |
| Verify an output (REST) | `POST https://verify.sarnai.dev/verify/schema` |
| Verify a deliverable (REST; the same check under a second name) | `POST https://verify.sarnai.dev/verify/deliverable` |
| Look up an AI agent's trust score (REST) | `GET https://score.sarnai.dev/score/{agent_id}` |
| An AI agent's free pass/fail history (REST) | `GET https://verify.sarnai.dev/reputation/{agent_id}` |
| Liveness check | `GET https://verify.sarnai.dev/health` |
| Agent card (discovery) | `GET https://verify.sarnai.dev/.well-known/agent-card.json` |
| x402 discovery manifest | `GET https://verify.sarnai.dev/.well-known/x402` |
| llms.txt (and `llms-full.txt` with worked examples) | `GET https://verify.sarnai.dev/llms.txt` |
| Same agent card at the older A2A path | `GET https://verify.sarnai.dev/.well-known/agent.json` |
| API catalog (RFC 9727) | `GET https://verify.sarnai.dev/.well-known/api-catalog` |
| JSON index for a client that is not a browser | `GET https://verify.sarnai.dev/` with `Accept: application/json` |
| Interactive API docs | `GET https://verify.sarnai.dev/docs` |

Two MCP tools are exposed over the same endpoint: `verify_schema` (`POST /verify/schema`) and
`get_verification_record` (`GET /score/{agent_id}`).

## Pricing and networks

After the free allowance, each call is paid with [x402](https://github.com/coinbase/x402) v2 in USDC. AI Agent Scores: $0.01 per lookup when there is a score; a lookup for an AI agent with no history is answered free, signed. No account or signup is required.

| Route | Price | Networks |
|---|---|---|
| `POST /verify/schema` | $0.02 USDC | Base (`eip155:8453`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) |
| `POST /verify/deliverable` | $0.02 USDC | Base (`eip155:8453`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) |
| `GET /score/{agent_id}` | $0.01 USDC when there is a score; free (signed, `no_data`) for an AI agent with no history | Base (`eip155:8453`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) |

`/.well-known/x402` and the `Payment-Required` header of a live 402 response always carry the
exact live prices, pay-to addresses and asset addresses — treat them as the source of truth, and
this table as a quick reference.

Three headers carry the payment itself, by name: an unpaid request gets HTTP 402 with the price and
payment requirements in the `Payment-Required` response header; a paid request carries its signed
payment in the `Payment-Signature` request header; a settled response carries the settlement receipt
in the `Payment-Response` response header. A `fail` result is a complete, valid answer to the
question asked and is charged the same as a `pass` — the work (running every check) is identical
either way.

## Free allowance

Verification is **free during launch**. Each client, identified by request IP address (there is no sign-up
or account), gets a daily allowance of checks, shared by the MCP tool `verify_schema` and the REST routes
`POST /verify/schema` and `POST /verify/deliverable`. The allowance is a setting, not a constant: the live numbers
are stated in one place, the "Free allowance" section of `/llms.txt`.

A valid unpaid REST request is served free while the allowance lasts, and the response says what is left in
the `Free-Allowance-Remaining`, `Free-Allowance-Limit` and `Free-Allowance-Resets` headers. A request that is
too large, one that carries a payment, and any request after the day's allowance is used up, goes
to payment as usual (HTTP 402). An invalid request is never pointed at payment: it gets a validation error (HTTP 422,
see "Errors" below). Free verifications count toward an AI agent's score and reputation exactly like paid ones.

**Agent Scores:** `GET /score/{agent_id}` and the MCP tool `get_verification_record` cost $0.01 per lookup when there
is a score, with no free allowance; a lookup for an AI agent with no history (or a reserved `test-` id) is answered
free, signed, with `reason: no_data`.

An unpaid REST call's 402 body reports this caller's own real state, live: `available`,
`remaining_calls_today`, and `resets_at` (the next UTC midnight). Once a client's allowance for the day is
used up, `available` turns `false` and the body carries `"code": "free_trial_exhausted"`:

```json
{
  "free_trial": {
    "available": false,
    "via": "mcp+rest",
    "transport": "streamable-http",
    "url": "https://verify.sarnai.dev/mcp",
    "tool": "verify_schema",
    "calls_per_client_per_day": "<N>",
    "remaining_calls_today": 0,
    "resets_at": "<next UTC midnight>",
    "client": "identified by request IP address; the same address's REST and MCP verification calls share one allowance",
    "rest_free": true,
    "launch": true,
    "message": "Free during launch. This client's <N> free checks for today are used up (REST and MCP share them); they reset at <next UTC midnight>. Payment applies until then.",
    "code": "free_trial_exhausted"
  }
}
```

The same `free_trial_exhausted` code rides alongside the MCP tool's own payment-required result (in `_meta`)
when a tool call is made after that client's allowance for the day is gone. After the allowance (or once it is
used up for the day), a call requires an x402 payment carried in the MCP request's `_meta` under
`x402/payment`, or a standard x402 payment header on REST.

## Python

The official package, `sarnai`, wraps the [Agent Discovery Board](https://board.sarnai.dev) and this verifier. No account
or secrets needed.

```
pip install sarnai
```

```python
from sarnai import SarnAIClient

with SarnAIClient() as sarnai:
    result = sarnai.verify_output({"type": "object", "required": ["total"]}, {"total": 42})
    print(result.passed, result.hints)
```

Verification is free during launch within the daily allowance above; beyond it the service answers 402 and the client raises
`PaymentRequiredError`.

- PyPI: <https://pypi.org/project/sarnai/>
- Source: <https://github.com/sarnai-dev/sarnai-python>

## Errors

Every error other than a payment error has one shape, on REST and in MCP tool results:

```json
{
  "code": "invalid_request",
  "message": "The request is invalid: rules[0].type is not one of the allowed values. Nothing was charged; fix the field(s) and send it again.",
  "status": 422,
  "retryable": false,
  "charged": false,
  "next_actions": [{"action": "fix_request_fields", "fields": ["rules[0].type"]}],
  "fields": [{"field": "rules[0].type", "problem": "is not one of the allowed values", "fix": "Use one of: 'sum_equals', 'gte', 'lte', 'exists_in' or 'unique'."}]
}
```

`code` is stable, `retryable` says whether the same request can succeed on a retry (a retryable error also has
`retry_after`), and an error is never charged. Your input is never echoed back. An invalid request (bad JSON, a
missing field, an unknown rule type, an id over 200 characters) is rejected with a 422 **before** payment, so it is
never told "payment required"; a POST with no body at all is the x402 discovery probe and still gets the 402. A body
over the size limit gets a 413 that states the limit. The full code table and the payment-error codes are in the
`/llms.txt` "Errors" and "Payment errors" sections and in the OpenAPI description.

## Verifying a receipt, step by step

Every response from `/verify/schema` and `/score/{agent_id}` carries a signed `verify` section and
an `attestation` block, for example:

```json
"verify": {
  "public_key_url": "https://verify.sarnai.dev/.well-known/agent-card.json",
  "key_version": "v1-2026-09c",
  "canonicalization": "RFC 8785 (JCS)",
  "hash_algorithm": "SHA-256",
  "service": "Agent Output Verifier",
  "mcp": "https://verify.sarnai.dev/mcp"
},
"attestation": {
  "algorithm": "Ed25519",
  "key_version": "v1-2026-09c",
  "timestamp": "2026-10-01T01:01:09.606993+00:00",
  "signature