{
  "markdown": "# TrustBench\n\nVerify that x402 payments settled on-chain and get cryptographically signed\nproof. POST `/verify` with a receipt ID or raw envelope to confirm Ed25519\nsignature validity + on-chain settlement on Base, no trust required.\n\nAlso routes paid x402 calls with server-side spend caps, idempotency, and a\nfail-safe paywall (agent isn't charged when the upstream merchant is\nnon-conformant). Non-custodial: TrustBench never holds funds. Every paid\ncall emits an Ed25519-signed receipt verifiable offline against a published\npublic key.\n\nCross-network: routes Base today, registers Solana endpoints (Heurist\nMesh, Pay.sh skills), Solana settlement next.\n\n## What's live today\n- Public registry of x402 endpoints across Base (Coinbase Agentic Market,\n  ~650 services) and Solana (Heurist Mesh, ~150 endpoints) — Solana inventory\n  is in the database today and surfaces on `/rankings` once the network\n  filter is dropped (P4-3a, see `phase4-p4-3-timing.md`)\n- Nightly liveness probe (HEAD requests from a single cloud host, 3 samples per\n  provider, statuses 200/201/204/401/402/403/404/405/429 treated as alive)\n- Score derivation: 15 + 45·successRate + 35·latencyHealth + 3·consistency,\n  clamped to [40, 98], via linear-interpolation percentiles\n- Ed25519-signed scorecards, public key at /.well-known/trustbench-pubkey\n- Routing and settlement on Base + USDC (Phase 3); Solana is roadmap (P4-3)\n- Methodology disclosure at /methodology\n\n## Phase 3 + 4 (live since 2026-05-04 / 2026-05-06)\n- Authenticated POST /route endpoint with API-key auth (argon2id), idempotency\n  keys, hard spend caps, and Ed25519-signed receipts\n- /route/settle endpoint forwarding agent-signed EIP-3009 authorizations\n- Queryable audit at /receipts/:id\n- Strict reservation-based spend caps (P4-7)\n- Discovery surfaces: /skill.md, /llms.txt, /.well-known/trustbench.json\n- First paid x402 receipt against a real provider, settled on Base 2026-05-06:\n  [rcpt_01KQY7C44GAPSXZPFQYRZ1D10C](https://trustbench.io/receipts/rcpt_01KQY7C44GAPSXZPFQYRZ1D10C)\n  — verifies SIGNATURE VALID + ON-CHAIN VERIFIED with no overrides.\n\n## In flight (Phase 4b)\n- x402-paywalled API endpoints (per-call USDC pricing surface)\n- Public receipt explorer at /explorer\n- Formal partner integrations\n- Solana routing (registry pre-built, network filter to drop)\n- npm verifier package `@trustbench/verify-receipt`\n\n## Claude Desktop / MCP\n\nTrustBench ships a native MCP server so agents in Claude Desktop, Claude Cowork, ChatGPT, or Cherry Studio can look up providers, fetch receipts, and verify signatures without any HTTP-fetch workaround.\n\nAdd to `claude_desktop_config.json` (or your host's equivalent MCP settings file):\n\n```json\n{\n  \"mcpServers\": {\n    \"trustbench\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@trustbench/mcp\"]\n    }\n  }\n}\n```\n\nRestart the host app after saving. Three tools become available:\n\n- **get_rankings** — scored providers by capability. No API key.\n- **get_receipt** — fetch any receipt by ID (`rcpt_…` / `rrcpt_…`). No API key.\n- **verify_receipt** — confirm Ed25519 signature + on-chain status. No API key.\n\nRouting tools (`route_quote`, `route_settle`) require a `tb_live_…` API key and ship in the next MCP release. Request access by DM'ing @TrustBench on X.\n\n## What we don't do\n- We never hold agent funds, never submit transactions on-chain, never act as\n  a payment facilitator. Agents sign EIP-3009 transferWithAuthorization\n  payloads; providers submit them on-chain and pay gas. TrustBench observes\n  the resulting tx_hash and records it in a signed receipt.\n\n## Pricing model\n- x402-native paywalled API endpoints, per-call USDC settlement on Base\n- No subscriptions, no contracts, no per-seat or per-month charge\n- v0.1.0 ships `POST /route` at $0.005 per call (score-provider tier); full\n  tier table at [/pricing](https://trustbench.io/pricing) (HTML for humans,\n  JSON for agents via `Accept: application/json` or `?format=json`)\n- Settlement through the Coinbase CDP facilitator at\n  `api.cdp.coinbase.com/platform/v2/x402` (the public `x402.org/facilitator`\n  is testnet-only). TrustBench never holds funds; the agent's wallet\n  signs and the facilitator submits on-chain.\n- Existing partner agreements override the published table for that partner.\n  Reach out for partner-volume credit before integration.\n- Registry listing is currently free and automatic (crawled from public x402\n  catalogs). A refundable provider verification bond is a design intent, not a\n  shipped mechanism. Never pay-to-rank — routing decisions are measurement-based.\n\n## Stack\n\nTypeScript + Hono (API) + Supabase (Postgres + RLS) + ioredis (Upstash Redis cache) + tsx runtime. Deployed on Railway. Nightly probe pipeline + autonomous X posting via GitHub Actions.\n\n## Quick start\n\n```bash\nnpm install\ncp .env.example .env   # fill in Supabase + Upstash credentials\nnpm run pipeline       # probe + score (writes to Supabase)\nnpm run dev            # run the API locally\n```\n\n## Endpoints\n\nPublic (no auth):\n\n- `GET /health` — liveness check for the API itself\n- `GET /rankings?capability=search` — ranked providers for a capability (`search`, `inference`, `data`)\n- `GET /rankings/paid?capability=search` — same as `/rankings` but with each provider's signed scorecard\n- `GET /route?capability=search` — current best provider + fallback (legacy read-only — the Phase 3 routing surface is `POST /route`)\n- `GET /mcp/tools` — MCP tool descriptor catalog (JSON schema). For native tool use, see the Claude Desktop / MCP section above.\n- `GET /analytics` — plain HTML dashboard\n- `GET /methodology` — full description of what the probe does and does not measure\n- `GET /skill.md` — agent skill file in the [agentic.market/skill.md](https://agentic.market/skill.md) format. Paste into Claude Code, Codex, Gemini CLI, Hermes, Cursor, Claude Desktop, Cherry Studio, or ChatGPT to teach the agent the TrustBench quote/settle flow as an additive policy + receipt layer on top of Coinbase Agentic Wallet.\n- `GET /llms.txt` — LLM-grounded research summary in [llmstxt.org](https://llmstxt.org) format\n- `GET /pricing` — public, honest pricing for paid endpoints. Content-negotiated: HTML for humans, JSON for agents via `Accept: application/json` or `?format=json`. Returns a 7-row tier table with `live` / `planned (v0.2.0)` / `planned (v0.3.0)` status badges per endpoint.\n- `GET /.well-known/trustbench.json` — machine-readable manifest of TrustBench's public surfaces, capabilities, signing scheme, and discovery references. Includes an `endpoints` array with paid annotations matching `/pricing`.\n- `GET /.well-known/trustbench-pubkey` — Ed25519 public key (PEM) for verifying scorecards and receipts\n\nAuthenticated (Phase 3, in build):\n\n- `POST /route` — quote step. `Authorization: Bearer tb_…`, `Idempotency-Key: <16–128 chars>`, body `{capability, max_price (atomic-unit string), payer_address}`. Returns `{route_id, payment_required, expires_at, fallback_provider}`. Quote validity is 5 minutes; settling after that returns 410.\n- `POST /route/settle` — settle step. Body `{route_id, signature}` where `signature` is the agent's EIP-3009 `transferWithAuthorization` signature. Returns `{response, receipt}` plus `X-Receipt-Id` header. Idempotent on `(route_id, signature)`: replays return `x-idempotent-replay: true` with the cached receipt and never re-call the merchant.\n- `GET /receipts/:id` — public, no-auth, immutable. Returns the exact signed envelope (`{receipt, signature}`) that was issued. `Cache-Control: public, max-age=86400, immutable`.\n\n## Verifying a receipt\n\nReceipts are Ed25519-signed over the JCS-canonicalized form of `envelope.receipt`. The `signature` block (including `public_key_url`) is detached and not part of the signed bytes, so it can be overridden at verification time without invalidating the chain of trust.\n\nReference verifier: `scripts/verify-receipt.js`.\n\n```bash\n# By id, against a deployed instance\nnpm run verify-receipt -- rcpt_01HV3K8M5C9X2ZBFYR4QWP8ND1 https://your.trustbench.deployment\n\n# From a saved JSON file\nnode scripts/verify-receipt.js ./receipt.json\n\n# Override pubkey URL when the receipt's public_key_url isn't reachable\n# from your network (useful for local-dev verification of locally-issued receipts)\nnode scripts/verify-receipt.js ./receipt.json --pubkey-url http://localhost:3000/.well-known/trustbench-pubkey\n```\n\n## Failure semantics\n\n**TrustBench down ≠ payments down.** This is an architectural property, not a feature flag.\n\nThe agent's payment authorization is an EIP-3009 signature it produces with its own key. The merchant accepts that signature and submits the on-chain transaction. TrustBench sits between them as a router and audit layer — it constructs the quote and records the result, but it never holds funds, never signs the payment, and never broadcasts the transaction.\n\nIf the TrustBench API is unavailable, an agent can still:\n- Transact directly with any x402 provider it already knows about, using the same EIP-3009 signing flow.\n- Submit and verify receipts after the fact (the verifier is a standalone script and the public key is served from `/.well-known/trustbench-pubkey`).\n\nWhat it temporarily loses while the API is down:\n- Routing decision (which provider scored best at this moment).\n- Server-enforced spend caps (the agent must enforce caps locally if it cares).\n- Signed receipts for any calls made during the outage.\n\nExisting receipts remain verifiable — the public key and JCS canonicalization rules are stable, and the receipt's `audit_url` is a hint, not a dependency.\n\n## Paywall (Phase 4 v0.1.0)\n\n`POST /route` is paywalled when `TRUSTBENCH_PAYWALL_ENABLED=true` on the deployment. The flow is x402-native end-to-end:\n\n1. Agent calls `POST /route` with no `X-PAYMENT` header.\n2. TrustBench responds `402 Payment Required` with x402 payment requirements pointing at the TrustBench revenue wallet on Base. Price: $0.005 USDC.\n3. Agent signs an EIP-3009 `transferWithAuthorization` for the routing fee and retries the call with an `X-PAYMENT` header carrying the signed envelope (use any x402 client; the modular `@x402/core` + `@x402/evm` SDKs are the reference).\n4. TrustBench verifies the payment with the Coinbase CDP facilitator at `api.cdp.coinbase.com/platform/v2/x402`, settles it on-chain, selects the best provider via the live registry, and returns 200 with an Ed25519-signed routing receipt plus payment requirements for the agent's NEXT call (to the upstream provider).\n5. The agent then pays the provider directly via a second x402 transaction. TrustBench is out of the loop after step 4.\n\nTwo payments per call (TrustBench fee + provider fee), both non-custodial. Receipts cover the routing decision; the provider transaction is a separate x402 envelope the agent owns end-to-end.\n\n**Discovery.** Paid endpoints carry `paid: true` annotations alongside the free ones in [`/skill.md`](https://trustbench.io/skill.md) and [`/.well-known/trustbench.json`](https://trustbench.io/.well-known/trustbench.json). v0.2.0+ endpoints are listed with `available_in` tags so agent builders see the roadmap shape.\n\n**Verifying a routing receipt.** Same Ed25519 + JCS canonicalization as Phase 3 settlement receipts, with `kind: \"paid_response.route\"`. Use the npm verifier:\n\n```bash\nnpm install @trustbench/verify-receipt\ntrustbench-verify-receipt ./routing-receipt.json\ntrustbench-verify-receipt ./routing-receipt.json --check-chain   # also re-verify the on-chain tx\n```\n\n**Server-side controls (v0.1.1).** Two safeguards run on every paywalled call:\n\n- **Per-paying-wallet hourly rate limit.** Default 60 paid calls per hour per `agent_address`. Tunable via `TRUSTBENCH_PAYWALL_HOURLY_LIMIT` (set to 0 to disable). Returns 429 with `Retry-After: 60` when exceeded.\n- **Idempotency-key replay with `replayed_at` marker.** `Idempotency-Key` header (16-128 chars) honored on every paywalled call. Same key + same body within 24 hours returns the original signed receipt with a top-level `replayed_at` field added outside the signed bytes — original signature stays valid, downstream consumers can distinguish fresh from replayed. Same key + different body returns 409.\n\n**Failure modes.** Documented in detail in the Critic-pass header at the top of [`src/paywall-handler.ts`](./src/paywall-handler.ts). Live facilitator is the Coinbase CDP facilitator at `api.cdp.coinbase.com/platform/v2/x402`; the original \"Foundation facilitator first, swap to CDP later\" plan was disproven on 2026-05-11 when settle-tests confirmed the Foundation facilitator is testnet-only (see `lessons.md` 2026-05-11 entry). Current hidden assumption: CDP facilitator stays stable and within plan limits. Kill criterion: if CDP returns 5xx or auth-errors >5% of calls in the first 4 weeks, fall back to PayAI-mediated settlement.\n\n## What Phase 3 deliberately does not do\n\nThese are limits in the current implementation, called out so consumers don't infer behavior the system doesn't actually deliver:\n\n- **Single-merchant routing.** `POST /route` serves one capability against one selected provider per call. Multi-merchant fan-out (one intent → multiple paid APIs → one envelope) is Phase 4.\n- **Receipt content is not yet on-chain anchored.** Receipts are Ed25519-signed by TrustBench. They are not Merkle-batched into a public blockchain. On-chain anchoring is a Phase 5 consideration if real demand surfaces.\n- **Single-chain settlement today.** Routing + settlement is Base + USDC. Solana inventory is registered but not yet routable (P4-3 next).\n\n## Methodology disclosure\n\nThe probe is a HEAD-request liveness check from a single host, three samples per provider per night. Status codes 200, 201, 204, 401, 402, 403, 404, 405, and 429 are treated as alive (the provider is responding; only the auth/payment gate is closed).\n\nThis is not a benchmark in the rigorous sense. Latency is wall-clock from a single network vantage. Score `latencyHealth` is derived from linear-interpolation percentiles across the cohort — useful as a relative signal, not as a service-level claim. Full description at `/methodology`.\n\n## License\n\nMIT.\n\n\n",
  "bytes": 14110,
  "sha": "d288ac124d68447bbaa5d5b115542567a183423941c4f6598d0f3f33ee23bd5c",
  "repo_slug": "lithvall/trustbench",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lithvall_trustbench_631d46ed/readme"
}