AR.IO LogoAR.IO Documentation
Run a GatewayManage your Gateway

x402 Payment Setup

Learn how to set up x402 payment protocol on your AR.IO Gateway to monetize data egress. For information about what x402 is and how gateways leverage it, see our x402 Payments guide.

Release Requirement: x402 payments first became available with gateway Release 56. Ensure your gateway is running Release 56 or later to use this feature.

Prerequisites

  • Running AR.IO Gateway
  • Administrative access to your server
  • USDC wallet for receiving payments
  • API access to x402 payment facilitator

Important: x402 payments require the rate limiter to be enabled. There is no "payments only" configuration - both systems must work together.

Quick Start

Enable Rate Limiter

Configure basic rate limiting in your .env file:

# Enable rate limiter (required for x402)
ENABLE_RATE_LIMITER=true
RATE_LIMITER_TYPE=redis
RATE_LIMITER_IP_TOKENS_PER_BUCKET=100000
RATE_LIMITER_IP_REFILL_PER_SEC=20
RATE_LIMITER_RESOURCE_TOKENS_PER_BUCKET=1000000
RATE_LIMITER_RESOURCE_REFILL_PER_SEC=100

Configure x402 Payments

Add x402 configuration to your .env file:

# Enable x402 payments
ENABLE_X_402_USDC_DATA_EGRESS=true
X_402_USDC_NETWORK=base-sepolia # or base for production
X_402_USDC_WALLET_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
X_402_USDC_FACILITATOR_URL=https://x402.org/facilitator
X_402_USDC_PER_BYTE_PRICE=0.0000000001
X_402_USDC_DATA_EGRESS_MIN_PRICE=0.001
X_402_USDC_DATA_EGRESS_MAX_PRICE=1.00
X_402_RATE_LIMIT_CAPACITY_MULTIPLIER=10

Restart Gateway

Apply the configuration changes:

docker compose down
docker compose up -d

Test Configuration

Verify x402 is working by checking gateway logs:

docker compose logs -f core | grep -i "x402\|payment"

Detailed Configuration

Testnet Configuration

Perfect for development and testing with free testnet USDC:

Configure Rate Limiter

Set up memory-based rate limiting for single-node deployment:

# Rate limiter configuration
ENABLE_RATE_LIMITER=true
RATE_LIMITER_TYPE=memory
RATE_LIMITER_IP_TOKENS_PER_BUCKET=100000
RATE_LIMITER_IP_REFILL_PER_SEC=20
RATE_LIMITER_RESOURCE_TOKENS_PER_BUCKET=1000000
RATE_LIMITER_RESOURCE_REFILL_PER_SEC=100

Configure x402 Testnet

Set up x402 with Base Sepolia testnet:

# x402 testnet configuration
ENABLE_X_402_USDC_DATA_EGRESS=true
X_402_USDC_NETWORK=base-sepolia
X_402_USDC_WALLET_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
X_402_USDC_FACILITATOR_URL=https://x402.org/facilitator
X_402_USDC_PER_BYTE_PRICE=0.0000000001
X_402_USDC_DATA_EGRESS_MIN_PRICE=0.001
X_402_USDC_DATA_EGRESS_MAX_PRICE=1.00
X_402_RATE_LIMIT_CAPACITY_MULTIPLIER=10

Get Testnet USDC

Obtain free testnet USDC from a faucet:

  1. Visit Base Sepolia Faucet
  2. Connect your wallet
  3. Request testnet USDC
  4. Use the same wallet address in your configuration

Test Payment Flow

Test the payment system:

# Make multiple requests to trigger rate limiting
for i in {1..200}; do
  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/TX_ID
done

# Check for 402 Payment Required responses
curl -v http://localhost:3000/TX_ID

Mainnet Configuration

Production setup with real USDC payments:

Configure Redis Rate Limiter

Set up distributed rate limiting for multi-node deployment:

