x402 Payment Integration Guide

One-line: How to implement HTTP-native x402 micropayments on Base with USDC, enabling agent-to-agent commerce.

When to use

• You want to monetize an API with per-request payments
• You need to integrate x402 as a payment receiver
• You want to build agent-friendly pricing
• You need to understand the x402 protocol flow

Instructions

The x402 Flow

1. Client sends HTTP request to endpoint
2. Server responds with HTTP 402 + payment spec
3. Client signs EIP-3009 TransferWithAuthorization
4. Client retries with X-PAYMENT header
5. Server verifies payment, processes request
6. Payment settles on-chain in seconds

Implementation Steps

Step 1: Set up your Base wallet

• Generate or import a wallet
• Fund with USDC on Base
• This wallet receives all payments

Step 2: Implement the 402 challenge

• On first request, respond with 402 status
• Include payment requirements in response body
• Specify USDC contract on Base
• Set price in atomic units (6 decimals)

Step 3: Verify payments

• Check EIP-3009 signature validity
• Verify nonce hasn't been used
• Check payment amount matches
• Confirm from address matches requester

Step 4: Handle edge cases

• Expired authorizations (validBefore)
• Insufficient USDC balance
• Network errors during settlement
• Replay attacks (nonce tracking)

Pricing Models

• Per-request: Fixed price per API call ($0.001-$0.10)
• Nanopayments: Ultra-low cost via Circle Gateway ($0.0001)
• Credit drawdown: Pre-purchased bundles for volume discounts
• Freemium: Free tier + paid premium features

Security Best Practices

• Never trust client-provided payment amounts
• Always verify the signer owns the wallet
• Use short validity windows (60-300 seconds)
• Track used nonces to prevent replay
• Monitor for unusual payment patterns

Tools Required

• Node.js with viem or ethers
• Base RPC endpoint
• USDC on Base for testing
• x402 client library (@x402/core)

Version

v1.0 - last updated 2026-08-20