x402 Payments

AR.IO gateways integrate the x402 payment protocol to enable frictionless cryptocurrency payments for data access. This creates a sustainable monetization model that allows gateways to cover infrastructure costs while providing premium access tiers for users who need higher bandwidth or priority service.

What is x402?

x402 is an open-source payment protocol built by Coinbase that leverages the HTTP 402 "Payment Required" status code to enable frictionless cryptocurrency payments for web APIs. The protocol is designed to eliminate traditional friction points in web 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 a simple HTTP-based flow:

AR.IO Gateway Integration

AR.IO gateways implement x402 using USDC (USD Coin) on the Base blockchain to monetize data egress with per-byte pricing. This integration works seamlessly with the gateway's rate limiting system to provide a complete traffic management and monetization solution.

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. The Onramp integration allows users to purchase USDC without leaving the gateway interface, creating a seamless payment experience.

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 (uses fixed size pricing)

Not Rate Limited

GraphQL queries (/graphql)
Chunk POST requests (POST /chunk)
Administrative endpoints (/ar-io/*)

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