# x402-trust — machine-readable trust & reliability data for the x402 ecosystem

> https://x402.fuchss.app
> A live, continuously-updated registry of every publicly listed x402 endpoint
> (Base + Solana): what is reachable, spec-compliant, and — crucially — what
> actually SETTLES in real on-chain USDC, with deterministic trust scores,
> observation history, semantic alternatives and 30-day endpoint watches.
>
> Read this file first. It tells you what exists, what it costs, and how to
> pay. For exact request/response schemas see /openapi.json. For MCP see
> /mcp.json (and the hosted endpoint POST /mcp). For the human-readable
> failure taxonomy see /failure-modes.

## What this is — and what it is NOT

We are an independent OBSERVER. We probe listed endpoints many times a day
(polite unpaid requests), parse their 402 envelopes, and index real on-chain
USDC settlement (Base via CDP beacons, Solana via RPC token-account scans).
We deliberately do NOT verify "did the seller deliver what was advertised
after payment" — no scanner can, economically. Trust here means:
- the endpoint answers, answers fast, and its 402 envelope is spec-correct;
- it has REAL settlement history (un-fakeable: money moved on-chain);
- its advertised payTo/price/network have been stable, or the variance is
  explained (see /failure-modes).

A trust score is therefore evidence FOR proceeding, never a guarantee.

## Quickstart for an agent

1. Call /trust/stats first (free) to gauge the whole ecosystem.
2. Before paying ANY endpoint you do not already trust: get its report via
   POST /v1/x402-trust (paid, ~$0.005) or its endpoint page (/endpoint/:id,
   free). A "avoid" verdict or a severity:error flag means do not pay.
3. If an endpoint looks dead/poor, ask for its best better-scored equivalent
   via POST /v1/similar (paid, ~$0.005).
4. To stay current on a partner endpoint, open a 30-day watch
   (POST /v1/watch-endpoint-30d, paid, $0.20) and poll /v1/watch/:id/events.

## Free endpoints (GET, no payment)

- /trust/stats — aggregate snapshot: endpoints listed/active/delisted,
  reachability, envelope compliance, 30-day settlements + settled USDC volume,
  distinct receivers/payers.
- /trust/leaderboard — top-25 endpoints by trust score (latency from a single
  EU vantage point is only lightly weighted).
- /trust/report — human report page; /trust/report.json is its raw data.
- /v1/x402-trust-preview — FREE full paid-grade sample reports for three
  fixed picks (best / median / worst), so you see exactly what a paid report
  looks like before paying.
- /facilitators — facilitator leaderboard; /facilitators/:id detail
  (settlers, per-chain volume, 90d chart). JSON: /v1/facilitators(+/:id).
- /endpoint/:id — per-endpoint page (score, probe + settlement history,
  flags). A resource can be resolved to its id via /endpoint?resource=<url>.
- /badge/:id.svg, /card/:id.svg, /card/:id.png AND the resource-keyed forms
  /badge.svg?resource=<url>, /card.svg?resource=<url>, /card.png?resource=<url>
  — embeddable status shields (zero-integration proof for directories).
- /failure-modes — the human-readable taxonomy of what a 402 CANNOT rule out
  (uncollectable Solana ATAs, facilitator network mismatches, EIP-712 domain
  names, transport-version skew). Read it before trusting a score.
- /submit — let a human or agent submit an endpoint that is not yet listed
  (must return a live 402 to be accepted).
- /health — liveness probe (no trust data).

## Paid endpoints (POST, pay-per-call over x402)

- POST /v1/x402-trust — full trust report for one endpoint: score 0-100,
  grade A-F, recommendation proceed|caution|avoid|parameterize, advertised
  price, scoreRange, per-component breakdown, 30d settlement stats, and
  structured flags (any severity:error = avoid). ~$0.005/call.
- POST /v1/x402-history — raw observation time-series 1-90d: list/delist
  events, advertised price and payTo changes, per-probe uptime/latency/quote.
  $0.02/call.
- POST /v1/similar — the endpoints whose advertised purpose most closely
  matches the given URL AND currently out-score it (semantic + trust
  re-routing). ~$0.005/call.
- POST /v1/x402-trust-bulk-{10|50|100|200|500} — score many endpoints in one
  paid call (smallest fitting tier is the cheapest; dedupe happens server-side):
