DEV Community: rplryan

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

rplryan — Wed, 04 Mar 2026 21:02:43 +0000

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.

x402 Payment Harness: Making x402 Payments Without a Coinbase CDP Wallet

rplryan — Fri, 27 Feb 2026 23:50:10 +0000

x402 Payment Harness: Making x402 Payments Without a Coinbase CDP Wallet

The x402 protocol is elegant: an HTTP client hits an endpoint, gets a 402 Payment Required response, signs a USDC micropayment using EIP-712, and retries with an X-PAYMENT header. Server verifies, returns 200. No API keys, no subscriptions, no Stripe.

The problem: every Python implementation assumed you had a Coinbase CDP wallet. If you're a protocol researcher, a server builder testing your own endpoints, or an agent developer who doesn't want CDP account creation + KYC-adjacent onboarding — you had no clean path.

x402-payment-harness fixes this.

pip install x402-payment-harness

What it does

A pure Python library + CLI that implements the full x402 protocol flow using any standard Ethereum EOA (a regular private key, no CDP required):

HTTP GET /endpoint
    → 402 Payment Required + EIP-712 challenge
    → Local EIP-712 sign (TransferWithAuthorization)
    → Retry with X-PAYMENT header
    → 200 OK + receipt

No Coinbase account. No CDP SDK. No vendor lock-in.

5-Minute Quickstart

Install

pip install x402-payment-harness

Set up a wallet

You need any Ethereum wallet with USDC on Base. Two options:

Option A: Use an existing private key

export X402_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
export X402_WALLET_ADDRESS=0xYOUR_ADDRESS

Option B: Generate a test wallet

from eth_account import Account
account = Account.create()
print(f"Address: {account.address}")
print(f"Private key: {account.key.hex()}")
# Fund with USDC on Base mainnet

Make your first x402 payment

from x402_harness import X402Client, PaymentConfig

client = X402Client(PaymentConfig(
    private_key="0xYOUR_PRIVATE_KEY",
    wallet_address="0xYOUR_ADDRESS"
))

# Hit any x402 endpoint
response = client.call("https://x402-discovery-api.onrender.com/discover?q=weather")
print(response.json())

Or via CLI:

x402-pay https://x402-discovery-api.onrender.com/discover?q=weather \
  --key 0xYOUR_PRIVATE_KEY \
  --address 0xYOUR_ADDRESS

How the Protocol Flow Works

The harness implements the full x402 spec in three steps:

Step 1: Probe the endpoint

GET /discover?q=weather
→ HTTP 402
   X-Payment-Required: {
     "scheme": "exact",
     "payTo": "0xServer...",
     "maxAmountRequired": "5000",  // 5000 USDC micro-units = $0.005
     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
     "extra": {"name": "USDC", "version": "2"}
   }

Step 2: Sign the payment (EIP-712)

The harness constructs a TransferWithAuthorization payload and signs it locally using EIP-712 typed data:

transfer = {
    "from": wallet_address,
    "to": payTo,
    "value": amount,
    "validAfter": now - 30,
    "validBefore": now + 300,
    "nonce": os.urandom(32).hex()  # random UUID-style nonce
}
signed = Account.sign_typed_data(private_key, domain, types, transfer)

This is pure Python — no RPC calls, no contract interaction at this step.

Step 3: Retry with X-PAYMENT header

GET /discover?q=weather
X-PAYMENT: <base64(JSON(signed_payload))>
→ HTTP 200
   X-Payment-Response: {"success": true, "payer": "0x...", "network": "eip155:8453"}

The server verifies the EIP-712 signature locally and returns 200. In a full x402 implementation, the server would then call receiveWithAuthorization on the USDC contract to settle the payment on-chain.

Who This Is For

Use case	Why this helps
x402 server builders	Test your own endpoints without a CDP wallet or external dependency
Agent developers	Add x402 payment capability to any Python agent with a standard EOA
Protocol researchers	Full x402 flow in ~100 lines of Python, readable + hackable
CI/CD pipelines	Inject `X402_PRIVATE_KEY` as a secret, test x402 endpoints automatically

Test Against Live x402 Services

The harness works against any x402-compliant endpoint. There are now 251+ live services in the x402 ecosystem. Use the x402 Service Discovery API to find them:

import requests

# Find an x402 service (free)
catalog = requests.get("https://x402-discovery-api.onrender.com/catalog?category=data")
service = catalog.json()["services"][0]

