The x402 Protocol in Practice: HTTP 402 Payments for AI Agents (Node.js Guide)

#x402 #aiagents #node #payments

HTTP 402 (Payment Required) sat unused in the spec for 30 years. The x402 movement is changing that: AI agents paying APIs per call, no accounts, no API keys, no Stripe onboarding — just an on-chain USDC transfer and a signed receipt.

After integrating 402 payments on several Node.js services, here is the pattern that actually works in production.

The flow

Agent calls your endpoint without payment
Your server replies 402 with a payment challenge (amount, wallet address, chain)
Agent sends the USDC transfer on-chain
Agent retries the call attaching a payment header
Your server verifies the tx on-chain and serves the response

The server in ~30 lines

import express from 'express';
import { verifyPayment, paymentChallenge } from '@josealbertomaquina/usdc-paywall';

const app = express();
app.use(express.json());

app.post('/api/generate', verifyPayment({
  amount: 0.05,            // USDC per call
  chain: 'base',
  wallet: process.env.WALLET,
}), (req, res) => {
  res.json({ result: 'your expensive compute here' });
});

app.use(paymentChallenge()); // emits 402 + challenge headers
app.listen(3000);

The client side is equally short: catch the 402, read the challenge, pay with any EVM wallet, attach the receipt header, retry.

Why per-call USDC beats API keys for agents

Zero onboarding: an agent can pay without a signup flow or a human buying a plan
No chargebacks, no KYB: funds go straight to your wallet
Machine-native pricing: $0.01 per call is trivial to settle on Base (fees under a cent)
No key leakage: keys shared across agent runs are a real liability; payments are per-call

What to watch out for

Verify on-chain, not client-side: trust only a fresh transaction receipt with the right recipient and amount
Replay protection: cache verified tx hashes so one payment cannot unlock unlimited calls
Confirmations: for low amounts, one confirmation on Base is enough; make it configurable
Price anchoring: charge in USDC but think in cost-per-outcome your buyer understands

Try it

The middleware above is @josealbertomaquina/usdc-paywall (GitHub / npm): MIT for self-serve, plus a Pro tier ($19) with replay-safe verification, multi-chain support and priority support if you want batteries included.

Machine-to-machine payments are the first genuinely new internet payments primitive in a decade. The services that speak 402 today are the ones agents will spend money on tomorrow.

DEV Community