# Redis-based rate limiter
ENABLE_RATE_LIMITER=true
RATE_LIMITER_TYPE=redis
RATE_LIMITER_REDIS_ENDPOINT=redis://redis:6379
RATE_LIMITER_IP_TOKENS_PER_BUCKET=100000
RATE_LIMITER_IP_REFILL_PER_SEC=20
RATE_LIMITER_RESOURCE_TOKENS_PER_BUCKET=1000000
RATE_LIMITER_RESOURCE_REFILL_PER_SEC=100

Configure x402 Mainnet

Set up x402 with Base mainnet:

# x402 mainnet configuration
ENABLE_X_402_USDC_DATA_EGRESS=true
X_402_USDC_NETWORK=base
X_402_USDC_WALLET_ADDRESS=0xYOUR_MAINNET_WALLET
X_402_USDC_FACILITATOR_URL=https://facilitator.x402.rs
X_402_USDC_PER_BYTE_PRICE=0.0000000001
X_402_USDC_DATA_EGRESS_MIN_PRICE=0.001
X_402_USDC_DATA_EGRESS_MAX_PRICE=1.00
X_402_RATE_LIMIT_CAPACITY_MULTIPLIER=10

Set Up CDP Integration (Onramp)

Configure Coinbase Developer Platform for browser paywall with easy USDC purchases:

What are CDP keys for? These keys enable Coinbase Onramp integration in the browser paywall, allowing users to easily purchase USDC without leaving your gateway. They are optional for testnet but required for mainnet when using Coinbase facilitators.

Security Note:

  • X_402_CDP_CLIENT_KEY is PUBLIC (safe for client-side use)
  • CDP_API_KEY_ID and CDP_API_KEY_SECRET_FILE are SENSITIVE SECRETS
  • CDP keys are for Onramp integration, NOT facilitator authentication
# CDP configuration for Coinbase Onramp (browser paywall)
CDP_API_KEY_ID=YOUR_API_KEY_ID
CDP_API_KEY_SECRET_FILE=/app/secrets/cdp_secret_key
X_402_CDP_CLIENT_KEY=YOUR_PUBLIC_CLIENT_KEY

Create the secret file:

mkdir -p ./secrets
chmod 700 ./secrets
echo "YOUR_CDP_SECRET_KEY" > ./secrets/cdp_secret_key
chmod 600 ./secrets/cdp_secret_key

Note: If both CDP_API_KEY_SECRET_FILE and CDP_API_KEY_SECRET are set, the file version takes precedence.

Configure Redis Persistence

Ensure paid tokens persist across restarts:

# Redis persistence for paid tokens
EXTRA_REDIS_FLAGS=--save 300 10 --appendonly yes --appendfsync everysec

Advanced Setup Options

Customize your x402 implementation:

Configure Paywall Customization

Customize the payment interface:

# Paywall customization
X_402_APP_NAME=My AR.IO Gateway
X_402_APP_LOGO=https://example.com/logo.png

Set Up Chunk Pricing

Configure fixed-size pricing for chunk requests:

# Chunk pricing configuration
CHUNK_GET_BASE64_SIZE_BYTES=368640

Configure Allowlists

Exempt specific IPs or ArNS names from rate limiting:

# IP/CIDR allowlist (comma-separated)
RATE_LIMITER_IPS_AND_CIDRS_ALLOWLIST=192.168.1.100,10.0.0.50

# ArNS name allowlist (comma-separated)
RATE_LIMITER_ARNS_ALLOWLIST=trusted-app,premium-service

Set Up Monitoring

Configure monitoring and metrics:

# Enable detailed logging
LOG_LEVEL=debug

# Monitor payment metrics
# Access metrics at: http://localhost:3000/ar-io/__gateway_metrics

Environment Variables Reference

Required Variables

VariableDescriptionExample
ENABLE_RATE_LIMITEREnable rate limiting (required for x402)true
ENABLE_X_402_USDC_DATA_EGRESSEnable x402 paymentstrue
X_402_USDC_NETWORKBase network (base-sepolia or base)base-sepolia
X_402_USDC_WALLET_ADDRESSYour USDC wallet address0x742d35Cc...
X_402_USDC_FACILITATOR_URLPayment facilitator URLhttps://x402.org/facilitator

Pricing Configuration

