Quickstart

Make your first autonomous agent payment in 5 minutes using the x402 protocol.

Prerequisites

• Node.js 18 or higher

• A wallet with USDC on Base, Polygon, Solana, or Stellar

• Basic understanding of stablecoin payments

Install the SDK

npm install @clawd402/openclaw-plugin

Or for Python:

pip install clawd402-python openclaw

Setup your agent wallet

Create a wallet configuration file ~/.clawd402/wallet.json:

{
  "type": "keystore",
  "path": "~/.clawd402/keystore.json",
  "chains": ["base", "polygon", "solana"]
}

Security Note: For production, use hardware wallets (Ledger/Trezor). Never commit private keys to version control.

Configure approval policies

Create ~/.clawd402/policies.yaml:

policies:
  # Auto-approve small payments
  - name: auto_approve_small
    conditions:
      max_value_usd: 10
      daily_limit_usd: 100
    action: auto_approve

  # Require approval for larger amounts
  - name: approve_large
    conditions:
      min_value_usd: 10
    action: require_human_approval
    notification:
      channels: [email]
      timeout: 3600

  # Default deny unknown patterns
  - name: default_deny
    conditions: {}
    action: reject

Make your first payment

TypeScript/JavaScript

import { Agent } from 'openclaw'
import { Clawd402Tool } from '@clawd402/openclaw-plugin'

// Initialize Clawd402 payment tool
const paymentTool = new Clawd402Tool({
  chains: ['base'],
  walletPath: '~/.clawd402/wallet.json',
  policiesPath: '~/.clawd402/policies.yaml'
})

// Create agent with payment capabilities
const agent = new Agent({
  name: 'payment_agent',
  tools: [paymentTool]
})

// Agent can now make payments via natural language
const result = await agent.run(`
Purchase access to weather API at https://api.weather.com/premium
for $5 USDC
`)

console.log(`Payment completed: ${result.paymentReceipt.txHash}`)
console.log(`Settled on: ${result.paymentReceipt.chain}`)
console.log(`Confirmation time: ${result.paymentReceipt.settlementTime}s`)

Python

from openclaw import Agent
from clawd402 import Clawd402Provider

# Initialize payment provider
provider = Clawd402Provider(
    chains=['base'],
    wallet_path='~/.clawd402/wallet.json',
    policies_path='~/.clawd402/policies.yaml'
)

# Create agent
agent = Agent(
    name='payment_agent',
    providers=[provider]
)

# Make payment
result = agent.run("""
Purchase access to weather API at https://api.weather.com/premium
for $5 USDC
""")

print(f"Payment hash: {result.tx_hash}")
print(f"Chain: {result.chain}")
print(f"Status: {result.status}")

What just happened?

When the agent attempts to access the API:

1. HTTP 402 Discovery: API responds with 402 Payment Required and payment details in headers

2. Payment Construction: Clawd402 constructs a USDC transaction on Base chain

3. Policy Check: Verifies payment is within auto-approval limits ($5 < $10)

4. Blockchain Settlement: Submits transaction and waits for confirmation (~2 seconds)

5. Request Retry: Retries API request with payment proof, receives data

Total time: ~3 seconds (vs 2-3 days for traditional payments) Total cost: ~$0.03 (vs 3% credit card fee = $0.15)

Receive payments as an agent

Agents can also earn revenue by providing services:

// Configure agent to receive payments
const serviceTool = new Clawd402Tool({
  chains: ['base'],
  walletPath: '~/.clawd402/wallet.json',
  receivePayments: true,
  pricing: {
    'data_analysis': 10,      // $10 USDC per analysis
    'code_review': 25,         // $25 USDC per review
    'report_generation': 50    // $50 USDC per report
  }
})

const serviceAgent = new Agent({
  name: 'data_analyst',
  tools: [serviceTool]
})

// Offer service via x402
serviceAgent.serve()
// Agent now responds to HTTP requests with 402 Payment Required
// After payment received, executes service and returns results

Check payment history

// View recent payments
const payments = await paymentTool.getPaymentHistory({
  limit: 10
})

