DEV Community

rplryan
rplryan

Posted on

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

#python #web3 #agents #blockchain

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

5-Minute Quickstart

Install 

pip install x402-payment-harness
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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())
Enter fullscreen mode Exit fullscreen mode

Or via CLI:

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

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"}
   }
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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"}
Enter fullscreen mode Exit fullscreen mode

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())
Enter fullscreen mode Exit fullscreen mode

Running the Tests 

pip install x402-payment-harness
python -m pytest tests/ -v
Enter fullscreen mode Exit fullscreen mode

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

Links

Built as open-source infrastructure for the x402 ecosystem on Base. Contributions welcome.

Top comments (0)