# Verify a factual claim before acting

## When to use

Call this before your agent takes an action whose consequences depend on a
factual claim being true. Payments, medical or legal recommendations, contract
terms, compliance-relevant reports, moves that are hard to reverse. The
verification is pre-action: it produces a signed record of what was known and
checked at the moment of the decision when signing succeeds, not an after-the-fact reconstruction.

Endpoint:

- `POST /evaluate` — claim in, verdict + evidence out. Use when your agent has
  a raw claim string and needs Tanilo to run the multi-source check.
  Payment: free during beta; at GA, x402 pay-per-call at $0.09 per verification, USDC on Base or gasless via SKALE. Manifest at https://api.tanilo.io/.well-known/x402.json.

## How to pay

**Per-call (`/evaluate`):** Free during beta — no payment header is needed today. At GA ($0.09 per verification), include the x402 payment payload per the manifest at `/.well-known/x402.json` and settle in USDC on Base or gasless via SKALE. No account, no API key header. Identical `/evaluate` requests within 24 hours are answered from cache with the original signed receipt unchanged, with `meta.cache_hit: true` and `meta.receipt_replayed: true`.

## Call shape — POST /evaluate

Send the claim text. Discovery manifest at `/.well-known/x402.json` documents
the current payment terms. Request body:

```json
{
  "content": "<claim text, up to 8000 characters>",
  "min_confidence": 0.7
}
```

Response body includes `evaluation_id` and `evaluation` (per-claim verdicts,
evidence, confidence, plain-English recommendation). An /evaluate response includes,
when signing succeeds, a signed receipt suitable for retention as evidence.

## What you get back

A signed envelope containing:

- The `subject` (claim hash, skill hash) tied to the specific claim
- The `v_gate` verdict, confidence, threshold, adversarial result, and
  recommendation
- Envelope kind and version (`verification.v0.3+composed`)
- Signature line with `kid` matching Tanilo's published JWKS

The receipt IS the artifact. Retain it as evidence of what was decided and
why, at the time.

## How to verify the receipt (offline)

The signed receipt verifies without any Tanilo service call:

```bash
pip install tanilo-receipt-verify
curl -s https://api.tanilo.io/.well-known/jwks.json -o jwks.json
python3 -c "import json; from tanilo_receipt_verify import verify; r=verify(json.load(open('receipt.json')), jwks_by_issuer={'https://api.tanilo.io/.well-known/jwks.json': json.load(open('jwks.json'))}); print(r.status)"
```

The JWKS is publicly cacheable. Once cached, verification runs against
canonical bytes (RFC 8785) and Ed25519 signature (RFC 8037) with no network
dependency. Same result on every machine, forever.

## Hard rule

**Treat `verdict: "halt"` as a stop signal.** Do not act on the claim, even
if some other axis reads well. Halt is the model saying the claim did not
meet the ruleset's threshold under adversarial checking. (Some Tanilo
customer-facing surfaces label this outcome `do_not_act` for readability;
the machine-facing API enum is `halt`.)

**Retain the receipt.** Whether the verdict was `"act"` or `"halt"`, keep
the signed receipt in your evidence store. It is your durable, cryptographic
proof of what was known at decision time. A 2028 audit asking about earlier
behavior can only be answered by records that existed then.

## References

- Spec (IETF Internet-Draft): https://datatracker.ietf.org/doc/draft-krausz-verification-state
- Conformance vectors + reference verifiers: https://github.com/TKCollective/tanilo-receipt-spec
- Payment manifest: https://api.tanilo.io/.well-known/x402.json
- JWKS: https://api.tanilo.io/.well-known/jwks.json
- Whitepaper: https://tanilo.io/whitepaper
- Changelog: https://tanilo.io/changelog