for (const payment of payments) {
  console.log(`${payment.timestamp}: ${payment.type} ${payment.amount} USDC`)
  console.log(`  ${payment.description}`)
  console.log(`  Chain: ${payment.chain}, TX: ${payment.txHash}`)
}

// Check balance
const balance = await paymentTool.getBalance('base')
console.log(`Base USDC balance: ${balance.usdc}`)

Subscribe to recurring services

// Agent subscribes to monthly data feed
const result = await agent.run(`
Subscribe to real-time market data at https://api.marketdata.com
for $50 USDC per month. Auto-renew if daily usage exceeds 80% of free tier.
`)

// Clawd402 handles:
// - Initial payment
// - Monthly renewal reminders
// - Automatic renewal (if within approval limits)
// - Cancellation if budget exceeded

Multi-chain payments

Clawd402 automatically selects the optimal chain based on cost and availability:

const paymentTool = new Clawd402Tool({
  chains: ['base', 'polygon', 'solana', 'stellar'],
  preferredChain: 'base',  // Primary
  fallbackChains: ['polygon', 'solana', 'stellar'],
  walletPath: '~/.clawd402/wallet.json'
})

// Agent will try Base first, fallback to Polygon if needed
// Solana used for micropayments (<$1) due to lower fees
// Stellar for cross-border payments

What's next?

Now that you've made your first payment, explore advanced features:

• OpenClaw Integration: Build autonomous payment workflows

• Approval Policies: Configure spending rules and human-in-the-loop

• Making & Receiving Payments: Complete payment capabilities guide

• Subscription Management: Automated recurring payments

• Security Best Practices: Production deployment security

Get testnet USDC

Need testnet tokens for testing? Use the Base Sepolia faucet:

# Get testnet ETH for gas
curl -X POST https://faucet.base.org/api/claim \
  -H "Content-Type: application/json" \
  -d '{"address": "your-wallet-address"}'

# Get testnet USDC
# Visit: https://faucet.circle.com/

Or use Clawd402's testnet helper:

const paymentTool = new Clawd402Tool({
  network: 'testnet',
  chains: ['base-sepolia'],
  walletPath: '~/.clawd402/wallet.json'
})

// Request testnet USDC
await paymentTool.requestTestnetFunds({
  amount: 100,  // 100 USDC
  chain: 'base-sepolia'
})

Troubleshooting

"Insufficient funds" error

Check your USDC balance on the target chain:

const balances = await paymentTool.getAllBalances()
console.log(balances)
// { base: { usdc: '50.00', eurc: '0.00' }, polygon: { usdc: '25.00' } }

Fund your wallet via:

• Bridge from mainnet: bridge.base.org

• Buy directly on chain via Coinbase

• Receive from another wallet

Payment stuck/pending

Check payment status:

const status = await paymentTool.getPaymentStatus(txHash)
console.log(status)
// { state: 'pending', chain: 'base', confirmations: 1 }

Payments on Base typically confirm in 2-4 seconds. If stuck >30 seconds:

1. Check network status: status.base.org

2. Verify sufficient gas (ETH on Base/Polygon, SOL on Solana)

3. Try alternative chain via fallback configuration

"Policy rejected" error

Payment exceeded approval limits. Options:

1. Approve manually if amount is legitimate

2. Adjust policy limits in ~/.clawd402/policies.yaml

3. Use human-in-the-loop approval for this transaction

// Get pending approvals
const pending = await paymentTool.getPendingApprovals()
console.log(pending)

// Approve specific payment
await paymentTool.approvePayment(approvalId)

HTTP 402 not supported by API

Not all APIs support x402 yet. Check if the API provider:

• Returns 402 Payment Required status code

• Includes X-Payment-Address and X-Payment-Amount headers

• Accepts payment proof in retry request

If API doesn't support x402, you can:

• Request x402 support from API provider

• Use traditional payment methods for that API

• Build custom integration wrapper

Support

Questions? We're here to help:

• Discord: discord.gg/clawd402

• GitHub Issues: github.com/clawd402/clawd402/issues

• Email: [email protected]

• Documentation: docs.clawd402.dev