# Pay and call it
response = client.call(service["url"])
print(response.json())

Running the Tests

pip install x402-payment-harness
python -m pytest tests/ -v

The test suite verifies: EIP-712 struct hash, signature construction, base64 encoding, protocol flow. All 4 tests pass against the live discovery API endpoint.

What's Not in the Harness (By Design)

This library handles the client-side protocol flow:

HTTP 402 challenge reception
EIP-712 signing (TransferWithAuthorization)
X-PAYMENT header construction

It does not handle on-chain settlement. After the server verifies your signature, in a fully implemented x402 server, receiveWithAuthorization would be called on the USDC contract to actually move funds. The harness is for testing the signing/challenge/verification layer — which is where most of the protocol complexity lives.

The Full x402 Stack

The harness is part of a broader open-source x402 infrastructure suite:

Component	What it is	Link
x402-payment-harness	This library — EOA-based x402 client	GitHub / PyPI
x402 Service Discovery API	251+ indexed services, health monitoring, ERC-8004 trust	Live API
x402 RouteNet	Smart routing across services (cheapest/fastest/best)	Live API
x402-discovery-mcp	MCP server with 6 tools for Claude/Cursor	GitHub

Add x402 Service Discovery to Claude and Cursor in 30 Seconds

rplryan — Thu, 26 Feb 2026 16:45:12 +0000

The Problem

You're building with Claude, Cursor, or Cline. You want to call a paid x402 API — but you have no idea which services exist, what they cost, or whether they're actually up. You end up hardcoding endpoints or manually browsing directories.

There's a better way.

The Solution: 2 Config Lines

Add the x402 Service Discovery MCP server to your Claude Desktop or Cursor config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "x402-discovery": {
      "url": "https://x402-discovery-api.onrender.com/smithery",
      "transport": "http"
    }
  }
}

Cursor (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "x402-discovery": {
      "url": "https://x402-discovery-api.onrender.com/smithery",
      "transport": "http"
    }
  }
}

Restart Claude/Cursor. That's it.

What Claude Can Now Do

Ask Claude: "Find me x402 APIs for web scraping"

Claude will call x402_discover and return live results from 251+ indexed x402 services — with real health scores, latency data, and ERC-8004 trust signals.

Found 3 services matching 'web scraping':

1. Firecrawl — Web Scraping & Extraction API
   Price: $0.002/request | Health: Healthy | Uptime: 99.1%
   URL: https://api.firecrawl.dev/x402/scrape
   Tags: scraping, markdown, llm-ready

2. Browserless — Headless Chrome API
   Price: $0.005/request | Health: Healthy | Uptime: 98.7%
   URL: https://chrome.browserless.io/content
   Tags: browser, automation, screenshot

3. Jina AI Reader — URL to LLM-Ready Content
   Price: $0.0001/request | Health: Healthy | Uptime: 99.8%
   URL: https://r.jina.ai/x402
   Tags: reader, markdown, content

6 MCP Tools Available

Tool	What it does	Cost
`x402_discover`	Search 251+ services by keyword/capability	$0.005 USDC
`x402_browse`	Browse full catalog by category	Free
`x402_health`	Check uptime & latency for any service	Free
`x402_register`	Add your own service to the catalog	Free
`x402_trust`	ERC-8004 on-chain trust profile lookup	Free
`x402_facilitator_check`	Verify facilitator compatibility	Free

Note on x402_discover: The $0.005 cost is an x402 micropayment — the protocol handles it automatically if your agent has a Base/USDC wallet. For manual browsing, use x402_browse (always free).

251+ Services Indexed

The catalog auto-scans x402.org/ecosystem, awesome-x402, and the Coinbase Bazaar every 6 hours. Current categories:

data (60+): Einstein AI, SIBYL token scoring, DJD Agent Score, Nansen, Zapper, CoinGecko…
compute (40+): BlockRun.AI (28 LLM APIs), AurraCloud, X402Engine…
utility (50+): Firecrawl, Browserless, dTelecom STT, Pinata…
agent (30+): Questflow, AgentKit reference, Ubounty…

All with real uptime monitoring and health scoring — not just a static list.

Smart Routing: x402 RouteNet

Once you discover services, RouteNet picks the best one:

curl "https://x402-routenet.onrender.com/route?q=web+scraping&strategy=best"

