Example CLI Output

$ xclaw02 probe https://api.example.com/paid
{
  "status": "payment_required",
  "price": "0.05",
  "currency": "USDC",
  "network": "base",
  "recipient": "0x1234...abcd",
  "description": "Premium API access"
}

$ xclaw02 wallet balance 0xYourAddress
{
  "address": "0xYourAddress",
  "network": "base",
  "balance": "12.50",
  "token": "USDC"
}

$ xclaw02 pay https://api.example.com/paid --max-amount 0.10
{
  "status": "success",
  "paid": "0.05",
  "txHash": "0xabc123...",
  "response": { ... }
}

Using in Code

Node.js / TypeScript

const { createSigner, x402Fetch } = require('xclaw02');

// Private key format: 0x followed by 64 hex characters
const signer = await createSigner('eip155:8453', process.env.XCLAW02_PRIVATE_KEY);
const response = await x402Fetch('https://api.example.com/paid', signer, {
  maxAmount: '0.10'  // Maximum USDC to spend
});
const data = await response.json();

Python

from xclaw02 import create_signer, x402_requests
import os

# Private key format: 0x followed by 64 hex characters
signer = create_signer('eip155:8453', os.environ['XCLAW02_PRIVATE_KEY'])
with x402_requests(signer, max_amount='0.10') as session:
    response = session.get('https://api.example.com/paid')
    data = response.json()

Selling Your Services (Server-Side)

Want other agents to pay you? Add a paywall to your API:

Express.js

const express = require('express');
const { x402Express } = require('xclaw02');

const app = express();

app.use(x402Express('0xYourAddress', {
  '/api/premium': {
    amount: '0.05',          // $0.05 USDC per request
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    network: 'eip155:8453'
  }
}));

app.get('/api/premium', (req, res) => {
  res.json({ data: 'Premium content here' });
});

FastAPI (Python)

from fastapi import FastAPI
from xclaw02 import x402_fastapi

app = FastAPI()

app.add_middleware(x402_fastapi(
    '0xYourAddress',
    {
        '/api/premium': {
            'amount': '0.05',
            'asset': '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
            'network': 'eip155:8453'
        }
    }
))

@app.get("/api/premium")
async def premium_endpoint():
    return {"data": "Premium content here"}

Supported Networks

| Network | CAIP-2 ID | Token | Notes | |---------|-----------|-------|-------| | Base | eip155:8453 | USDC | Primary - fast, cheap, recommended | | Base Sepolia | eip155:84532 | USDC | Testnet | | Ethereum | eip155:1 | USDC | Higher fees | | Arbitrum | eip155:42161 | USDC | | | Optimism | eip155:10 | USDC | | | Polygon | eip155:137 | USDC | |

Base is the default network. To use others, set XCLAW02_NETWORK environment variable.

Facilitators

Facilitators handle payment verification and on-chain settlement. The x402 ecosystem has many independent facilitators:

| Name | URL | Notes | |------|-----|-------| | Primer | https://x402.primer.systems | Default | | Coinbase | https://api.cdp.coinbase.com/platform/v2/x402 | | | x402.org | https://x402.org/facilitator | Testnet only | | PayAI | https://facilitator.payai.network | | | Corbits | https://facilitator.corbits.dev | | | Dexter | https://x402.dexter.cash | | | Heurist | https://facilitator.heurist.xyz | | | Kobaru | https://gateway.kobaru.io | | | Nevermined | https://api.live.nevermined.app/api/v1/ | | | Openfacilitator | https://pay.openfacilitator.io | | | Solpay | https://x402.solpay.cash | | | xEcho | https://facilitator.xechoai.xyz | |

To use a different facilitator, set XCLAW02_FACILITATOR environment variable.

Environment Variables

| Variable | Format | Description | |----------|--------|-------------| | XCLAW02_PRIVATE_KEY | 0x + 64 hex chars | Wallet private key (required for payments) | | XCLAW02_NETWORK | eip155:8453, base, etc. | Default network (default: base) | | XCLAW02_MAX_AMOUNT | 0.10 | Default max payment amount in USDC | | XCLAW02_FACILITATOR | URL | Facilitator URL override |

Error Handling

| Error Code | Meaning | What to Do | |------------|---------|------------| | INSUFFICIENT_FUNDS | Wallet balance too low | Tell user to fund wallet with USDC on Base | | AMOUNT_EXCEEDS_MAX | Payment exceeds maxAmount | Ask user to approve higher amount, then retry with --max-amount | | SETTLEMENT_FAILED | On-chain settlement failed | Wait a moment and retry, or try a different facilitator | | INVALID_RESPONSE | Malformed 402 response | The URL may not support x402 properly | | NETWORK_MISMATCH | Wrong network | Check the 402 response for required network, set XCLAW02_NETWORK |

Security Notes

...