AR.IO x402 Monorepo

A practical implementation and testing environment for AR.IO Gateway integration with the x402 payment protocol for monetized data access.

🎯 Project Overview

This monorepo provides:

AR.IO Gateway (using :latest Docker image) running in delegated mode
x402 Payment Protocol examples and testing tools
x402 stream - Production-ready Next.js video streaming app with x402 payments
Example Applications demonstrating real-world usage

🚀 Quick Start

Prerequisites

Docker & Docker Compose
Node.js 18+
pnpm 9+
AR.IO Wallet address
Observer Wallet with JWK keyfile

Installation

Clone and Install

git clone <your-repo-url> ar-io-x402
cd ar-io-x402
pnpm install

Configure Gateway
```
pnpm gateway:setup
```
The setup wizard will:
- ✅ Verify Docker and docker-compose are running
- ✅ Create .env from template
- ✅ Validate wallet address formats (Arweave & EVM)
- ✅ Check observer wallet keyfile exists and is valid JSON
- ✅ Pull latest gateway Docker image

Configure Wallets

Edit services/ar-io-gateway/.env:

# Required: Arweave wallets (43-character base64 addresses)
AR_IO_WALLET=your-ar-io-wallet-address
OBSERVER_WALLET=your-observer-wallet-address

# Optional: For x402 payments (42-character hex address with 0x prefix)
X_402_USDC_WALLET_ADDRESS=0xYourEVMWalletAddress

Add observer wallet keyfile:

cp your-wallet.json services/ar-io-gateway/wallets/<observer-address>.json

The setup script will validate all formats automatically.

Start Gateway
```
pnpm gateway:up
```
Verify Installation
```
pnpm gateway:health
```

📋 Available Commands

Gateway Management

pnpm gateway:up       # Start gateway
pnpm gateway:down     # Stop gateway
pnpm gateway:logs     # View logs
pnpm gateway:restart  # Restart gateway
pnpm gateway:setup    # Initial setup wizard
pnpm gateway:health   # Health check

Development

pnpm dev              # Start all services (via Turborepo)
pnpm build            # Build all packages
pnpm test             # Run tests
pnpm lint             # Lint all packages

🏗️ Architecture

Delegated Gateway Mode

This project uses delegated mode for the AR.IO Gateway:

Client Request
    ↓
Local Gateway (localhost:4000)
    ├─ Rate Limiting
    ├─ x402 Payment Validation
    └─ Token Consumption
         ↓
Trusted Gateway (arweave.net)
    └─ Data Fetching
         ↓
Arweave Network

Benefits:

✅ No blockchain syncing required
✅ Fast startup (seconds, not hours)
✅ Minimal disk space (~100MB vs ~3TB)
✅ Real Arweave data via proxy
✅ Full x402 functionality

Monorepo Structure

ar-io-x402/
├── services/
│   └── ar-io-gateway/      # Gateway with x402 support
├── examples/
│   └── arstream/           # x402 stream - Video streaming with payments
├── packages/               # Shared libraries (coming soon)
└── scripts/                # Automation scripts

🔌 Gateway Endpoints

Data Access (Monetized)

# Fetch transaction data
curl http://localhost:4000/:txid

# Fetch chunk data (x402 enabled)
curl http://localhost:4000/chunk/:offset

# Fetch raw transaction
curl http://localhost:4000/raw/:txid

Configuration Discovery

# Gateway info (includes x402 config)
curl http://localhost:4000/ar-io/info

# Health check
curl http://localhost:4000/ar-io/healthcheck

GraphQL

# GraphQL queries (proxied to arweave.net)
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ transactions { edges { node { id } } } }"}'

🎬 x402 stream - Video Streaming Example

A production-ready Next.js application demonstrating decentralized video streaming with x402 micropayments.

Features

Stream video content from AR.IO Network's permanent cloud
Automatic rate limiting with free tier access
x402 payment modal for paid tier access
USDC payments on Base Sepolia testnet
MetaMask wallet integration

Quick Start

# Start the gateway first
pnpm gateway:up

# Install and run x402 stream
cd examples/arstream
pnpm install
pnpm dev

# Open http://localhost:3000

Full Documentation

See examples/arstream/README.md for complete setup, testing instructions, and architecture details.

💰 x402 Payment Protocol

Overview

x402 enables monetized data access using USDC payment tokens:

Regular Tokens: Free tier with rate limits
Paid Tokens: USDC-based tokens for overflow capacity
Token Priority: Regular → Paid

Payment Flow

1. Client requests data with x402 header
2. Gateway validates payment token
3. Rate limiter checks token availability
4. Data fetched from trusted gateway
5. Token consumption recorded
6. Response sent to client

Configuration

Rate limiting is required for x402:

ENABLE_RATE_LIMITER=true
ENABLE_X_402_USDC_DATA_EGRESS=true

📖 Documentation

Gateway Service README - Detailed gateway documentation
Claude.md - Project plan and architecture decisions
AR.IO Docs - Official AR.IO documentation
Gateway Node Repo

🧪 Testing

Test Data Access

# Known transaction ID
curl http://localhost:4000/4jBV3ofWh41KhuTs2pFvj-KBZWUkbrbCYlJH0vLA6LM

Test x402 Configuration

# Check rate limiter config
curl http://localhost:4000/ar-io/info | jq '.rateLimiter'

Test Chunk Endpoint

# HEAD request (no token consumption)
curl -I http://localhost:4000/chunk/0

🛠️ Development Workflow

Adding New Examples

Create workspace in examples/:

mkdir examples/my-example
cd examples/my-example
pnpm init

Add to pnpm-workspace.yaml:
```
packages:
  - "examples/my-example"
```
Update turbo.json if needed
Add convenience script to root package.json

🐛 Troubleshooting

Gateway Won't Start

# Check Docker
docker ps

# View logs
pnpm gateway:logs

# Check .env configuration
cat services/ar-io-gateway/.env

Rate Limiting Not Working

Verify ENABLE_RATE_LIMITER=true in .env
Check /ar-io/info endpoint
Review gateway logs

Observer Wallet Issues

Verify keyfile exists: ls services/ar-io-gateway/wallets/
Check keyfile format (JWK JSON)
Ensure filename matches wallet address

🗺️ Roadmap

✅ Phase 1: Foundation (Completed)

Turborepo monorepo setup
AR.IO Gateway in delegated mode
x402 configuration
Basic documentation
x402 stream example application
MetaMask wallet integration
Payment modal and UX

🚧 Phase 2: Enhanced Examples (Next)

Additional video content and demo files
Payment history and analytics
Rate limit visualization
Multi-format content support (audio, documents)

🔮 Phase 3: Client Libraries & Tools

Reusable TypeScript x402 client library
Python x402 client
CLI tools for x402 testing
Multi-gateway load balancing
Performance benchmarks

📚 Resources

🔒 Security

⚠️ Never commit .env files with real wallet addresses
⚠️ Never commit wallet keyfiles
⚠️ Keep wallets/ and data/ in .gitignore
✅ Use read-only Docker volume mounts for wallets
✅ Regularly update to latest gateway release

📄 License

[Your License Here]

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

💬 Support

Open an issue for bug reports
Discussions for questions and ideas
AR.IO Discord for community support