x402 Content Gate - OpenClaw Skill

Monetize your AI agent's API endpoints with USDC micropayments on Base

This skill provides the x402 Content Gate middleware and utilities for implementing HTTP 402 Payment Required responses with USDC payments on Base blockchain.

🎯 What It Does

• Protects API endpoints behind micropayments
• Uses x402 protocol (HTTP 402 + USDC on Base)
• Zero-config setup with sensible defaults
• Works with any Express app via middleware
• Includes demo server for testing

📦 Installation

The skill includes both the npm package source and OpenClaw integration.

As npm package:

npm install @axiombotx/x402-gate

As OpenClaw skill:

This directory is the skill - copy or link it into your OpenClaw skills folder.

🚀 Usage

Quick Start

import express from 'express';
import { x402Gate } from '@axiombotx/x402-gate';

const app = express();

// Add payment gate
app.use(x402Gate({
  wallet: '0x523Eff3dB03938eaa31a5a6FBd41E3B9d23edde5',
  routes: {
    'GET /api/data': { price: '$0.01', description: 'Data access' },
    'POST /api/ai': { price: '$0.10', description: 'AI generation' },
  }
}));

// Your monetized endpoints
app.get('/api/data', (req, res) => {
  res.json({ valuable: 'data' });
});

app.listen(3000);

Configuration

interface X402GateConfig {
  wallet: string;              // Where USDC payments go
  routes: Record<string, {     // Route configurations
    price: string | number;    // '$0.01' or USDC units
    description: string;       // What the endpoint provides
    facilitatorUrl?: string;   // Optional custom facilitator
  }>;
  chainId?: number;           // Default: 8453 (Base)
  usdcAddress?: string;       // Default: Base USDC
  debug?: boolean;            // Enable debug logging
}

🎮 Demo

Run the included demo to see it in action:

# Start demo server (runs on port 3000)
npm run demo

# Test the endpoints
npm run test-client

# Or manually test
curl http://localhost:3000/api/weather

The demo includes:

• Free endpoints: / and /health
• Paid endpoints: /api/weather ($0.01), /api/crypto ($0.05), /api/generate ($0.10)

🔧 OpenClaw Integration

Agent Usage

// In your agent's API setup
const { x402Gate } = require('./skills/x402-gate/dist');

// Configure payment for your agent's services
app.use(x402Gate({
  wallet: process.env.AGENT_WALLET,
  debug: process.env.NODE_ENV !== 'production',
  routes: {
    'GET /agent/analyze': {
      price: '$0.05',
      description: 'AI content analysis'
    },
    'POST /agent/generate': {
      price: '$0.20',
      description: 'AI content generation'
    },
    'GET /agent/data/*': {
      price: '$0.02',
      description: 'Dynamic data endpoints'
    }
  }
}));

Environment Variables

# Set in your agent's environment
AGENT_WALLET=0x523Eff3dB03938eaa31a5a6FBd41E3B9d23edde5
NODE_ENV=production
PORT=3000

🌊 Payment Flow

1. Client requests protected endpoint without payment
2. Server returns 402 with payment requirements:

   {
     "error": "Payment Required",
     "payment": {
       "amount": "10000",
       "currency": "USDC", 
       "recipient": "0x523Eff...",
       "facilitator": "https://x402.org/facilitator",
       "chainId": 8453
     }
   }
   

3. Client pays using x402-compatible wallet/library
4. Server verifies payment and returns data

🛠 Utilities

Price Conversion

import { parsePriceToUsdc, formatUsdcToPrice } from '@axiombotx/x402-gate';

// Convert prices
const usdcUnits = parsePriceToUsdc('$0.01');  // '10000'
const priceDisplay = formatUsdcToPrice(10000); // '$0.01'

Payment Verification

import { verifyPayment } from '@axiombotx/x402-gate';

const result = await verifyPayment(
  paymentHash,
  {
    amount: '10000',
    currency: 'USDC',
    recipient: '0x523Eff...',
    facilitator: 'https://x402.org/facilitator',
    description: 'API access'
  }
);

if (result.valid) {
  // Payment confirmed, serve content
}

🎯 Use Cases

Data APIs

routes: {
  'GET /api/prices': { price: '$0.01', description: 'Market prices' },
  'GET /api/news': { price: '$0.02', description: 'Curated news' }
}

AI Services

routes: {
  'POST /ai/summarize': { price: '$0.05', description: 'Text summary' },
  'POST /ai/translate': { price: '$0.03', description: 'Translation' },
  'POST /ai/analyze': { price: '$0.10', description: 'Deep analysis' }
}

Premium Features

routes: {
  'POST /premium/forecast': { price: '$0.25', description: 'AI forecasts' },
  'GET /premium/signals': { price: '$0.50', description: 'Trading signals' }
}

🔒 Security Notes

• Never store private keys in your config
• Only wallet addresses are needed for receiving payments
• All payments verified via x402 facilitator before serving content
• Use HTTPS in production
• Consider rate limiting for additional protection

🧪 Testing

# Build the TypeScript
npm run build

# Start demo server
npm run demo

# Test with client
npm run test-client

# Manual testing
curl http://localhost:3000/api/weather
# Returns 402 Payment Required

curl http://localhost:3000/health  
# Returns data (no payment required)

🔗 Client Libraries

Use these libraries to consume x402-protected endpoints:

• @x402/fetch - Auto-paying fetch wrapper
• @x402/core - Core x402 utilities
• Browser extensions - Wallet integrations for seamless UX

📚 Examples

See the examples/ directory for:

• express-api.ts - Complete AI agent API setup
• Integration patterns for different use cases
• Error handling best practices

🐛 Troubleshooting

Common Issues

1. "Payment verification failed"

   • Check facilitator URL is correct
   • Ensure wallet address matches payment recipient
   • Verify payment was actually sent

2. "Invalid wallet address"

   • Wallet must be valid Ethereum address starting with 0x
   • Use checksummed addresses when possible

3. "Module not found"

   • Run npm run build to compile TypeScript
   • Check import paths are correct

Debug Mode

Enable debug logging to see payment flow:

app.use(x402Gate({
  wallet: '0x...',
  debug: true,  // Shows payment attempts and verification
  routes: { ... }
}));

🚀 Production Deployment

1. Build the package: npm run build
2. Set environment variables:

   AGENT_WALLET=0xYourWallet
   NODE_ENV=production
   PORT=8080
   

3. Use HTTPS for secure payments
4. Monitor payments via your wallet or Base block explorer
5. Consider caching verification results for performance

Ready to monetize your agent? Drop the middleware in and start earning USDC! 💰