AgentSkillsCN

X402 Gate

X402 门

SKILL.md

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:

bash
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

javascript
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

typescript
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:

bash
# 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

javascript
// 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

bash
# 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:
    json
    {
  "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

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

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

Payment Verification

javascript
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

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

AI Services

javascript
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

javascript
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

bash
# 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:

javascript
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:
    bash
    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! 💰