Four routing strategies: cheapest, fastest, most_trusted, best (composite score).

Trust Layer: ERC-8004

Ask Claude: "Find me a web scraping API that's ERC-8004 verified"

{
  "name": "Firecrawl",
  "uptime_pct": 99.1,
  "avg_latency_ms": 145,
  "erc8004_verified": true,
  "erc8004_reputation_score": 87
}

Browse the Catalog Right Now

No setup needed:

curl "https://x402-discovery-api.onrender.com/catalog"

Register Your Service (Free)

import requests
requests.post('https://x402-discovery-api.onrender.com/register', json={
    'name': 'My AI Service',
    'description': 'Does something useful for agents',
    'url': 'https://myservice.com/api',
    'category': 'data',
    'price_usd': 0.001,
    'network': 'base'
})

x402 Service Discovery: How Autonomous Agents Find and Pay for APIs at Runtime

rplryan — Thu, 26 Feb 2026 13:22:22 +0000

x402 Service Discovery: How Autonomous Agents Find and Pay for APIs at Runtime

Autonomous agents need to call paid APIs. The problem: there's no standard way to find them.

You don't want to hardcode 50 endpoint URLs into your agent. You want it to discover the best available service for any capability at runtime — like DNS for the agent economy.

That's what x402 Service Discovery does.

What is x402?

x402 is a protocol that lets HTTP servers charge for API calls using USDC stablecoin micropayments on Base. A client hits an endpoint, gets a 402 Payment Required response with a payment challenge, pays ~$0.001–$0.05 in USDC, then retries the request with a payment proof header. No API keys, no subscriptions, no billing dashboards.

The discovery problem

The x402 ecosystem is growing — there are services for research, data feeds, compute, AI agents — but there's no index. You have to know a URL exists before you can call it.

We built the missing piece: a service registry where x402-payable APIs can register themselves, and agents can query by capability.

How it works

Free: Browse the full catalog

curl https://x402-discovery-api.onrender.com/catalog

Gated: Query by capability (x402 payment required)

curl "https://x402-discovery-api.onrender.com/discover?q=research+API"
# → 402 Payment Required
# x-payment-required: {"payTo": "0xDBBe14C418466Bf5BF0ED7638B4E6849B852aFfA", "amount": "5000", ...}

Cost: $0.005 USDC per query. Payment handled automatically by x402-capable clients.

Python SDK

pip install x402discovery

Framework integrations

Now supporting 6 frameworks:

1. Coinbase AgentKit (NEW ✨)

The natural home for x402 — AgentKit agents already have a funded Base/USDC wallet. The x402_pay_and_call action closes the full loop: discover → pay → execute, all in one step.

pip install agentkit-x402-discovery

from agentkit_x402_discovery import x402_discovery_action_provider
from coinbase_agentkit import AgentKit, AgentKitConfig

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider,
    action_providers=[
        x402_discovery_action_provider(),
        # ... your other providers
    ]
))

# Your agent now has 4 new actions:
# x402_discover  — Find services by keyword/capability
# x402_browse    — List full catalog (free, no payment)
# x402_health    — Check service uptime & latency
# x402_pay_and_call — Discover + pay + call in one shot

2. LangChain

pip install langchain-x402-discovery

from langchain_x402_discovery import X402DiscoveryTool
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")
tools = [X402DiscoveryTool()]
agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
agent.run("Find a research API under $0.05/call")

3. AutoGen

pip install autogen-x402-discovery

4. CrewAI

pip install crewai-x402-discovery

5. LlamaIndex

pip install llama-index-x402-discovery

6. Raw Python

from x402discovery import X402DiscoveryClient
client = X402DiscoveryClient()
results = client.discover(query="weather data", max_price_usd=0.10)

MCP (Model Context Protocol)

Available as an MCP server on Smithery with 5 tools: x402_discover, x402_browse, x402_health, x402_register, x402_trust.

Trust Layer: ERC-8004 Integration (NEW ✨)

Beyond quality signals (uptime, latency), we now surface on-chain trust identity for every registered service.

ERC-8004 is a new Ethereum standard (January 2026) that provides decentralized AI agent trust via three on-chain registries:

Identity Registry — unique on-chain identifier for each agent/service
Reputation Registry — verifiable scores from real interactions
Validation Registry — third-party attestations from auditors and ecosystem partners

