# 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, not an after-the-fact reconstruction.

Two endpoints, two use cases:

- `POST /evaluate` — claim in, verdict + evidence out. Use when your agent has
  a raw claim string and needs AgentOracle to run the multi-source check.
  Payment: x402 pay-per-call, $0.09 per verification, USDC on Base or gasless
  via SKALE. Manifest at https://agentoracle.co/.well-known/x402.json.
- `POST /v1/compose` — decision in, signed receipt out. Use when your pipeline
  already produces a `v_gate` verdict and you need the JWS-signed envelope so
  AgentTrust / Presidio / downstream aggregators can co-sign. Payment: API key
  only (`Authorization: Bearer <key>`), $99/month self-serve at
  https://agentoracle.co/register, 100 requests/hour/key.

## How to pay

**Per-call (`/evaluate`):** Include the x402 payment payload per the manifest
at `/.well-known/x402.json`. Settle in USDC on Base or gasless via SKALE. No
account, no API key header. Cached results within 24h at 50% off.

**Subscription (`/v1/compose`):** Buy the $99/month tier at
https://agentoracle.co/register (Stripe). Key issued at checkout; send as
`Authorization: Bearer <key>`. Rate limit: 100 requests/hour/key. Enterprise
volume via joe@agentoracle.co.

## Call shape — POST /v1/compose

The signing endpoint accepts a pre-computed `v_gate` result plus subject
hashes and returns a JWS-signed one-leg composed envelope. From the live
gateway OpenAPI spec:

```json
{
  "subject": {
    "claim_hash": "sha256-<64-hex>",
    "skill_hash": "sha256-<64-hex>"
  },
  "v_gate": {
    "verdict": "act",
    "v_confidence": 0.91,
    "v_gate_threshold": 0.7,
    "v_adversarial_result": "resilient",
    "v_recommendation": "confident_supported"
  }
}
```

- `subject.claim_hash` — sha256 of the exact claim string being asserted
- `subject.skill_hash` — sha256 of the ruleset / skill used to evaluate it
- `v_gate.verdict` — one of `"act"` or `"halt"`
- `v_gate.v_confidence` — decimal, 0–1
- `v_gate.v_gate_threshold` — decision threshold used
- `v_gate.v_adversarial_result` — `"resilient"` or `"vulnerable"`
- `v_gate.v_recommendation` — `"confident_supported"` or `"refuted"`

Optional field:
- `mycelium_trail_id` — string identifier if the caller is tracking a trail.
  Must be absent or a string. Never null.

Response: JWS General Serialization with the AgentOracle signature, `typ` =
`application/vnd.verification.v0.3+composed+jws`, per
draft-krausz-verification-state-01.

## 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). The paid-path response
includes 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 AgentOracle'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 AgentOracle service call:

```bash
pip install agentoracle-receipt-verify
agentoracle-verify receipt.json --jwks https://agentoracle.co/.well-known/jwks.json
```

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 AgentOracle
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/agentoracle-receipt-spec
- Payment manifest: https://agentoracle.co/.well-known/x402.json
- JWKS: https://agentoracle.co/.well-known/jwks.json
- Whitepaper: https://agentoracle.co/whitepaper
- Changelog: https://agentoracle.co/changelog