x402 URL Payment Server

A standalone x402 payment server that handles URL-based micropayments using the HTTP 402 Payment Required protocol. Each URL has its own payment address and price determined by a smart contract.

Features

• Dynamic URL Payments: Each URL has its own payment configuration
• Smart Contract Integration: Fetches payment info from WebsiteRegistry contract
• x402 Protocol: Standard HTTP 402 Payment Required implementation
• Caching: 5-minute cache for smart contract calls
• Batch Processing: Handle multiple URLs in one request

Quick Start

1. Install Dependencies

npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your configuration

3. Start Server

# Development
npm run dev

# Production
npm run build
npm start

API Endpoints

Health Check

GET /api/health

Get Payment Info for URL

GET /api/payment-info/wikipedia.org

Make Payment for URL

POST /api/pay/wikipedia.org

Batch Payment Info

POST /api/batch-payment-info
Content-Type: application/json

{
  "urls": ["wikipedia.org", "nytimes.com"]
}

How It Works

1. URL Request: Client requests payment info for a URL
2. Smart Contract Query: Server checks WebsiteRegistry contract for payment requirements
3. Dynamic Configuration: If payment required, configures x402 middleware with specific price and recipient
4. HTTP 402 Response: Returns 402 Payment Required with payment headers
5. Payment Processing: x402 middleware handles payment via Coinbase CDP
6. Access Granted: Returns success response after payment completion

Payment Flow Example

# 1. Check if payment is required
curl http://localhost:3001/api/payment-info/wikipedia.org

# Response if payment required:
{
  "url": "wikipedia.org",
  "paymentRequired": true,
  "payTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "price": "$0.001000",
  "network": "base-sepolia",
  "paymentEndpoint": "/api/pay/wikipedia.org"
}

# 2. Make payment (with x402-compatible client)
curl -X POST http://localhost:3001/api/pay/wikipedia.org

# Response after successful payment:
{
  "success": true,
  "message": "Payment completed successfully!",
  "url": "wikipedia.org",
  "paidAmount": "$0.001000",
  "paidTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "network": "base-sepolia",
  "accessGranted": true
}

Smart Contract Integration

The server integrates with the WebsiteRegistry smart contract:

• Address: 0xA8832D3E571396F5F9990b0ABAC3e370e003a9A7 (Base Sepolia)
• Functions Used:
  • isWebsiteRegistered(string) - Check if URL requires payment
  • getWebsite(string) - Get payment amount and recipient address
• Domain Normalization: Automatically handles subdomains (e.g., en.wikipedia.org → wikipedia.org)

Configuration

Environment Variables

# Network (testnet)
FACILITATOR_URL=https://x402.org/facilitator
NETWORK=base-sepolia
PORT=3001

# Production (mainnet)
FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
NETWORK=base

Testing

Test with curl

# Test health
curl http://localhost:3001/api/health

# Test payment info
curl http://localhost:3001/api/payment-info/wikipedia.org

# Test batch request
curl -X POST http://localhost:3001/api/batch-payment-info \
  -H "Content-Type: application/json" \
  -d '{"urls": ["wikipedia.org", "github.com"]}'

Test with x402-compatible client

Use x402-fetch or x402-axios for automatic payment handling:

import { wrapFetchWithPayment } from "x402-fetch";

const fetchWithPayment = wrapFetchWithPayment(fetch, account);
const response = await fetchWithPayment("http://localhost:3001/api/pay/wikipedia.org", {
  method: "POST"
});

Development

Project Structure

x402/
├── server.ts              # Main server file
├── lib/
│   └── website-registry.ts # Smart contract integration
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Key Components

1. Dynamic Middleware: Payment middleware configured per URL
2. Smart Contract Client: Reads payment requirements from blockchain
3. Caching Layer: Reduces contract calls for better performance
4. Error Handling: Graceful fallbacks for network issues

Production Deployment

1. Environment: Set production environment variables
2. Network: Switch to Base mainnet
3. Facilitator: Use official Coinbase CDP facilitator
4. Caching: Consider Redis for distributed caching
5. Monitoring: Add health checks and metrics

Integration

This server can be integrated with any application that needs URL-based payments:

// Check payment requirements
const response = await fetch(`${X402_SERVER}/api/payment-info/${encodeURIComponent(url)}`);
const paymentInfo = await response.json();

if (paymentInfo.paymentRequired) {
  // Handle payment via x402 protocol
  // Client will automatically get 402 response and handle payment
}

Learn More

• x402 Protocol Documentation
• Coinbase CDP Platform
• HTTP 402 Payment Required