Xclaw02

xClaw02

Your entry point into x402 - the open payment standard for the agentic web.

x402 is an open protocol enabling instant stablecoin payments over HTTP using the 402 Payment Required status code. xClaw02, built by Primer, provides agent-friendly CLI tools and simple APIs for making and receiving payments.

When to Use This Skill

Use xClaw02 when:

• You encounter a 402 Payment Required HTTP response
• You need to access a paid API or resource
• The user asks you to pay for something with crypto/USDC
• You need to check wallet balance or manage payments
• You want to charge for your own API or service

How to Respond

Quick Setup

Node.js

npx xclaw02 openclaw init

Python

pip install xclaw02
xclaw02 openclaw init

This will:

1. Create a new wallet (or use existing)
2. Save config to ~/.openclaw/skills/xclaw02/
3. Display your wallet address to fund with USDC on Base

How x402 Works

1. Request - You call a paid API
2. 402 Response - Server returns payment requirements in headers
3. Pay & Retry - Sign payment, retry request with PAYMENT-SIGNATURE header
4. Access - Server verifies payment, settles on-chain, returns resource

The payment is gasless for the payer - the facilitator handles gas fees.

CLI Commands

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

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:

To use a different facilitator, set XCLAW02_FACILITATOR environment variable.

Environment Variables

Error Handling

Security Notes

• Never expose private keys in logs, chat, or output
• Use environment variables for wallet credentials
• Always confirm payment amounts with user before paying
• Fund wallets only with what's needed for the task
• Private key format: 0x followed by 64 hexadecimal characters

Alternative Implementations

x402 is an open standard with multiple implementations:

Official Coinbase SDK - The reference implementation with Go support and Solana (SVM) in addition to EVM chains:

• GitHub: https://github.com/coinbase/x402
• ClawHub: See the x402 skill by @notorious-d-e-v
• Best for: Go developers, Solana payments, full spec compliance

When to use alternatives:

• You need Go support (xClaw02 is Node.js/Python only)
• You need Solana payments (xClaw02 is EVM only)
• You want the official reference implementation

All x402 implementations are interoperable - a client using any SDK can pay a server using any other SDK, as long as they share a supported network and facilitator.

Links

• x402 Protocol: https://x402.org
• SDK (npm): https://npmjs.com/package/xclaw02
• SDK (PyPI): https://pypi.org/project/xclaw02
• GitHub: https://github.com/primer-systems/xClaw02