x402 · THE WALKTHROUGH

From one transfer to a payment gateway

Eleven chapters, each one a hurdle we hit and the move that cleared it. Chapters 1 to 3 run live in your browser on Solana devnet; the rest explain what we built.

Solana devnet · test tokens only · nothing here moves real money

Before you start

  1. Install Phantom and switch it to Solana devnet (Settings, Developer Settings, Testnet Mode).
  2. Get free devnet SOL for network fees from the Solana faucet.
  3. Get free devnet USDC from Circle's faucet (choose Solana Devnet).
§1

The progression

A multi-rail payment gateway, built one problem at a time.

1

Single Recipient

One buyer pays one recipient. The simplest possible x402 transaction.
The Hurdle
Can we move money on-chain from a browser, with no backend, using nothing but a wallet and a little JavaScript?
The Move
One HTML file. The wallet's injected provider. An SPL Token transfer of $0.01 in devnet USDC, sent straight to Solana's public devnet endpoint.
Live on devnet Try Chapter 1 →
▼
2

Choose Your Recipient

Dynamic addressing: one buyer picks from many possible recipients.
The Hurdle
Chapter 1 hardcoded the recipient. How do we scale to any number of authors without rewriting the payment flow for each?
The Move
Let the buyer choose the recipient. The payment flow is identical; one line changes: payTo = recipients[selected]. Same protocol, different destination.
Live on devnet Try Chapter 2 →
▼
3

Minimal Paywall

The full HTTP 402 handshake: pay to unlock content.
The Hurdle
Chapters 1 and 2 proved transfers work. But x402 is not just a transfer; it is a protocol for gating content. How does request, 402, pay, unlock actually feel?
The Move
Ask for an article. The gateway answers 402 with the price and where to pay. The wallet signs, the gateway verifies and settles the payment, then sets a signed access cookie. The article unlocks.
Live on devnet Try Chapter 3 →
▼
4

Multi-Chain

One framework, multiple networks: Solana, Base, Polygon, Arbitrum.
The Hurdle
Chapters 1 to 3 were all Solana. Buyers hold USDC on many chains. How do we accept payment on any of them without duplicating the stack per chain?
The Move
A reusable client module with a chain-adapter registry: one Solana adapter, one EVM adapter that covers Base, Polygon and Arbitrum by configuration, and the same server-side net-delta verification on every chain.
Explained Read Chapter 4 →
▼
5

Mobile Crypto

Crypto payments on phones, iOS and Android: three tiers from free deep links to invisible embedded wallets.
The Hurdle
Mobile browsers cannot see wallet extensions. Wallets are standalone apps, so the browser says "no wallet detected", while cards and Apple Pay work natively. Crypto has to clear the same bar.
The Move
Three tiers. Tier 1: wallet deep links. Tier 2: WalletConnect v2, so the buyer stays in the browser and the wallet app approves. Tier 3: embedded wallets: email sign-in, Face ID, done.
Explained Read Chapter 5 →
▼
6

Testing Infrastructure

Automated tests for every adapter, every attack scenario, every edge case.
The Hurdle
The framework holds security-critical verification logic. Changes shipped without automated tests broke a live build. How do we prevent regressions and prove the framework works?
The Move
A Vitest and jsdom suite: wallet detection mocks, payment verification against attack fixtures (refund tricks, wrong recipient, partial payment, wrong token, stale transaction), EVM net-delta attacks, deep links and the client lifecycle.
Explained Read Chapter 6 →
▼
7

QR Pay / Monitored Address

No wallet extension needed: scan a QR code, pay from any wallet on any device.
The Hurdle
Every chapter so far needs a browser extension. What about the buyer who will not install anything, or pays from a hardware wallet, an exchange withdrawal or a friend's phone?
The Move
The server makes a unique reference key per payment request and encodes it in a Solana Pay QR code. The buyer scans and pays normally; the server watches the chain until the payment lands.
Explained Read Chapter 7 →
▼
8

Integration Guide

Step by step: add x402 paywalls to an existing content site.
The Hurdle
Chapters 1 to 7 prove the technology works. A publisher asks: "How do I add this to my site?" They need a clear path from zero to gated content without rewriting their stack.
The Move
An end-to-end walkthrough: put the gateway beside an existing site, define paywall rules, add the client script, configure wallets and payment options, test on devnet, then go live.
Explained Read Chapter 8 →
▼
9

Agentic Commerce

Four protocols compete to power AI agent payments: x402, MPP, ACP, AP2.
The Hurdle
AI agents need to pay on their own: discover a service, agree a price, move money, use the result. Four protocols emerged in 2026, each solving a different layer. Which do we bet on?
The Move
Do not pick a winner. Map the layers (AP2 for authorization, ACP for discovery and checkout, x402 and MPP for settlement) and build a gateway that speaks more than one.
Explained Read Chapter 9 →
▼
10

Micropayment Channels

Charge a tenth of a cent per paragraph, then settle the whole session in one on-chain transaction.
The Hurdle
A Solana transaction costs a fixed network fee. At $0.001 per paragraph the fee can exceed the payment, so true sub-cent settlement one read at a time does not work.
The Move
An off-chain debit ledger. Open a channel with a prepaid cap; each read is a tiny debit against a tamper-evident voucher (monotonic sequence, replay-proof); settle once for the whole session.
Explained Read Chapter 10 →
▼
11

Trustless Payment Channels

Design spec: remove the trust from Chapter 10 with an on-chain escrow and reader-signed vouchers.
The Hurdle
Chapter 10's "open tab" trusts the reader to settle and the publisher not to over-charge. How do we keep the one-fee economics and make neither party trust the other?
The Move
An on-chain program escrows the reader's deposit; reads are reader-signed ed25519 vouchers; the publisher redeems the latest voucher on-chain, and the reader reclaims any unspent remainder after a timeout.
Design Spec Read the Spec →