rplryan

Posted on Mar 4

How to Connect Claude to x402 APIs with MCP — No API Keys Required

#ai #mcp #claude #web3

The traditional API economy runs on API keys. You sign up for a service, wait for approval, pay a monthly subscription, and embed a secret string in your code. For human developers, this is annoying. For autonomous AI agents that need to discover and call APIs at runtime — it's a fundamental mismatch.

x402 Service Discovery MCP solves this for the emerging class of x402-payable APIs — services that implement the Coinbase x402 micropayment protocol, accepting USDC on Base as direct payment instead of API keys.

In this walkthrough, I'll show you how to connect Claude Desktop (or Cursor, or Windsurf) to the x402 discovery catalog in under 5 minutes — and make your first authenticated API call without a single API key. Then we'll look at scout_relay: the layer that automates discovery and execution into a single call.

What is x402?

x402 is an HTTP-native payment protocol. When an agent calls an x402-enabled endpoint without paying, it receives an HTTP 402 response with payment details. The agent pays with USDC on Base via EIP-712 signed authorization, includes an X-PAYMENT header in the retry, and the server returns the real response.

The full flow:

Agent → POST /api → 402 Payment Required
Agent → Signs EIP-712 → POST /api (X-PAYMENT: <signed-auth>) → 200 OK + data

No API keys. No subscriptions. Pure micropayments between machines.

The x402 ecosystem now has 343+ live services across data, compute, agent, and utility categories. The problem: how does an agent find the right service at runtime, and then pay for it autonomously?

Install: 60 Seconds

Add to claude_desktop_config.json (on macOS at ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "x402-discovery": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/rplryan/x402-discovery-mcp:latest"]
    }
  }
}

No Docker? Use npx:

{
  "mcpServers": {
    "x402-discovery": {
      "command": "npx",
      "args": ["-y", "@rplryan/x402-discovery-mcp"]
    }
  }
}

Restart Claude Desktop. You now have 6 new tools available.

Or install the CLI:

npm install -g x402scout
x402scout search "weather data"

The 6 Discovery Tools

Tool	What It Does	Cost
`x402_discover`	Ranked semantic search across 343+ services	$0.010 USDC
`x402_health`	Real-time uptime + latency check	Free
`x402_register`	Add a new service to the catalog	Free
`x402_attest`	ERC-8004 trust score and reputation data	Free
`x402_browse`	Verify facilitator compatibility	Free
`x402_scan`	Full compliance scan + trust score for any URL	Free

Worth noting: x402_discover itself costs $0.010 USDC per call, paid via x402. The discovery tool eats its own dogfood.

Your First Discovery

Open Claude and try:

"Find me x402-payable blockchain analytics APIs that cost less than $0.01 per call"

Claude will call x402_discover with category="data", max_price=0.01 and return something like:

[
  {
    "name": "Nansen Wallet Screener",
    "url": "https://nansen.ai/x402/screener",
    "price_usd": 0.008,
    "uptime_pct": 98.7,
    "latency_ms": 210,
    "facilitator_compatible": true,
    "trust_score": 87,
    "llm_usage_prompt": "Use this service to screen wallets for whale activity..."
  },
  ...
]

Every result includes llm_usage_prompt — a pre-written hint that tells Claude exactly how to use the discovered service. Discovery and usage instructions in one call.

The Trust Layer

Before an agent pays, it should verify the service is legitimate. Try:

"Check the trust score for https://example-x402-service.com"

x402_attest returns ERC-8004 reputation signals — on-chain verification that the service has a credible payment history and hasn't been flagged by the community.

Or scan any URL directly:

"Scan https://example-x402-service.com for x402 compliance"

x402_scan returns a full compliance report: protocol version, payment details format, EIP-3009 vs plain transfer, trust score (0–100).

Checking Health Before Paying

Before committing USDC to a call, check if the endpoint is actually up:

"Is https://example-service.com/api currently healthy?"

x402_health returns live uptime percentage, latency in milliseconds, and a boolean status. You can build agent workflows that skip unhealthy services and route to the next-best alternative.

Autonomous Execution with scout_relay

The discovery tools tell your agent what to call. scout_relay handles calling it — discovery, payment, retry, and result in a single operation.

# Route an intent — one call does everything
curl -X POST https://x402-scout-relay.onrender.com/route \
  -H "Content-Type: application/json" \
  -H "X-Payment: <your-x402-payment-header>" \
  -d '{"intent": "get current ETH price in USD", "max_budget_usd": 0.01}'

# Returns:
# {
#   "result": {"price": 3421.50, "source": "CoinGecko x402"},
#   "provider": "https://coingecko.x402.example/price",
#   "trust_score": 89,
#   "fee_usd": 0.003,
#   "retries": 0
# }

4 MCP tools for autonomous workflows:

Tool	What It Does	Cost
`scout_route`	Intent → discover → pay → result	max($0.003, 2.5%)
`scout_discover`	Query catalog without executing	Free
`scout_execute`	Execute payment to a known URL	max($0.003, 2.5%)
`scout_audit`	View agent spend log and budget status	Free

scout_relay is itself listed in the catalog it routes for — and charges its own /route endpoint via x402. The protocol all the way down.

Provider placement: Service providers can register routing priority bids at POST /placement/bid (x402-gated, $0.01 registration fee). Bids are used as tiebreakers after trust-score filtering — merit first, always.

Registering Your Own Service

If you've built an x402-enabled endpoint, add it to the catalog:

"Register my service: name=My Analytics API, url=https://myservice.example.com/api, price=0.005, category=data"

Or via curl:

curl -X POST https://x402scout.com/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Analytics API",
    "url": "https://myservice.example.com/api",
    "price_usd": 0.005,
    "category": "data",
    "description": "On-chain analytics with whale tracking",
    "network": "base-mainnet"
  }'

The auto-scanner picks it up within 6 hours. Your service now appears in every agent's discovery results — and scout_relay will route to it automatically when it matches an intent and passes the trust filter.

What to Build Next

A few directions worth exploring:

Autonomous API routing — use scout_relay's scout_route for fully autonomous discovery + payment in one line
Multi-service aggregation — discover 5 blockchain analytics services, query all of them in parallel, return the consensus answer
Cost-optimized workflows — discover the cheapest service in a category that meets a minimum trust threshold
Service monitoring — periodic x402_health checks across your discovered services, alerting when uptime drops
Provider placement — register your service's placement bid and track routing volume via the audit log

The protocol is nascent. The tooling is early. The interesting work is in the agent workflows built on top — and the full discovery + execution stack is now live to support them.

GitHub: https://github.com/rplryan/x402-discovery-mcp

API: https://x402scout.com

scout_relay: https://x402-scout-relay.onrender.com

CLI: npm install -g x402scout

MCP Registry: io.github.rplryan/x402-discovery-mcp

343+ services indexed. Built on coinbase/x402.

DEV Community