x402-easy-start 🚀

The easiest way to add x402 blockchain payments to any API endpoint.

One line of code. Instant payments. No complexity.

💡 What is this?

x402-easy-start makes it ridiculously simple to monetize your APIs with blockchain payments. Just wrap your endpoint and start earning.

import { x402protect } from 'x402-easy-start';

// That's it! Your endpoint now requires $0.01 payment
app.use('/api/search', x402protect({
  wallet: 'YOUR_WALLET_ADDRESS',
  price: '$0.01',
  network: 'solana'
}));

✨ Features

• 🎯 One-line integration - Add payments in seconds
• 💰 Multiple networks - Solana, Base, Polygon, Avalanche, and more
• ⚡ Automatic handling - Payment verification, settlement, all automatic
• 🔒 Secure - Built on x402 protocol with cryptographic signatures
• 💸 No gas fees - Network fees covered by PayAI facilitator
• 🚀 Production ready - Battle-tested infrastructure

📦 Installation

npm install x402-easy-start

🚀 Quick Start

Basic Usage

import express from 'express';
import { x402protect } from 'x402-easy-start';

const app = express();
app.use(express.json());

// FREE endpoint (add before protection)
app.get('/api/health', (req, res) => {
  res.json({ status: 'healthy' });
});

// PAID endpoint - requires $0.01 payment
app.use('/api/search', x402protect({
  wallet: 'YOUR_SOLANA_WALLET_ADDRESS',
  price: '$0.01',
  network: 'solana'
}));

app.post('/api/search', (req, res) => {
  // This code only runs if payment was successful!
  res.json({ result: 'Your paid data here' });
});

app.listen(4021, () => {
  console.log('Server running on http://localhost:4021');
});

🎛️ API Reference

x402protect(config)

Protect a single endpoint with x402 payments.

Configuration

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | wallet | string | ✅ Yes | - | Your wallet address (where you receive payments) | | price | string | No | '$0.01' | Price per request (e.g., '$0.01', '0.001') | | network | string | No | 'solana' | Blockchain network | | method | string | No | Auto-detected | HTTP method (GET, POST, etc.) | | facilitator | string | No | PayAI | Custom facilitator URL |

Example

app.use('/api/predict', x402protect({
  wallet: 'YOUR_SOLANA_WALLET_ADDRESS',
  price: '$0.01',
  network: 'solana'
}));

app.post('/api/predict', (req, res) => {
  // Payment verified - process request
  res.json({ prediction: 'result' });
});

x402protectMultiple(wallet, routes, options)

Protect multiple endpoints with different prices.

Parameters

• wallet (string) - Your wallet address
• routes (object) - Route configuration
• options (object) - Additional options

Example

import { x402protectMultiple } from 'x402-easy-start';

app.use(x402protectMultiple(
  'YOUR_SOLANA_WALLET_ADDRESS',
  {
    'POST /api/basic': { price: '$0.001' },
    'POST /api/advanced': { price: '$0.05' },
    'GET /api/premium/*': { price: '$0.10' }
  },
  { 
    network: 'solana',
    facilitator: 'https://facilitator.payai.network'
  }
));

x402quickStart(config)

Quick setup helper - creates a complete Express app with x402.

Configuration

| Option | Type | Required | Default | |--------|------|----------|---------| | wallet | string | ✅ Yes | - | | network | string | No | 'solana' | | port | number | No | 4021 |

Example

import { x402quickStart } from 'x402-easy-start';

const app = x402quickStart({
  wallet: 'YOUR_SOLANA_WALLET_ADDRESS',
  network: 'solana',
  port: 3000
});

app.post('/api/search', x402protect({ price: '$0.01' }), (req, res) => {
  res.json({ result: 'data' });
});

app.listen();

🌍 Supported Networks

• ✅ Solana (solana, solana-devnet)
• ✅ Base (base, base-sepolia)
• ✅ Polygon (polygon, polygon-amoy)
• ✅ Avalanche (avalanche, avalanche-fuji)
• ✅ Sei (sei, sei-testnet)
• ✅ IoTeX (iotex)
• ✅ Peaq (peaq)

💰 Pricing Examples

// $0.01 USD
{ price: '$0.01' }

// $0.10 USD
{ price: '$0.10' }

// $1.00 USD
{ price: '$1.00' }

// 0.001 USD (tenth of a cent)
{ price: '$0.001' }

// Atomic units (advanced)
{
  price: {
    amount: '100000',
    asset: {
      address: '0xTokenAddress',
      decimals: 18,
      eip712: { name: 'USDC', version: '1' }
    }
  }
}

🔒 How It Works

1. Client → Server: Request without payment
2. Server → Client: 402 Payment Required + Requirements
3. Client → Server: Request WITH payment header (automatic)
4. Server → Facilitator: Verify payment
5. Facilitator → Blockchain: Check signature
6. Server → Client: Response with data
7. Facilitator → Blockchain: Execute transaction
8. 💰 Money in your wallet!

📝 Client Side (Making Payments)

Your users need an x402-compatible client to make payments:

import axios from 'axios';
import { withPaymentInterceptor, createSigner } from '@payai/x402-axios';

// Create signer with private key
const signer = await createSigner('solana', PRIVATE_KEY);

// Create HTTP client with automatic payment
const client = withPaymentInterceptor(
  axios.create({ baseURL: 'http://localhost:4021' }),
  signer
);

// Make paid request (payment happens automatically!)
const response = await client.post('/api/search', {
  query: 'my search'
});

console.log(response.data); // Your data

🎯 Use Cases

• 🤖 AI API Monetization - Charge per AI inference
• 🔍 Search APIs - Pay per search query
• 📊 Data APIs - Micropayments for data access
• 🎮 Gaming APIs - In-game purchases via API
• 📈 Analytics APIs - Pay per analytics request
• 🎵 Content APIs - Access to premium content

🆚 Why x402-easy-start?

| Feature | x402-easy-start | Traditional Payment APIs | |---------|-----------------|-------------------------| | Setup time | 30 seconds | Days/weeks | | Code complexity | 1 line | Hundreds of lines | | Payment latency | <1 second | Minutes | | Transaction fees | $0 (covered) | 2-3% + fixed fee | | Integration | Drop-in | Complex SDK | | KYC required | No | Yes | | Minimum payment | $0.0001 | $0.50+ |

📖 Resources

• x402 Protocol
• PayAI Facilitator
• PayAI Website

📄 License

MIT © 2025

🙏 Credits

Built on top of:

• x402 Protocol
• PayAI Facilitator
• x402-express

Made with ❤️ for the future of API monetization