Every service in our catalog now returns trust fields alongside quality signals:

{
  "name": "My x402 API",
  "uptime_pct": 99.1,
  "avg_latency_ms": 145,
  "erc8004_verified": true,
  "erc8004_reputation_score": 87,
  "erc8004_attestations": 3,
  "erc8004_source": "well-known"
}

New: `/trust/{wallet}` endpoint

Look up the ERC-8004 trust profile for any wallet address:

curl https://x402-discovery-api.onrender.com/trust/0xDBBe14C418466Bf5BF0ED7638B4E6849B852aFfA

Returns identity metadata, reputation score, and attestation count — sourced from the ERC-8004 on-chain registries and /.well-known/erc8004.json declarations.

New MCP tool: `x402_trust`

The MCP server now exposes 5 tools (up from 4):

Tool	What it does	Cost
`x402_discover`	Search services by keyword/capability	$0.005 USDC
`x402_browse`	Browse full catalog by category	Free
`x402_health`	Check uptime & latency	Free
`x402_register`	Register your service	Free
`x402_trust`	Look up ERC-8004 trust profile for any wallet	Free

The demo at rplryan.github.io/ouroboros/demo.html shows ERC-8004 verification badges on services that have declared on-chain identity.

Register your x402 service

import requests
requests.post("https://x402-discovery-api.onrender.com/register", json={
    "id": "my-service",
    "name": "My x402 API",
    "url": "https://my-api.com/endpoint",
    "price_usd": 0.01,
    "description": "Does something useful",
    "capability_tags": ["data", "research"],
    "wallet_address": "0xYOUR_WALLET",
    "network": "base"
})

Registration is free. Health monitoring is automatic. Once registered, your service gets ERC-8004 trust lookup automatically if your wallet has an on-chain identity.

What's next

The catalog grows as more x402 services register. Quality signals (uptime_pct, avg_latency_ms, health_status) plus ERC-8004 trust scores let agents prefer reliable, verified services — the full trust layer the x402 ecosystem needs.

Links:

API: https://x402-discovery-api.onrender.com
Smithery MCP: https://smithery.ai/servers/rplryan/x402-discovery
AgentKit package: https://pypi.org/project/agentkit-x402-discovery/
PyPI (all packages): https://pypi.org/project/x402discovery/
Interactive Demo: https://rplryan.github.io/ouroboros/demo.html
GitHub: https://github.com/rplryan/ouroboros

DEV Community: rplryan

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

What is x402?

Install: 60 Seconds

The 6 Discovery Tools

Your First Discovery

The Trust Layer

Checking Health Before Paying

Autonomous Execution with scout_relay

Registering Your Own Service

What to Build Next

x402 Payment Harness: Making x402 Payments Without a Coinbase CDP Wallet

x402 Payment Harness: Making x402 Payments Without a Coinbase CDP Wallet

What it does

5-Minute Quickstart

Install

Set up a wallet

Make your first x402 payment

How the Protocol Flow Works

Step 1: Probe the endpoint

Step 2: Sign the payment (EIP-712)

Step 3: Retry with X-PAYMENT header

Who This Is For

Test Against Live x402 Services

Running the Tests

What's Not in the Harness (By Design)

The Full x402 Stack

Links

Add x402 Service Discovery to Claude and Cursor in 30 Seconds

The Problem

The Solution: 2 Config Lines

What Claude Can Now Do

6 MCP Tools Available

251+ Services Indexed

Smart Routing: x402 RouteNet

Trust Layer: ERC-8004

Browse the Catalog Right Now

Register Your Service (Free)

Links

x402 Service Discovery: How Autonomous Agents Find and Pay for APIs at Runtime

x402 Service Discovery: How Autonomous Agents Find and Pay for APIs at Runtime

What is x402?

The discovery problem

How it works

Free: Browse the full catalog

Gated: Query by capability (x402 payment required)

Python SDK

Framework integrations

1. Coinbase AgentKit (NEW ✨)

2. LangChain

3. AutoGen

4. CrewAI

5. LlamaIndex

6. Raw Python

MCP (Model Context Protocol)

Trust Layer: ERC-8004 Integration (NEW ✨)

New: /trust/{wallet} endpoint

New MCP tool: x402_trust

Register your x402 service

What's next

New: `/trust/{wallet}` endpoint

New MCP tool: `x402_trust`