The Complete Guide to x402 Protocol: The Future of Internet-Native Payments

When the internet was born, the designers of the HTTP protocol reserved a special status code: 402 Payment Required. For over thirty years, this status code remained “reserved for future use,” waiting for a technology that could make internet-native payments a reality.

In 2024, Coinbase and Cloudflare launched the x402 protocol, finally bringing this dormant status code to life.

What is x402?

x402 is an open payment protocol that allows servers to request payment through standard HTTP responses, and clients can instantly complete payments using cryptocurrency (primarily USDC stablecoins).

Key Features:

• Zero Fees: The protocol itself charges no fees
• Instant Settlement: Funds arrive in your wallet in 2 seconds, not T+2
• Self-Custody: Funds go directly to your wallet, no third-party custody
• Open Standard: Anyone can implement and use it

Why Do We Need x402?

Traditional online payments have many problems:

Issue	Traditional Payments	x402
Fees	2.9% + $0.30	0%
Settlement Time	T+2 (2 business days)	2 seconds
Chargeback Risk	Yes	No (blockchain transactions are irreversible)
Account Risk	Can be frozen	Self-custody, full control
Cross-border	Complex, expensive	Global, borderless

For developers, x402 has another huge advantage: one-line integration.

How Does x402 Work?

The x402 workflow is straightforward:

Step 1: Client Requests a Resource

GET /api/premium-content HTTP/1.1
Host: example.com

Step 2: Server Returns 402

If the resource requires payment, the server returns HTTP 402 status code with payment requirements:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmountRequired": "1000000",
    "payTo": "0xYourWalletAddress",
    "resource": "https://example.com/api/premium-content"
  }],
  "x402Version": 1
}

Step 3: Client Signs and Resends Request

The client signs the payment using a crypto wallet and includes payment info in the request header:

GET /api/premium-content HTTP/1.1
Host: example.com
X-PAYMENT: eyJwYXlsb2FkIjp7...base64 encoded payment info...}

Step 4: Server Verifies and Returns Content

The server verifies payment validity through a Facilitator, then returns the requested content:

HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVl...}
Content-Type: application/json

{
  "data": "This is your purchased content"
}

The entire flow completes in seconds with a smooth user experience.

Core Concepts

Payment Requirements

The payment requirements returned by the server include:

• scheme: Payment scheme, currently mainly exact (exact amount)
• network: Blockchain network, e.g., base, base-sepolia, polygon
• asset: Token contract address (usually USDC)
• maxAmountRequired: Amount to pay (in smallest units)
• payTo: Recipient wallet address

Facilitator

A Facilitator is an intermediary service responsible for:

1. Verifying payment signatures
2. Settling transactions on the blockchain
3. Confirming payment completion

The default public Facilitator is https://x402.org/facilitator, but you can also self-host.

Paywall

When a browser accesses a resource requiring payment, x402 returns an elegant payment page that guides users to connect their wallet and complete payment. This page is auto-generated but can be customized.

Supported Networks

x402 currently supports the following blockchain networks:

EVM Networks

Network	Network ID	Type
Base	base	Mainnet
Base Sepolia	base-sepolia	Testnet
Polygon	polygon	Mainnet
Polygon Amoy	polygon-amoy	Testnet
Avalanche	avalanche	Mainnet
Abstract	abstract	Mainnet
Sei	sei	Mainnet

Solana Networks

Network	Network ID	Type
Solana	solana	Mainnet
Solana Devnet	solana-devnet	Testnet

Quick Start

Using Hono framework as an example, you can add payment functionality with just a few lines of code:

npm install 402ok-hono

import { Hono } from "hono";
import { paymentMiddleware } from "402ok-hono";

const app = new Hono();

// Your receiving wallet address
const PAY_TO = "0xYourWalletAddress";

// Configure paid endpoints
const paidRoutes = {
  "GET /api/premium": {
    price: "$0.01",           // Price
    network: "base-sepolia",  // Network
    config: {
      description: "Access premium content",
    },
  },
};

// Apply payment middleware
app.use("/api/premium", paymentMiddleware(PAY_TO, paidRoutes));

// Premium content
app.get("/api/premium", (c) => {
  return c.json({ message: "Welcome to premium content!" });
});

That’s it! When users access /api/premium:

1. Without payment, returns 402 and payment page
2. User pays via wallet
3. After successful payment, returns content

Use Cases

x402 is particularly suitable for:

1. API Monetization

Add per-request pricing to your AI interfaces and data APIs.

2. Digital Goods

Sell e-books, courses, software licenses, and other digital content.

3. E-commerce Payments

Add cryptocurrency payment options to independent stores, especially suitable for cross-border e-commerce.

4. Content Payments

Single-purchase access to blog posts, videos, music, and other content.

5. Tips and Donations

Receive USDC tips for open source projects and creators.

Comparison with Other Solutions

Feature	x402	Stripe	Coinbase Commerce
Fees	0%	2.9% + $0.30	1%
Settlement	Instant	T+2	Instant
Custody	Self-custody	Custodial	Custodial
Integration	Simple	Medium	Simple
Currency	USDC	Fiat	Multiple cryptos
Open Source	Yes	No	No

Next Steps

Now that you understand the basics of x402, you can continue learning:

• Want to get started quickly? → 5-Minute Express + x402 Guide
• Want to understand the business value? → Say Goodbye to Payment Fees: How x402 Changes Online Payments
• Want to see e-commerce examples? → E-commerce Payments: User System + Orders + x402

Resources

• x402 Official Website
• x402 GitHub Repository
• Coinbase Developer Documentation
• x402 Whitepaper

---

x402 is changing how internet payments work. Join this revolution and embrace the future of internet-native payments.