x402 MCP tool demo — a real 402, a real rejection, and a real settlement

A minimal demo of the x402 payment protocol protecting an MCP-style tool endpoint, run against the real x402==2.16.0 Python package and its default public facilitator (https://x402.org/facilitator) on Base Sepolia testnet. Nothing here is hand-written protocol JSON — every response in captured_responses/ came out of the library, unedited.

Companion to: How to Charge for an MCP Tool: A Working x402 Endpoint in Under an Hour.

What's here

Related MCP server: 402-mcp

Run it

pip install -r requirements.txt
python gen_wallets.py          # writes wallets.json (gitignored) -- two fresh, empty keys
python server.py               # starts on 127.0.0.1:8402
python client_probe.py         # in a second terminal

What you'll see

Round 1 — no payment. A 402 with a payment-required header (base64 JSON): scheme, network, asset contract, amount in the token's smallest unit, and the address to pay.

Round 2 — a real signed payment, zero balance. The client builds and signs an actual EIP-3009 authorization with the throwaway key, attaches it as X-PAYMENT, and the facilitator checks it against the real Base Sepolia chain state. It comes back:

{ "error": "invalid_exact_evm_insufficient_balance" }

That string is the facilitator's real error code, not a guess — it is what you get when the protocol works exactly as designed and the payer simply doesn't have the money.

Round 3 — funded, settled for real. The agent_address was funded with 20 testnet USDC from Circle's public faucet, then client_probe.py was run again against the same server. This time round 2 comes back 200:

{
  "url": "https://example.com/mcp",
  "recommendation": "expose as a priced x402 tool at $0.01/call",
  "paid": true
}

with a payment-response header that decodes to:

{ "success": true, "payer": "0x3214cB6C...E0E9", "transaction": "0x9530b663...0dd86", "network": "eip155:84532" }

That transaction hash is real and independently verifiable — view it on Base Sepolia Blockscout: status ok, sent to the USDC contract, method transferWithAuthorization — the exact EIP-3009 gasless-transfer pattern the payer signed. Anyone can check this without trusting this README.

Why the manual round trip in client_probe.py

x402 2.16.0 ships PaymentRoundTripper, but it's a callback (handle_response(...)) meant to be wired into a custom httpx/requests transport — it is not a drop-in transport by itself, despite what the docstring implies. client_probe.py calls the same three primitives it calls internally (get_payment_required_response → create_payment_payload → encode_payment_signature_header) directly, which is fewer moving parts for a demo and produces identical wire output.

Safety notes

• gen_wallets.py creates keys with eth_account.Account.create() — cryptographically random, never funded, never touching mainnet in this demo.

• wallets.json is gitignored. wallets.example.json shows the shape with a well-known burn address so the repo is runnable from a clean clone without secrets in git history.

• The facilitator URL, network, and asset contract are the library's own testnet defaults — nothing here talks to Base mainnet or moves real value.