VariableDescriptionDefault
X_402_USDC_PER_BYTE_PRICEPrice per byte in USDC0.0000000001
X_402_USDC_DATA_EGRESS_MIN_PRICEMinimum payment amount0.001
X_402_USDC_DATA_EGRESS_MAX_PRICEMaximum payment amount1.00
X_402_RATE_LIMIT_CAPACITY_MULTIPLIERPaid token multiplier10

Rate Limiter Configuration

VariableDescriptionDefault
RATE_LIMITER_TYPERate limiter type (memory or redis)redis (docker-compose), memory (standalone)
RATE_LIMITER_IP_TOKENS_PER_BUCKETIP bucket size100000
RATE_LIMITER_IP_REFILL_PER_SECIP refill rate20
RATE_LIMITER_RESOURCE_TOKENS_PER_BUCKETResource bucket size1000000
RATE_LIMITER_RESOURCE_REFILL_PER_SECResource refill rate100

Testing Your Configuration

Verify Rate Limiting

Test that rate limiting is working:

# Make requests to trigger rate limits
for i in {1..150}; do
  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/TX_ID
done

# Should see 402 responses after rate limit is exceeded

Test Payment Response

Check the 402 payment response:

# Get detailed payment information
curl -v http://localhost:3000/TX_ID

# Look for X-Payment header in response

Monitor Gateway Logs

Watch for payment-related activity:

# Monitor x402 and payment logs
docker compose logs -f core | grep -i "x402\|payment\|rate limit"

Check Metrics

View payment and rate limiting metrics:

# Access gateway metrics
curl -s http://localhost:3000/ar-io/__gateway_metrics | grep rate_limit

# Check token consumption
curl -s http://localhost:3000/ar-io/__gateway_metrics | grep tokens_consumed

Troubleshooting

Common Issues

Rate Limiter Not Working: Ensure ENABLE_RATE_LIMITER=true is set and gateway has been restarted.

No 402 Responses: Check that rate limits are being exceeded and x402 is properly configured.

Payment Verification Fails: Verify wallet address and facilitator URL are correct.

Debug Steps

  1. Check Configuration:

    # Verify environment variables
docker compose exec core env | grep -E "RATE_LIMITER|X_402"

  2. Monitor Logs:

    # Watch for errors
docker compose logs -f core | grep -i error

  3. Test Rate Limits:

    # Check if rate limiting is active
curl -s http://localhost:3000/ar-io/__gateway_metrics | grep rate_limit

  4. Verify Network Connectivity:

    # Test facilitator connectivity
curl -I https://x402.org/facilitator

Next Steps

Once x402 payments are configured:

Monitor Performance

Use Grafana to track payment metrics, rate limiting statistics, and gateway performance analytics.

Optimize Settings

Adjust rate limits and pricing based on usage patterns, and configure gateway filters for optimal performance.

Scale Infrastructure

Consider Redis for distributed deployments and review environment variables for advanced configuration options.

Customize Experience

Configure paywall branding, messaging, and customize your gateway's apex domain for a professional appearance.

How is this guide?

Setting Apex Domain Content

Complete guide to configuring your AR.IO Gateway to serve custom content from the apex domain

Troubleshooting

Comprehensive troubleshooting guide and FAQ for AR.IO Gateway operators, including common issues, failed epoch guidance, and frequently asked questions.

On this page

PrerequisitesQuick StartEnable Rate LimiterConfigure x402 PaymentsRestart GatewayTest ConfigurationDetailed ConfigurationTestnet ConfigurationConfigure Rate LimiterConfigure x402 TestnetGet Testnet USDCTest Payment FlowMainnet ConfigurationConfigure Redis Rate LimiterConfigure x402 MainnetSet Up CDP Integration (Onramp)Configure Redis PersistenceAdvanced Setup OptionsConfigure Paywall CustomizationSet Up Chunk PricingConfigure AllowlistsSet Up MonitoringEnvironment Variables ReferenceRequired VariablesPricing ConfigurationRate Limiter ConfigurationTesting Your ConfigurationVerify Rate LimitingTest Payment ResponseMonitor Gateway LogsCheck MetricsTroubleshootingCommon IssuesDebug StepsNext Steps