x402 Payments

ar.io gateways support the x402 payment protocol, so clients can pay for data access in cryptocurrency. Operators can recover infrastructure costs, and users who need more bandwidth can pay for it.

What is x402?

x402 is an open-source payment protocol from Coinbase. It uses the HTTP 402 "Payment Required" status code to let clients pay for web APIs in cryptocurrency, without accounts or card payments:

Key Features

Zero protocol fees: No intermediaries or payment processing costs
Fast settlement: Payments settle in approximately 2 seconds
Minimal integration: Simple HTTP status codes and headers
Privacy-focused: No account creation or personal information required
Chain-agnostic: Works with multiple blockchain networks
Token-agnostic: Supports various cryptocurrencies

How x402 Works

The x402 protocol uses an HTTP flow:

The client never talks to the facilitator. The gateway verifies and settles the payment itself, and returns the settlement receipt to the client in the X-Payment-Response header.

ar.io gateways implement x402 with USDC (USD Coin) on the Base blockchain, priced per byte of data served. It works as part of the gateway's rate limiter: a client pays only once it has used its free allowance.

Payment Flow in ar.io Gateways

Free Tier Access: Users consume regular tokens from their rate limit buckets
Rate Limit Exceeded: When limits are reached, gateway sends 402 Payment Required response
Payment Processing: Users can make USDC payments to continue access
Premium Access: Payments add paid tokens with configurable multiplier (default 10x capacity)
Priority Consumption: Regular tokens consumed first, then paid tokens
Resource Bypass: Paid requests bypass per-resource limits (only IP limits apply)

Browser Paywall & Onramp Integration

For mainnet deployments, gateways can integrate Coinbase Onramp to enable easy USDC purchases directly in the browser paywall. This requires Coinbase Developer Platform (CDP) API keys, which are separate from payment facilitator authentication. With Onramp, users can buy USDC without leaving the gateway's paywall page.

Note: CDP keys are optional for testnet but required for mainnet when using Coinbase facilitators. These keys enable the browser-based purchasing experience and are not related to payment verification or settlement.

Network Options

ar.io gateways support two Base blockchain networks for x402 payments:

Feature	Base Sepolia (Testnet)	Base (Mainnet)
USDC	Free testnet USDC (faucet)	Real USDC (costs money)
CDP API Key	Not required	Required for official facilitator
Default Facilitator	https://x402.org/facilitator	Must configure
Use Case	Development, testing	Production monetization
Configuration	`X_402_USDC_NETWORK=base-sepolia`	`X_402_USDC_NETWORK=base`

Rate Limited Endpoints

The x402 payment system applies to data egress endpoints where gateways serve actual content:

Data Serving Endpoints

Transaction/Data Item requests: /:txid and /:txid/path
Raw data requests: /raw/:txid
ArNS resolved content: All requests resolved through ArNS names
Farcaster frames: /local/farcaster/frame/:txid
Chunk requests: GET /chunk/:offset and GET /chunk/:offset/data (fixed size pricing)
Index Sharing byte routes: band files by name, by digest, and the WebSeed under /ar-io/indexes. The publication document at /ar-io/indexes and the .torrent files are free

Not Rate Limited

GraphQL queries (/graphql)
Chunk POST requests (POST /chunk)
Administrative and informational endpoints under /ar-io/*, except the Index Sharing byte routes above

Benefits for Gateway Operators

Sustainable Infrastructure

Cost Recovery: Monetize data egress to cover operational expenses
Premium Services: Offer higher bandwidth tiers for power users
Flexible Pricing: Per-byte pricing scales with actual usage
Revenue Generation: Create sustainable business models

Traffic Management

Fair Access: Free tier for casual users with reasonable limits
Premium Access: Power users can pay for additional capacity
DDoS Protection: Rate limiting prevents abuse while allowing legitimate paid access
Resource Optimization: Paid requests bypass resource limits for better performance