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 a few tenths of a cent to ~$0.50, 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.

Watch / alerting (x402_watch_create, x402_watch_events, x402_watch_renew)

• Create (x402_watch_create) 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) reads the append-only event log. Start without since; afterwards pass the highest returned event_id as the next since. Send Authorization: Bearer <secret> — this is done automatically by the tool.
• Renew (x402_watch_renew) 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 (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 watch with notCharged: true so you can retry with a corrected URL. On success the create response reports per-URL delivery under delivery.connection_test.

• x402_watch_events polls the append-only log (free). It returns two streams: events (endpoint changes) and watch_events (lifecycle feedback — created / edited / cancelled / renewed / expiring / expired), each with its own cursor (next_cursor / watch_events_cursor). Every alert is timestamped (observed_at_iso).
• x402_watch_edit changes webhook/Slack URLs, liveness sensitivity, or events for free (bearer-authed). New URLs are connection-tested before the change is persisted; if any new URL fails, the existing config stays unchanged.
• x402_watch_cancel cancels a watch early for free (bearer-authed), returning the endpoint to normal probe cadence immediately.
• x402_watch_renew extends a watch by another 30 days (paid).

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