# Settled verifier method

Version 1.1, 2026-10-31 (1.0 earlier the same day: the terms rule read "since the last probe"; it now reads the last day's price moves). This document describes how Settled (settled.tools) arrives at the `verifier` object it
attaches to every check answer (`/v1/free/check`, `/v1/check`, `/v1/preflight`, and the `settled_check` and
`settled_preflight` MCP tools). The object follows the verifier response schema drafted by the x402 Foundation's
Domain Discovery working group (x402-foundation/wg-domain-discovery, `proposal/verifier-schema.md`, with the
`purchase_by`, `method_digest` and `attestation.relationship` fields of its pull request #13). The sha256 of this
file as served is the `method_digest` on each verdict, so a verdict names the exact method it was produced under.

## What Settled does

Settled keeps an index of x402 endpoints found in public catalogues and submitted by sellers and buyers. Each
endpoint is probed on a schedule: an unpaid request on the declared verb (and the other verb when the declared one
does not answer), reading the 402 challenge from the `PAYMENT-REQUIRED` header or the body. A scout wallet pays a
sample of live endpoints with real USDC on Base and records whether usable content came back, what it was charged
on-chain and whether the response matched the listing. Every answer is signed (EIP-191 over keccak256 of the
canonical JSON, key at `/v1/signer`).

## Verdict and reason

Settled's state for an endpoint maps onto the draft's closed reason set as follows.

| Settled finds | `verdict` | `reason` | `detail` |
| --- | --- | --- | --- |
| a valid quote, and the scout bought the endpoint within 30 days and got content back, and the price has not moved in the last day | `true` | `settled-under-terms` | |
| a valid quote on the latest probe (not bought, or bought but the price moved in the last day: `price_changed` for one or two moves, `price_dynamic` for three or more, both carried with the band on the check answer) | `true` | `probe-ok` | |
| the quote's EIP-712 domain (`extra.name` / `extra.version`) is not the asset contract's; checked for USDC on the networks Settled knows | `false` | `wrong-domain` | the field, expected, got |
| an `exact` quote on an EVM network with no `extra` at all | `false` | `no-domain` | `extra`, absent |
| the discovery record Settled imported names a different payTo, network, asset or amount than the live quote | `false` | `terms-mismatch` | the field, listed, live |
| a valid 402 whose accept Settled cannot price (an asset or network it does not know) | `inconclusive` | `mapping-unknown` | `asset` |
| a 402 whose quote does not parse | `inconclusive` | `digest-unbound` | `accepts` |
| an answer with no payment challenge: 2xx without a paywall, 401/403, 404, 429, 5xx | `false` when the state is established (`free`, `auth_gated`, `not_found`, `dead`), else `inconclusive` | `no-challenge` | `http_status` |
| no HTTP answer on the latest probe | `inconclusive` | `probe-unreachable` | |
| the endpoint is on Settled's own domain | `inconclusive` | `self-referential` | |

The first matching row from the top decides. `terms-mismatch` compares the live quote with the discovery record
Settled imported (the x402 Bazaar or another catalogue) for the accept whose network and asset match the live one,
else the record's first accept; endpoints that reached Settled by submission or by a check have no record and are
never `terms-mismatch`. `mapping-stale` is not used.

## Evidence

`evidence` is the strongest level Settled reached for the endpoint, never lowered by a later weaker check:

- `purchase`: the scout paid the endpoint and got content back within the last 30 days (`purchase_by` is always
  `verifier`; the transaction hash and the comparison with the listing are in the check answer's
  `delivery_receipt`). Settled does not relay other parties' purchases: paying agents' reports (`POST /v1/report`)
  appear separately in the answer and never raise `evidence`.
- `probe`: a valid 402 quote was read on some probe.
- `none`: neither.

`observed_at` is when that evidence was obtained (the purchase, else the last valid quote, else the last probe).
`checked_at` is the last probe of any outcome. `untested` is the complement of `evidence` in `terms`, `probe`,
`purchase`; Settled always probes, so `terms` is never its evidence level.

## Digest, mapping and accepts_index

`digest` is the live quote's stable terms: `scheme`, `network` (CAIP-2), `asset`, `payTo`, `amount` in the asset's
smallest unit as a string, `extra` as the seller sent it (`{}` when absent). Settled prices the cheapest accept
it can price, else the first; `accepts_index` is that accept's position in the challenge. For endpoints last
probed before this method took effect, `amount` is reconstructed from the stored USD price when the asset is a
USD stablecoin Settled knows, and `extra` is `{}`. `mapping` names the entry Settled's asset table used
(`scheme/network/asset`) and the contract; `read_at` is the probe time.

## Attestation

`attestation.key_url` is `/v1/signer` on settled.tools: the current signing address, every earlier one with its
dates and status, and the rotation policy. `attestation.record_url` serves the record for this exact verdict: the
`verifier` object together with the resource URL, signed under settled.tools the same way as every Settled answer.
Records are kept for at least 90 days past `valid_until`. One endpoint state yields one record, so the same URL is
returned to everyone who asks while the state holds.

To verify a record offline: take the record's JSON without its top-level `attestation`, serialise it as canonical
JSON (keys sorted, no whitespace), hash with keccak256, and recover the EIP-191 signer of `attestation.signature`
over that hash; it must be the address `/v1/signer` lists as current (or a retired key within its dates).
`POST /v1/verify` with the record as the body does the same on Settled's side.

`attestation.subject.resource_domain` is the endpoint host reduced to its registrable domain with a short
public-suffix list (the common two-label country suffixes and the hosting platforms that give each customer a
subdomain); `verifier_domain` is settled.tools. A client with a full public-suffix list may reduce a rare host
differently.

`attestation.valid_until` is six hours after the endpoint's next scheduled probe (and at least six hours after
the last one), or seven days after the last probe when no next probe is scheduled: after that, ask again.

## Relationship disclosure

`attestation.relationship` is a disclosure, not evidence of independence:

- `paid-by-client` when the caller paid for the answer: a paid route (`/v1/check`, `/v1/preflight`), a pass, or
  `force`, which needs a pass.
- `paid-by-resource` when the seller behind the endpoint pays Settled: an active paid Seller Watch for the claimed
  wallet, an active Proven plan for the wallet (claimed or not), or the purchase behind the evidence was one the
  seller paid for: a re-test the seller bought, or a purchase made under the seller's Proven plan.
- `none` otherwise. Settled routes no payments, so `earns-from-routing` never applies, and it always discloses, so
  `undisclosed` never appears.

Both paid values can appear together. Claims, Seller Watch and re-tests never change a verdict, a score or the
order of any list; the free check and the paid check give the same verdict for the same endpoint state.

## Where to find it

- `GET /v1/free/check?url=<endpoint>` (free, rate-limited) and `GET /v1/check?url=<endpoint>` (paid): the
  `verifier` field of the answer.
- `GET /.well-known/x402-verifier`: this method's URL and digest, the key URL, the schema and the record pattern.
- `GET /v1/verifier/records/<id>`: a signed record.
