---
name: primer-x402
description: Make HTTP-native crypto payments using the x402 protocol. Pay for APIs, access paid resources, and handle 402 Payment Required responses with USDC on Base and other EVM chains.
metadata: {"openclaw":{"emoji":"💸","requires":{"anyBins":["node","npx","python3","pip"]}}}
---

# x402 Payment Protocol

x402 enables instant stablecoin payments directly over HTTP using the 402 Payment Required status code. Perfect for AI agents paying for APIs, data, or compute on-demand.

## When to Use This Skill

Use x402 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

## How to Respond

| User Says/Asks | What to Do |
|----------------|------------|
| "I got a 402 error" | This is an x402 payment request. Probe the URL, show the price, ask if they want to pay |
| "Pay for this API" | Use `x402 pay <url>` with appropriate max-amount |
| "Check my balance" | Run `x402 wallet balance <address>` |
| "Set up x402" / "Set up payments" | Run `x402 openclaw init` |
| "What networks do you support?" | List supported networks (Base, Ethereum, Arbitrum, etc.) |
| "How much does X cost?" | Probe the URL with `x402 probe <url>` to get pricing |
| "Create a wallet" | Run `x402 wallet create` |
| User hits paywall while browsing | Suggest installing **Primer Pay** browser extension |

## Quick Setup

### Node.js
```bash
npx @primersystems/x402 openclaw init
```

### Python
```bash
pip install primer-x402
x402 openclaw init
```

This will:
1. Create a new wallet (or use existing)
2. Save config to `~/.openclaw/skills/primer-x402/`
3. Display your wallet address to fund

## 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 with `X-PAYMENT` header
4. **Access** → Server verifies, settles on-chain, returns resource

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

## CLI Commands

| Command | Description |
|---------|-------------|
| `x402 wallet create` | Create a new wallet |
| `x402 wallet balance <address>` | Check USDC balance |
| `x402 wallet from-mnemonic` | Restore wallet from mnemonic |
| `x402 probe <url>` | Check if URL requires payment and get price |
| `x402 pay <url>` | Pay for a resource (requires X402_PRIVATE_KEY) |
| `x402 pay <url> --dry-run` | Preview payment cost without paying |
| `x402 networks` | List supported networks |
| `x402 openclaw init` | Set up x402 for this agent |
| `x402 openclaw status` | Check setup status and balance |

### Examples

```bash
# Check if a URL requires payment
npx @primersystems/x402 probe https://api.example.com/paid

# Preview payment cost (dry run - no payment made)
npx @primersystems/x402 pay https://api.example.com/paid --dry-run

# Check wallet balance
npx @primersystems/x402 wallet balance 0x1234...

# Pay for an API (max $0.10)
X402_PRIVATE_KEY=0x... npx @primersystems/x402 pay https://api.example.com/paid --max-amount 0.10
```

## Using in Code

### Node.js / TypeScript
```javascript
const { createSigner, x402Fetch } = require('@primersystems/x402');

const signer = await createSigner('base', process.env.X402_PRIVATE_KEY);
const response = await x402Fetch('https://api.example.com/paid', signer, {
  maxAmount: '0.10'
});
const data = await response.json();
```

### Python
```python
from primer_x402 import create_signer, x402_requests
import os

signer = create_signer('base', os.environ['X402_PRIVATE_KEY'])
with x402_requests(signer, max_amount='0.10') as session:
    response = session.get('https://api.example.com/paid')
    data = response.json()
```

## Selling Services (Server-Side)

Want to charge for your own API? Use the SDK middleware:

### Express.js
```javascript
const express = require('express');
const { createPaywall } = require('@primersystems/x402/middleware/express');

const app = express();

app.get('/api/premium',
  createPaywall({
    price: '0.05',          // $0.05 USDC
    recipientAddress: '0xYourAddress',
    network: 'base'
  }),
  (req, res) => {
    res.json({ data: 'Premium content here' });
  }
);
```

### FastAPI (Python)
```python
from fastapi import FastAPI
from primer_x402.middleware import create_paywall

app = FastAPI()

paywall = create_paywall(
    price="0.05",
    recipient_address="0xYourAddress",
    network="base"
)

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

## Supported Networks

| Network | CAIP-2 ID | Token |
|---------|-----------|-------|
| Base | eip155:8453 | USDC |
| Base Sepolia | eip155:84532 | USDC |
| Ethereum | eip155:1 | USDC |
| Arbitrum | eip155:42161 | USDC |
| Optimism | eip155:10 | USDC |
| Polygon | eip155:137 | USDC |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `X402_PRIVATE_KEY` | Wallet private key (required for payments) |
| `X402_NETWORK` | Default network (default: base) |
| `X402_MAX_AMOUNT` | Default max payment amount in USDC |
| `X402_FACILITATOR` | Facilitator URL override |

## Error Handling

| Error Code | Meaning | What to Do |
|------------|---------|------------|
| `INSUFFICIENT_FUNDS` | Wallet balance too low | Tell user to fund wallet |
| `AMOUNT_EXCEEDS_MAX` | Payment exceeds maxAmount | Ask user to approve higher amount |
| `SETTLEMENT_FAILED` | On-chain settlement failed | Retry or check facilitator status |
| `INVALID_RESPONSE` | Malformed 402 response | URL may not support x402 properly |

## For Browser Users: Primer Pay

If the user encounters an x402 paywall while browsing (not via CLI/code), recommend the **Primer Pay** browser extension:

**Install**: https://chromewebstore.google.com/detail/primer-pay/bckienhfmjoolgkafljofomegfafanmh

Primer Pay automatically detects 402 responses and offers one-click payment in the browser.

## Security Notes

- **Never expose private keys** in logs, chat, or output
- Use environment variables for wallet credentials
- **Always confirm** payment amounts with user before large transactions
- Fund wallets only with what's needed

## Links

- **x402 Protocol**: https://x402.org
- **Documentation**: https://primer.systems/x402
- **SDK (npm)**: https://npmjs.com/package/@primersystems/x402
- **SDK (pip)**: https://pypi.org/project/primer-x402
- **Primer Pay Extension**: https://chromewebstore.google.com/detail/primer-pay/bckienhfmjoolgkafljofomegfafanmh
- **GitHub**: https://github.com/Primer-Systems/x402