X402 Trust MCP Server

x402-trust-mcp

An MCP server that lets your agent check the trust & reliability of x402 endpoints before paying them.

Backed by x402.fuchss.app, which monitors the entire x402 ecosystem on Base 24/7: uptime probes, 402-envelope spec compliance, advertised-price history, and real on-chain USDC settlement volume per endpoint.

Why

Agents increasingly pay x402 endpoints autonomously. But ~⅔ of listed x402 endpoints are unreachable and ~⅓ of the reachable ones serve non-compliant payment envelopes. Before your agent sends USDC to an unknown endpoint, ask: is it alive, compliant, and does anyone actually pay it?

Tools

Paid tools cost from $0.005 (a single trust / similar lookup) up to ~$0.50 (500-endpoint bulk batch) or ~$0.20 for a 30-day watch, charged over x402 (USDC on Base). If you set X402_PRIVATE_KEY, the server auto-pays within your X402_MAX_USD limit; otherwise it returns the price quote for your host to pay.

Bulk scoring (x402_trust_bulk)

The bulk tool is the scale axis: score up to 500 endpoints in one call from the same data that powers the leaderboard. It auto-selects the cheapest tier that fits your request:

Cached rows older than ~15 minutes are recomputed on-demand from the latest stored probes and settlements (no live network re-probe), so bulk scores usually reflect reality within minutes. Per-request recompute limits apply: at most 50 rows / 8 seconds are recomputed; the response tells you via recompute_limit_hit + recompute_limit. Each result carries score, grade, recommendation, confidence, probed_at, computed_at, and recomputed so you can see exactly which rows were freshly computed vs served from cache. URLs not in the observation set return found: false; you still pay for the batch.

Finding better alternatives (x402_find_alternatives)

Before paying an unknown endpoint, check whether a better-tested alternative exists for the same purpose. x402_find_alternatives returns up to 25 endpoints (default 5) that are semantically similar to a given URL — matched on advertised purpose via description embeddings — and that out-score it on our deterministic trust score. Each alternative returns score, grade, recommendation, cosine similarity (0-1), amountUsd price, and a free endpointPage URL. Same-host siblings and avoid-flagged endpoints are excluded; an empty alternatives array is a valid answer meaning nothing beats the subject. Cost is ~$0.005 per call.

Watch / alerting (x402_watch_create, x402_watch_events, x402_watch_edit, x402_watch_cancel, x402_watch_renew)

• Create (x402_watch_create, paid) buys 30 days of change monitoring for one endpoint. Pay over x402; receive a one-time bearer secret, a poll_url, a renew_url, and machine-readable next_steps.
• Poll (x402_watch_events, free) reads the append-only event log. It returns two streams: events (endpoint changes — payTo / price / asset / network / spec / delisting / liveness) and watch_events (lifecycle feedback — created / edited / cancelled / renewed / expiring / expired), each with their own cursor (next_cursor and watch_events_cursor). Page forward by passing the previous response's cursors as since / watch_since. Cursors/ids are global sequences shared across watches, so a watch's first event id may be >1 — always use the returned next_cursor, never assume events start at 1.
• Edit (x402_watch_edit, free) changes webhook/Slack URLs, liveness sensitivity, or subscribed events. Bearer-authed with the secret.
• Cancel (x402_watch_cancel, free) soft-cancels a watch: no new events accrue and probing drops back to normal cadence immediately, but the event log stays readable via x402_watch_events until the original expires_at. Cancel is not a delete.
• Renew (x402_watch_renew, paid) extends the watch before expires_at. The secret stays the same.

Optional push delivery to one or more signed HTTPS webhooks and/or Slack/Discord incoming webhooks can be configured at creation time and updated via edit (up to 5 of each per watch). webhook_url and slack_url accept a single URL string or an array of URLs. Any URL is connection-tested before you are charged: the server POSTs a signed connection_test ping and, if it can't be delivered (3 attempts), rejects the change with notCharged: true so you can retry with a corrected URL. On success the response reports per-URL delivery under delivery.connection_test.

If you use a webhook, verify the x-signature header equals sha256= + HMAC-SHA256(body) keyed by the SHA-256 hex digest of your secret — i.e. the HMAC key is hex(sha256(secret)), not the raw secret. (The delivery worker only ever holds that hash, never the plaintext secret.)

x402_trust_score result

A single call returns everything an agent needs to decide whether and at what price to use an endpoint — no second round-trip, no raw-unit guessing:

Everything is computed deterministically (no LLM) from continuous on-chain and probe observation, so the breakdown is fully auditable.

x402 V2 Payment Flow

This MCP server uses the canonical x402 V2 payment flow:

1. 402 + PAYMENT-REQUIRED — The server responds with HTTP 402 and a base64-encoded PAYMENT-REQUIRED header containing the payment requirements (accepts, network, asset, amount, payTo).
2. Sign + retry with PAYMENT-SIGNATURE — The MCP client signs an EIP-3009 transferWithAuthorization for the selected accept and re-POSTs with the PAYMENT-SIGNATURE header (base64-encoded payment payload).
3. Settlement + PAYMENT-RESPONSE — The server settles the payment and responds with the data plus a PAYMENT-RESPONSE header.

Legacy X-PAYMENT / X-PAYMENT-RESPONSE headers are accepted as a fallback during the V1→V2 transition period but are not the default.

Accept selection: When a 402 response offers multiple accepts (e.g. Solana

• Base USDC), the client selects the best compatible one (canonical USDC on an allow-listed chain) rather than blindly taking the first accept.

Install

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "x402-trust": {
      "command": "npx",
      "args": ["-y", "x402-trust-mcp"]
    }
  }
}

To enable autonomous payment for the paid tools, add a funded Base USDC wallet:

{
  "mcpServers": {
    "x402-trust": {
      "command": "npx",
      "args": ["-y", "x402-trust-mcp"],
      "env": {
        "X402_PRIVATE_KEY": "0xYOUR_BASE_WALLET_KEY",
        "X402_MAX_USD": "0.05"
      }
    }
  }
}

Configuration (env vars)

The free tools work with no configuration at all.

Security

X402_PRIVATE_KEY is a hot wallet — fund it with only what you're willing to spend on trust lookups. The key never leaves your machine; it signs EIP-3009 payment authorizations locally.

Policy checks enforced before signing:

• Chain allow-list (Base mainnet by default)
• Canonical USDC contract verification (no arbitrary tokens)
• Optional payTo allow-list
• Per-call spend ceiling (X402_MAX_USD)
• Cumulative spend cap (X402_MAX_TOTAL_USD)
• Call-count cap (X402_MAX_CALLS)

License

MIT