x402 Starter Kit

Build payment-gated APIs and content services using the x402 protocol on Avalanche.

The x402 Starter Kit is a production-ready Next.js template that demonstrates how to build payment-gated APIs and content services using the x402 protocol on Avalanche C-Chain.

View on GitHub →

What Is x402?

x402 is an open payment protocol that uses HTTP status code 402 "Payment Required" to enable seamless cryptocurrency payments for web content and APIs. Learn more at x402.org.

Key Benefits

Direct Payments: Accept cryptocurrency payments without third-party payment processors
No Accounts: No user registration or authentication required
Blockchain-Verified: Payments are verified directly on the Avalanche blockchain
Simple Integration: Add payment gates to any Next.js route with middleware
Flexible Pricing: Set different prices for different content in USD

Payment Flow

User requests protected content
Server responds with 402 Payment Required
User makes payment via wallet
User proves payment with transaction signature
Server verifies payment on Avalanche blockchain
Access is granted to protected content

Why Avalanche + x402?

Aspect	Benefit
Sub-second finality	Instant payment verification
Low gas fees (~$0.01)	Makes micropayments ($0.01+) economically viable
EVM compatible	Use familiar Ethereum tooling and Solidity contracts
4,500+ TPS	High throughput for serving many concurrent users
Established network	Production-proven since 2020 with active ecosystem

Features

Payment Infrastructure

x402 Protocol Integration: HTTP 402 status code with blockchain verification
Micropayment Support: Enable sub-dollar transactions with low overhead
USD-Denominated Pricing: Automatic conversion to AVAX/USDC at current rates
EIP-712 Signatures: Gasless authorization using transferWithAuthorization
Network Support: Both Mainnet (43114) and Fuji Testnet (43113)

Demo Endpoints

/api/premium-data - Market insights ($0.01 USDC)
/api/ai-analysis - AI-powered market analysis ($0.25 USDC)
/content/[type] - Payment-gated content pages

Developer Experience

Wallet Connection: Reown (WalletConnect v3) integration
Modern UI: Tailwind CSS 4 with animated backgrounds
Type Safety: Full TypeScript support
AI Integration: Optional OpenRouter support for AI features

Getting Started

Clone the Repository

git clone https://github.com/tomi204/x402-starter-kit.git
cd x402-starter-kit/starters/nextjs

Install Dependencies

npm install
# or
yarn install
# or
pnpm install

Get Reown Project ID

You'll need a free Reown Project ID for wallet connection:

Visit cloud.reown.com
Sign up (free account)
Create a new project
Copy the Project ID

Configure Environment

Copy the example environment file:

cp .env.example .env.local

Edit .env.local with your settings:

# Your EVM wallet address (where payments go)
NEXT_PUBLIC_RECEIVER_ADDRESS=0x1234567890123456789012345678901234567890

# Network: avalanche-fuji (testnet) or avalanche (mainnet)
NEXT_PUBLIC_NETWORK=avalanche-fuji

# Facilitator service for payment verification
NEXT_PUBLIC_FACILITATOR_URL=https://facilitator.ultravioletadao.xyz

# Your Reown Project ID (REQUIRED)
NEXT_PUBLIC_REOWN_PROJECT_ID=your_reown_project_id_here

# Optional: OpenRouter API key for real AI features
OPENROUTER_API_KEY=sk-or-v1-your_api_key_here

Required Variables:

Variable	Purpose	Where to Get
`NEXT_PUBLIC_RECEIVER_ADDRESS`	Your wallet address that receives payments	Your EVM wallet (MetaMask, Core, etc.)
`NEXT_PUBLIC_NETWORK`	Blockchain network	Use `avalanche-fuji` for testing
`NEXT_PUBLIC_FACILITATOR_URL`	Payment verification service	Use provided URL
`NEXT_PUBLIC_REOWN_PROJECT_ID`	Wallet connection	cloud.reown.com

Run Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

Visit http://localhost:3000 to see your app running.

Test the Payment Flow

Click on "Access Cheap Content" or "Access Expensive Content"
Connect your wallet when prompted
You'll see a payment modal
Complete the payment (on testnet, make sure you have test AVAX)
Access is granted and you'll see the protected content

Make sure you're using Avalanche Fuji testnet. You can get test AVAX from the Fuji Faucet.

Project Structure

starters/nextjs/
├── app/
│   ├── api/
│   │   ├── ai-analysis/route.ts        # AI analysis endpoint ($0.25)
│   │   ├── premium-data/route.ts       # Market data endpoint ($0.01)
│   │   └── test-payment/route.ts       # Test endpoint
│   ├── content/
│   │   └── [type]/page.tsx             # Dynamic content pages
│   ├── page.tsx                        # Landing page
│   └── layout.tsx                      # Root layout with providers
│
├── components/ui/                      # React UI components
│
├── lib/
│   ├── x402-middleware.ts              # Server-side payment verification
│   ├── x402-client.ts                  # Client-side payment handling
│   ├── facilitator.ts                  # Facilitator API helpers
│   ├── ai-service.ts                   # AI integration (OpenRouter)
│   ├── config.ts                       # Wallet configuration
│   └── context.tsx                     # React providers
│
├── middleware.ts                       # Next.js middleware (payment protection)
├── .env.example                        # Environment template
└── package.json                        # Dependencies

How It Works

Payment Verification Flow

The template uses Next.js middleware to intercept requests and verify payments:

// middleware.ts defines protected routes
const protectedRoutes = {
  "/api/premium-data": {
    maxAmountRequired: "10000", // 0.01 USDC (6 decimals)
    description: "Premium data access"
  },
  "/api/ai-analysis": {
    maxAmountRequired: "250000", // 0.25 USDC
    description: "AI-powered market analysis"
  }
}

The payment verification follows this flow:

User Request → Middleware Checks Payment
    ↓
No Payment? → Return 402 Payment Required
    ↓
User Signs Payment → Retry Request with Payment Header
    ↓
Middleware Verifies with Facilitator → Check Blockchain
    ↓
Valid Payment? → Proceed to API Route → Return Content

Core Components

The template consists of three main components:

Middleware (middleware.ts):

Intercepts requests to protected routes
Returns 402 if no valid payment exists
Verifies payments via facilitator

x402 Client (lib/x402-client.ts):

Handles client-side payment flow
Creates EIP-712 signatures
Retries requests with payment proof

x402 Middleware Library (lib/x402-middleware.ts):

Payment verification logic
Facilitator communication
Payment settlement

Customization

Add New Protected Route

Edit middleware.ts to add more protected endpoints:

const protectedRoutes = {
  // ... existing routes
  "/api/premium-forecast": {
    maxAmountRequired: "500000", // $0.50 USDC
    description: "Premium 30-day price forecast"
  }
}

Change Pricing

Amounts are in USDC with 6 decimals:

"10000"    // $0.01
"500000"   // $0.50
"1000000"  // $1.00

Add AI Features

To enable real AI-powered analysis:

Get an API key from OpenRouter
Add to .env.local:

OPENROUTER_API_KEY=sk-or-v1-your_api_key_here

The template will automatically use real AI instead of mock data

You can change the AI model in app/api/ai-analysis/route.ts:

const aiService = new AIService({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'anthropic/claude-3.5-sonnet', // or 'openai/gpt-4o'
  temperature: 0.7,
  maxTokens: 800,
});