/v1/x402-trust-bulk-10 (≤10 endpoints, $0.045/call)
/v1/x402-trust-bulk-50 (≤50 endpoints, $0.2/call)
/v1/x402-trust-bulk-100 (≤100 endpoints, $0.325/call)
/v1/x402-trust-bulk-200 (≤200 endpoints, $0.4/call)
/v1/x402-trust-bulk-500 (≤500 endpoints, $0.5/call)
  Cache rows older than ~15min are recomputed on-demand (≤50 endpoints/8s per
  request; recompute_limit_hit tells you when you hit the cap). Resources out
  of our observation set return found:false — you still pay for the batch.
- POST /v1/watch-endpoint-30d — 30-day monitor of one endpoint: alerts on
  payTo/price/asset/network changes, 402-spec regressions, delisting,
  liveness down/recovered + flapping (coalesced). Optional push delivery to
  signed HTTPS webhooks and/or Slack/Discord (max 5 each; URLs are
  connection-tested BEFORE payment, unreachable = no charge). $0.2/call.
- POST /v1/watch/:id/renew — extend a watch +30d. $0.2/call.

## Watch management (free, bearer-authed with the watch secret)

- GET /v1/watch/:id/events — append-only event log (endpoint events +
  lifecycle events); page by the returned cursors (they are GLOBAL sequences,
  do not assume they start at 1). Cancelled watches stay readable until the
  original expiry.
- PATCH /v1/watch/:id — edit delivery URLs (full-replace per channel),
  liveness sensitivity (1-10), or subscribed events. New URLs are
  connection-tested before the change is persisted.
- DELETE /v1/watch/:id — soft-cancel (no new events; log stays readable).

## MCP

Two transports share the SAME 12 tools (single-sourced in tool-spec — no drift):
- Local: npx -y x402-trust-mcp (stdio; auto-pays over x402 if X402_PRIVATE_KEY
  is set; without it, returns the quote so you can pay with your own wallet).
- Hosted, zero-install: POST /mcp (stateless Streamable HTTP). Free tools work
  as-is. Paid tools return the x402 quote IN-BAND ({ paid:false, status:402,
  quote, hint }) — retry the same tools/call with a PAYMENT-SIGNATURE header
  to settle; the PAYMENT-RESPONSE header + decoded 'payment' field carry the
  settlement receipt.

Tools (free): x402_ecosystem_stats, x402_trust_leaderboard, x402_trust_preview,
x402_watch_events, x402_watch_edit, x402_watch_cancel.
Tools (paid): x402_trust_score, x402_endpoint_history, x402_find_alternatives,
x402_trust_bulk, x402_watch_create, x402_watch_renew.

## Discovery & metadata files

- /openapi.json — canonical machine schema (per x402scan strict-mode rules:
  every paid path declares x-payment-info + a 402 response). The live 402
  remains authoritative for pricing.
- /.well-known/x402 — the x402 scan/crawl contract (which paths are paywalled).
- /mcp.json — MCP server manifests (stdio + hosted transport, full tool list).
- /sitemap.xml, /robots.txt — human-crawl surfaces.

## Making an x402 payment (for agents)

1. POST the paid route with NO payment header. The server answers HTTP 402
   with a JSON PaymentRequired body: { resource, accepts: [...] } and a
   base64 PAYMENT-REQUIRED response header encoding the same JSON.
2. Pick accepts[0]. Sign an EIP-3009 USDC transfer: asset = the quoted USDC
   contract on the quoted network, amount = accept.amount (Exact scheme),
   payTo = the quoted receiving address. NOTE the domain: mainnet USDC's
   on-chain name is "USD Coin" (Base Sepolia test token: "USDC") — an EIP-712
   domain mismatch fails recovery for EVERY payment. For templated per-item
   endpoints, always pay the payTo in the LIVE 402 quote, never a cached one.
3. Retry the SAME request with the Authorization-free header
   PAYMENT-SIGNATURE (base64 of the signed PaymentPayload; legacy X-PAYMENT
   also accepted). The server verifies, settles on-chain via the facilitator,
   and answers. Replay protection: each nonce settles once — do not reuse it.
4. Settlement receipt: PAYMENT-RESPONSE response header (base64 settlement
   response), also echoed legacy X-PAYMENT-RESPONSE.

On 402 with the payment header present but settlement failing, the server
refuses with a 402 and an error reason — the money was NOT taken.

## Notes & limitations

- probes originate from one EU vantage point; latency includes network
  distance. See stats.latencyVantage on per-endpoint reports.
- flags are only produced from double-confirmed observations (≥6h apart);
  an RPC/fetch outage can never manufacture a false flag.
- Score freshness: free /endpoint/:id pages serve a precomputed cache
  (OBSERVER_SCORE_STALE_HOURS, default 24h); paid reports recompute on demand.
- new observability is the moat: every day of observation is history nobody
  can backfill.