{
  "markdown": "[![x402-trust-mcp MCP server](https://glama.ai/mcp/servers/JonasFuchss/x402-trust-mcp/badges/card.svg)](https://glama.ai/mcp/servers/JonasFuchss/x402-trust-mcp)\n\n# x402-trust-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server that lets your agent check the\n**trust & reliability of x402 endpoints before paying them**.\n\nBacked by [x402.fuchss.app](https://x402.fuchss.app), which monitors the entire\nx402 ecosystem on Base 24/7: uptime probes, 402-envelope spec compliance,\nadvertised-price history, and **real on-chain USDC settlement volume** per\nendpoint.\n\n## Why\n\nAgents increasingly pay x402 endpoints autonomously. But ~⅔ of listed x402\nendpoints are unreachable and ~⅓ of the reachable ones serve non-compliant\npayment envelopes. Before your agent sends USDC to an unknown endpoint, ask:\n*is it alive, compliant, and does anyone actually pay it?*\n\n## Tools\n\n| Tool | Cost | Description |\n|---|---|---|\n| `x402_ecosystem_stats` | free | Aggregate state of the x402 ecosystem (listings, reachability, compliance, 30d settlement volume). |\n| `x402_trust_leaderboard` | free | Top-25 most trustworthy x402 endpoints. |\n| `x402_trust_preview` | free | Showcase of what `x402_trust_score` returns — you don't choose the endpoint. Returns the **complete** paid-grade report (exact score, full breakdown, advertised price, on-chain settlement figures, all flags) for **three** endpoints: the best-scored, the median, and the worst-scored. See the full data shape across the quality range before you pay. To score *your own* endpoint, use `x402_trust_score` (paid). Takes no arguments. |\n| `x402_trust_score` | paid | Trust score (0-100, grade A-F) for a specific endpoint, plus the provider-advertised `serviceName` and `description` (unverified provider claims, shown next to our independent metrics), a machine-readable pay/don't-pay verdict, the advertised price, a confidence band, and structured flags — everything to decide in one call. |\n| `x402_endpoint_history` | paid | Observation time-series for a specific endpoint (listings, price changes, probes). |\n| `x402_find_alternatives` | paid | Find semantically-similar endpoints that OUT-SCORE a given one. Use this to route away from a mediocre/dead/expensive endpoint toward a more reliable, better-settled one serving the same function. Each alternative carries score, grade, similarity (0-1), price, and a free per-endpoint page. |\n| `x402_semantic_search` | paid | Free-text semantic search across the whole monitored catalog. Describe the capability you need in plain words, get the up to 25 closest endpoints ranked deterministically: cosine similarity bucketed to whole percentage points first (80.3% and 80.5% tie), then trust score, then described-before-undescribed, then id; matches below a 0.5 similarity floor are dropped. Missing description: no fixed malus, only the tiebreak loss at equal bucket + score (fallback embedding via service name + URL path tokens usually lowers similarity). Each match has resource, score, grade, similarity, description, and a free per-endpoint page. Discovery only: no verdicts or flag details (that is `x402_trust_score`). |\n| `x402_trust_bulk` | paid | Score up to 500 endpoints in a single paid call from cached full-density snapshots. Picks the cheapest tier that fits your list (10/50/100/200/500). Returns score, grade, recommendation, confidence, and `probed_at` per endpoint. |\n| `x402_watch_create` | paid | Start monitoring one endpoint for 30 days. Alerts on payTo change (takeover signal), price/asset/network change, spec regression, delisting, and liveness. Supports up to 5 webhook + 5 Slack/Discord URLs per watch, all connection-tested before payment. Returns a one-time bearer secret + poll/edit/cancel URLs + `next_steps`. |\n| `x402_watch_events` | free | Poll the append-only event log of an active watch using the watch id and one-time secret. Use the `since` (endpoint events) and `watch_since` (lifecycle events) cursors to page forward; nothing between polls is lost. |\n| `x402_watch_edit` | free | Change a watch's webhook/Slack URLs, liveness sensitivity, or subscribed events. Bearer-authed with the secret from `x402_watch_create`. |\n| `x402_watch_cancel` | free | Soft-cancel a watch: drops the endpoint back to normal probe cadence immediately, but the event log stays readable via `x402_watch_events` until the original `expires_at`. |\n| `x402_watch_renew` | paid | Extend an active watch by another 30 days. The secret stays the same. |\n\nPaid tools cost from **$0.001** (a semantic search) or **$0.005** (a single\ntrust / similar lookup) up to **~$0.50** (500-endpoint bulk batch) or **~$0.20**\nfor a 30-day watch, charged over x402 (USDC on Base). If you set\n`X402_PRIVATE_KEY`, the server **auto-pays** within your `X402_MAX_USD` limit;\notherwise it returns the price quote for your host to pay.\n\n### Bulk scoring (`x402_trust_bulk`)\n\nThe bulk tool is the scale axis: score up to 500 endpoints in one call from the\nsame data that powers the leaderboard. It auto-selects the cheapest tier that\nfits your request:\n\n| Tier | Max endpoints | Approx. price |\n|---|---|---|\n| 10 | 10 | ~$0.045 |\n| 50 | 50 | ~$0.20 |\n| 100 | 100 | ~$0.325 |\n| 200 | 200 | ~$0.40 |\n| 500 | 500 | ~$0.50 |\n\nCached rows older than ~15 minutes are recomputed on-demand from the latest\nstored probes and settlements (no live network re-probe), so bulk scores usually\nreflect reality within minutes. Per-request recompute limits apply: at most **50\nrows / 8 seconds** are recomputed; the response tells you via\n`recompute_limit_hit` + `recompute_limit`. Each result carries `score`, `grade`,\n`recommendation`, `confidence`, `probed_at`, `computed_at`, and `recomputed` so\nyou can see exactly which rows were freshly computed vs served from cache. URLs\nnot in the observation set return `found: false`; you still pay for the batch.\n\n### Finding better alternatives (`x402_find_alternatives`)\n\nBefore paying an unknown endpoint, check whether a better-tested alternative\nexists for the same purpose. `x402_find_alternatives` returns up to 25\nendpoints (default 5) that are **semantically similar** to a given URL — matched\non advertised purpose via description embeddings — and that **out-score it**\non our deterministic trust score. Each alternative returns `score`, `grade`,\n`recommendation`, cosine `similarity` (0-1), `amountUsd` price, and a free\n`endpointPage` URL. Same-host siblings and `avoid`-flagged endpoints are\nexcluded; an empty `alternatives` array is a valid answer meaning nothing beats\nthe subject. Cost is ~$0.005 per call.\n\n### Semantic search (`x402_semantic_search`)\n\nDescribe the capability you need in plain words and get the up to 25 closest\nendpoints in the monitored catalog. Ranking is deterministic: cosine similarity\nbucketed to whole percentage points first (80.3% and 80.5% are the same bucket),\nthen trust score, then described-before-undescribed, then endpoint id, with\nmatches below a 0.5 cosine-similarity floor dropped entirely (so a query can\nreturn fewer than the requested limit, or none). Endpoints that advertise no\ndescription are still matched via their service name and URL path tokens (host\nname as a last resort). The exact effect of a missing description: no fixed\npoint deduction and no direct similarity malus; the only deterministic penalty\nis the described-before-undescribed tiebreak (equal bucket AND equal score:\ndescribed wins). Beyond that it is purely indirect — the shorter fallback text\ntypically yields lower cosine similarity than a prose description, so such\nendpoints tend to land in lower buckets, by a query-dependent amount. Each\nmatch returns `id`, `resource`, `score`, `grade`, raw cosine `similarity` (0-1;\nranking buckets it), `description` (when advertised), and a free `endpointPage`\nURL. This is discovery, not verdicts: `score`/`grade` are null for unscored\nendpoints, and no recommendation or flag detail is included (use\n`x402_trust_score` for that). Cost is ~$0.001 per call.\n\n### Watch / alerting (`x402_watch_create`, `x402_watch_events`, `x402_watch_edit`, `x402_watch_cancel`, `x402_watch_renew`)\n\n- **Create** (`x402_watch_create`, paid) buys 30 days of change monitoring for\n  one endpoint. Pay over x402; receive a one-time bearer `secret`, a `poll_url`,\n  a `renew_url`, and machine-readable `next_steps`.\n- **Poll** (`x402_watch_events`, free) reads the append-only event log. It\n  returns two streams: `events` (endpoint changes — payTo / price / asset /\n  network / spec / delisting / liveness) and `watch_events` (lifecycle\n  feedback — created / edited / cancelled / renewed / expiring / expired), each\n  with their own cursor (`next_cursor` and `watch_events_cursor`). Page\n  forward by passing the previous response's cursors as `since` /\n  `watch_since`. Cursors/ids are global sequences shared across watches, so a\n  watch's first event id may be >1 — always use the returned `next_cursor`,\n  never assume events start at 1.\n- **Edit** (`x402_watch_edit`, free) changes webhook/Slack URLs, liveness\n  sensitivity, or subscribed events. Bearer-authed with the secret.\n- **Cancel** (`x402_watch_cancel`, free) soft-cancels a watch: no new events\n  accrue and probing drops back to normal cadence immediately, but the event\n  log stays readable via `x402_watch_events` until the original `expires_at`.\n  Cancel is **not** a delete.\n- **Renew** (`x402_watch_renew`, paid) extends the watch before `expires_at`.\n  The secret stays the same.\n\nOptional push delivery to one or more signed HTTPS webhooks and/or Slack/Discord\nincoming webhooks can be configured at creation time and updated via edit (up to\n5 of each per watch). `webhook_url` and `slack_url` accept a single URL string\nor an array of URLs. Any URL is **connection-tested before you are charged**:\nthe server POSTs a signed `connection_test` ping and, if it can't be delivered\n(3 attempts), rejects the change with `notCharged: true` so you can retry with\na corrected URL. On success the response reports per-URL delivery under\n`delivery.connection_test`.\n\nIf you use a webhook, verify the `x-signature` header equals `sha256=` +\nHMAC-SHA256(body) **keyed by the SHA-256 hex digest of your secret** — i.e. the\nHMAC key is `hex(sha256(secret))`, not the raw secret. (The delivery worker only\never holds that hash, never the plaintext secret.)\n\n### `x402_trust_score` result\n\nA single call returns everything an agent needs to decide **whether** and at\n**what price** to use an endpoint — no second round-trip, no raw-unit guessing:\n\n| Field | Meaning |\n|---|---|\n| `score` / `grade` | 0-100 point score and its A-F grade. |\n| `recommendation` | Machine verdict: `proceed` \\| `caution` \\| `avoid`. Already prices in data uncertainty — low confidence caps it at `caution` (a young endpoint is *unproven*, not *untrustworthy*); `avoid` is reserved for real negatives (error-severity flags, low score, recent payTo change). |\n| `scoreRange` | `{ low, point, high }` — a confidence-adjusted band. Decide conservatively against `low`. |\n| `confidence` / `confidenceDetail` | Overall confidence plus its parts: `observation` (data volume/age) vs `economic` (settlement coverage). |\n| `gradeThresholds` | The score cutoffs for each grade, so the verdict is auditable. |\n| `advertised` | The last observed 402 quote: `{ amount, amountUsd, asset, network, decimals, observedAtTs }`. Trust **and** cost in one call. |\n| `serviceName` / `description` | The provider-advertised name and description (unverified claim from the 402 envelope). Shown next to our independent metrics so you can sanity-check what the provider says against what we've measured. |\n| `flags` / `flagsDetailed` | Legacy string flags plus structured `{ code, severity, message }`. Rule of thumb: **any flag with `severity: \"error\"` ⇒ avoid.** |\n| `breakdown` / `subscores` | The full deterministic math (uptime, compliance, latency, age, activity, stability → technical / spec / economic subscores). |\n| `stats` | Observed evidence: probe counts, latency, payTo, `settledVolumeUsd30d`, distinct payers, and a `payToChanged*` hijack signal when the receiving wallet changed recently. |\n\nEverything is computed deterministically (no LLM) from continuous on-chain and\nprobe observation, so the breakdown is fully auditable.\n\n## x402 V2 Payment Flow\n\nThis MCP server uses the canonical x402 V2 payment flow:\n\n1. **402 + `PAYMENT-REQUIRED`** — The server responds with HTTP 402 and a\n   base64-encoded `PAYMENT-REQUIRED` header containing the payment requirements\n   (accepts, network, asset, amount, payTo).\n2. **Sign + retry with `PAYMENT-SIGNATURE`** — The MCP client signs an\n   EIP-3009 `transferWithAuthorization` for the selected accept and re-POSTs\n   with the `PAYMENT-SIGNATURE` header (base64-encoded payment payload).\n3. **Settlement + `PAYMENT-RESPONSE`** — The server settles the payment and\n   responds with the data plus a `PAYMENT-RESPONSE` header.\n\nLegacy `X-PAYMENT` / `X-PAYMENT-RESPONSE` headers are accepted as a fallback\nduring the V1→V2 transition period but are not the default.\n\n**Accept selection:** When a 402 response offers multiple accepts (e.g. Solana\n+ Base USDC), the client selects the best compatible one (canonical USDC on an\nallow-listed chain) rather than blindly taking the first accept.\n\n## Install\n\nAdd to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"x402-trust\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"x402-trust-mcp\"]\n    }\n  }\n}\n```\n\nTo enable autonomous payment for the paid tools, add a funded Base USDC wallet:\n\n```json\n{\n  \"mcpServers\": {\n    \"x402-trust\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"x402-trust-mcp\"],\n      \"env\": {\n        \"X402_PRIVATE_KEY\": \"0xYOUR_BASE_WALLET_KEY\",\n        \"X402_MAX_USD\": \"0.05\"\n      }\n    }\n  }\n}\n```\n\n## Configuration (env vars)\n\n| Var | Default | Description |\n|---|---|---|\n| `X402_TRUST_API_BASE` | `https://x402.fuchss.app` | API base URL. |\n| `X402_PRIVATE_KEY` | _(unset)_ | Base wallet private key. Enables auto-pay for paid tools. Accepted with or without the `0x` prefix (surrounding whitespace is trimmed); a set-but-malformed key logs a warning and leaves auto-pay off rather than failing silently. |\n| `X402_MAX_USD` | `0.05` | Per-call auto-pay ceiling. 0 disables auto-pay. |\n| `X402_MAX_TOTAL_USD` | `1.00` | Cumulative auto-pay cap per process. 0 = unlimited. |\n| `X402_MAX_CALLS` | `1000` | Max paid calls per process. 0 = unlimited. |\n| `X402_TIMEOUT_MS` | `20000` | Request timeout. |\n\nThe free tools work with no configuration at all.\n\n## Security\n\n`X402_PRIVATE_KEY` is a hot wallet — fund it with only what you're willing to\nspend on trust lookups. The key never leaves your machine; it signs EIP-3009\npayment authorizations locally.\n\n**Policy checks enforced before signing:**\n- Chain allow-list (Base mainnet by default)\n- Canonical USDC contract verification (no arbitrary tokens)\n- Optional payTo allow-list\n- Per-call spend ceiling (`X402_MAX_USD`)\n- Cumulative spend cap (`X402_MAX_TOTAL_USD`)\n- Call-count cap (`X402_MAX_CALLS`)\n\n## Verifying response signatures\n\nTool results are provider-signed: the `result` object of signed tools carries\na top-level `signature` block with an Ed25519 signature over the\nJCS-canonicalized (RFC 8785) response without the `signature` field. This\nproves the content was assembled by x402-trust and not modified afterwards.\n\nTo verify a result:\n\n1. Take the `result` object and remove its `signature` field.\n2. Canonicalize with JCS (RFC 8785): object keys sorted by UTF-16 code unit\n   order, no whitespace, ECMAScript number formatting.\n3. SHA-256 the canonical UTF-8 bytes; the hex must equal `signature.digest`.\n4. Verify `signature.value` (base64url, no padding) against the public key\n   that `signature.keyId` resolves to in your PINNED copy of the key document\n   (see below).\n\n**Trust anchor: pin, do not follow.** `signature.publicKeys` is a discovery\nhint, never a trust source. A verifier that fetches the key URL from the\nresponse it is checking verifies against a key chosen by the sender, which\nproves nothing: a forged response would carry the attacker's own key URL and\nstill verify. Pin one of these in your client instead:\n\n- the public key itself (strongest, works offline; add new keys on rotation),\n  e.g. `{ \"x402trust-2026-08\": \"i4jrHKvmZ98-IGgseDfMTjMV4lAaLAgk-EnBeRIJQ5Y\" }`\n  (current at the time of writing; the key document always carries the full\n  list, retired keys included), or\n- the key document URL\n  `https://x402.fuchss.app/.well-known/x402-trust-keys.json`, fetched over\n  HTTPS once at bootstrap and cached (rotation-friendly).\n\nRetired keys stay published forever, so a response you froze as evidence\nremains verifiable. A worked test vector and a 20-line reference verifier\nlive at https://x402.fuchss.app/schemas. Watch management responses\n(`x402_watch_create`, `x402_watch_edit`, `x402_watch_cancel`,\n`x402_watch_renew`) are unsigned by design: they carry capability secrets\nthat must never be forwarded as evidence.\n\n## License\n\nMIT\n",
  "bytes": 17029,
  "sha": "951cf65a6f30f855cfb3dc399ae4fcc3029376508a4b866b39c97d3241c0f1fb",
  "repo_slug": "jonasfuchss/x402-trust-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jonasfuchss_x402_trust_mcp_1771b1e2/readme"
}