x402 MCP tool demo — a real 402, a real rejection, zero funds at risk

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. Fund the agent_address with Base Sepolia testnet USDC (any faucet) to see round 2 return 200 with a payment-response settlement receipt instead.

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.