Skill: primer-dev/xclaw02 (version 0.1.0)

--- name: xclaw02 description: Make x402 payments. Pay for APIs, sell your services, handle 402 Payment Required responses with USDC on Base and other EVM chains. metadata: {"openclaw":{"emoji":"$","requires":{"anyBins":["node","npx","python3","pip"]}}} --- # xClaw02 Your entry point into x402 - the open payment standard for the agentic web. x402 is an [open protocol](https://x402.org) enabling instant stablecoin payments over HTTP using the 402 Payment Required status code. xClaw02, built by [Primer](https://primer.systems), 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 | User Says/Asks | What to Do | |----------------|------------| | "I got a 402 error" | This is an x402 payment request. Probe the URL with `xclaw02 probe <url>`, show the price, ask if they want to pay | | "Pay for this API" | Use `xclaw02 pay <url> --max-amount <amount>` - always confirm amount with user first | | "Check my balance" | Run `xclaw02 wallet balance <address>` | | "Set up x402" / "Set up payments" | Run `xclaw02 openclaw init` | | "What networks do you support?" | List supported networks (Base is primary; also Ethereum, Arbitrum, Optimism, Polygon) | | "How much does X cost?" | Probe the URL with `xclaw02 probe <url>` to get pricing | | "Create a wallet" | Run `xclaw02 wallet create` - remind user to save the private key securely | | "I want to charge for my API" | Show the Express.js or FastAPI middleware examples | ## Quick Setup ### Node.js ```bash npx xclaw02 openclaw init ``` ### Python ```bash 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 | Command | Description | |---------|-------------| | `xclaw02 openclaw init` | Set up xClaw02 for this agent | | `xclaw02 openclaw status` | Check setup status and balance | | `xclaw02 probe <url>` | Check if URL requires payment and get price | | `xclaw02 pay <url>` | Pay for a resource (requires XCLAW02_PRIVATE_KEY) | | `xclaw02 pay <url> --dry-run` | Preview payment without paying | | `xclaw02 pay <url> --max-amount 0.10` | Pay with spending limit | | `xclaw02 wallet create` | Create a new wallet | | `xclaw02 wallet balance <address>` | Check USDC balance on Base | | `xclaw02 wallet from-mnemonic` | Restore wallet from mnemonic | | `xclaw02 networks` | List supported networks | ### Example CLI Output ```bash $ 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 ```javascript 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 ```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 ```javascript 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: [REDACTED_SECRET], network: 'eip155:8453' } })); app.get('/api/premium', (req, res) => { res.json({ data: 'Premium content here' }); }); ``` ### FastAPI (Python) ```python from fastapi import FastAPI from xclaw02 import x402_fastapi app = FastAPI() app.add_middleware(x402_fastapi( '0xYourAddress', { '/api/premium': { 'amount': '0.05', 'asset': [REDACTED_SECRET], '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 - **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

path: _meta.json
content: {
  "name": "xclaw02",
  "version": "0.5.0",
  "description": "The OpenClaw entry point for x402 payments. Pay for APIs, sell your services, handle 402 responses.",
  "author": "Primer Systems",
  "homepage": "https://primer.systems/x402",
  "repository": "https://github.com/primer-systems/x402",
  "keywords": [
    "x402",
    "payments",
    "openclaw",
    "agents",
    "usdc",
    "micropayments",
    "base"
  ],
  "license": "MIT"
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)