x402-pay

name	x402_pay
description	Pay for any HTTP API automatically using USDC on Base. Detects x402 (HTTP 402) pricing, signs ERC-3009 authorization, and settles on-chain — all transparent to the user.
homepage	https://github.com/anthropics/x402-gateway
metadata	{"openclaw":{"emoji":"💳","requires":{"anyBins":["node","npx"],"env":["COINWALL_WALLET_KEY"]},"install":[{"id":"npm","kind":"node","pkg":"@coinwall/mcp","bins":["coinwall-mcp"],"label":"Install x402 Payment MCP Server (npm)"}]}}

x402 Pay — Automatic Crypto Payments for AI Agents

You have access to an x402 payment MCP server that lets you call any paid HTTP API by automatically handling cryptocurrency payments. When an API returns HTTP 402 (Payment Required), you sign an ERC-3009 USDC authorization off-chain — no gas needed, no manual steps.

MCP Server Configuration

The x402 MCP server must be configured in OpenClaw's MCP settings. If the user asks to set up x402 payments, or if you encounter an error indicating the MCP server is not available, guide them to add this to their OpenClaw MCP config:

{
  "x402": {
    "command": "npx",
    "args": ["@coinwall/mcp"],
    "env": {
      "COINWALL_WALLET_KEY": "<wallet-private-key-0x...>",
      "COINWALL_NETWORK": "eip155:84532",
      "COINWALL_MAX_PER_CALL": "0.01",
      "COINWALL_MAX_PER_HOUR": "1.00",
      "COINWALL_MAX_TOTAL": "50.00"
    }
  }
}

Environment variables

Variable	Required	Default	Description
COINWALL_WALLET_KEY	Yes	—	Wallet private key (0x...) for signing payments
COINWALL_NETWORK	No	eip155:84532	Network: eip155:84532 (Base Sepolia testnet) or eip155:8453 (Base mainnet)
COINWALL_MAX_PER_CALL	No	unlimited	Max USDC per single API call
COINWALL_MAX_PER_HOUR	No	unlimited	Max USDC per rolling hour
COINWALL_MAX_TOTAL	No	unlimited	Max USDC lifetime total
COINWALL_RPC_URL	No	public RPC	Custom RPC endpoint

Available MCP Tools

You have 4 tools from the x402 MCP server:

1. fetch_paid_api — Call any API with automatic payment

Use this as your primary HTTP fetch for any URL that might require payment. It works transparently:

• Free URLs: request passes through normally (no payment)
• Paid URLs (402): automatically detects price, signs payment, retries — user sees only the result

Input:

• url (required): The API URL to fetch
• method (optional): HTTP method — GET, POST, PUT, DELETE (default: GET)
• headers (optional): Additional request headers as key-value pairs
• body (optional): Request body string (for POST/PUT)

Success response:

{
  "status": "success",
  "statusCode": 200,
  "data": { "...API response..." },
  "spending": { "total": "0.003", "thisHour": "0.001" }
}

When presenting results to the user:

• Show the API data in a useful format (not raw JSON)
• Mention the cost: "(Cost: $X USDC)"
• If total spending is notable, mention it: "(Total spent this session: $X)"

2. check_price — Preview cost before paying

Use this BEFORE calling an expensive API, or when the user asks "how much does X cost?"

Input: url (required)

Responses:

{
  "status": "success",
  "amount": "0.001",
  "currency": "USDC",
  "network": "eip155:84532",
  "payTo": "0x..."
}

{ "status": "not_paid", "message": "This URL does not require x402 payment." }

When presenting: "This API costs $0.001 USDC per request."

3. check_balance — Check wallet USDC balance

Use when the user asks about their balance, or proactively when a payment fails.

Input: none

Response:

{
  "status": "success",
  "balance": "49.85",
  "currency": "USDC",
  "address": "0x...",
  "network": "eip155:84532"
}

When presenting: "Your wallet 0xABC...1234 has $49.85 USDC on Base Sepolia."

4. discover_resources — Find available paid APIs on a gateway

Use when the user asks "what APIs are available?" or wants to explore a Coinwall gateway.

Input: gateway (required) — The full discovery URL (e.g., https://gw.example.com/api/gateway/x402/discovery/resources/<merchant-uuid>)

Response:

{
  "status": "success",
  "resources": [
    {
      "name": "Weather API",
      "url": "https://...",
      "price": "0.001",
      "network": "eip155:84532",
      "description": "Real-time weather data"
    }
  ]
}

When presenting: Format as a table showing name, price, and description.

Decision Framework

Follow this logic when the user asks you to interact with an API:

1. User provides a URL directly → Use fetch_paid_api directly. It handles both free and paid URLs transparently.

2. User asks about cost first → Use check_price, then ask if they want to proceed.

3. User wants to explore a gateway → Use discover_resources, present the list, ask which to call.

4. User asks about balance/spending → Use check_balance.

5. Price seems high (> $0.01/call) → Proactively check price with check_price first, tell the user the cost, and confirm before paying.

Error Handling

budget_exceeded

{
  "status": "budget_exceeded",
  "limitType": "per-call",
  "limit": "0.01",
  "spent": "0",
  "requested": "0.05"
}

Tell the user which limit was hit and the amount. Suggest they update their COINWALL_MAX_PER_CALL (or per-hour/total) environment variable in their MCP config.

insufficient_balance

{
  "status": "insufficient_balance",
  "required": "0.001",
  "balance": "0",
  "walletAddress": "0x...",
  "network": "eip155:84532"
}

Tell the user their wallet needs funding. Provide the wallet address and network. For Base Sepolia (testnet), suggest using a faucet. For Base mainnet, suggest transferring USDC via the Base bridge.

payment_failed

{ "status": "payment_failed", "reason": "..." }

Common causes: network mismatch, server error, or facilitator issue. Suggest checking that COINWALL_NETWORK matches the API's expected network.

error (generic)

{ "status": "error", "message": "COINWALL_WALLET_KEY environment variable is required." }

Usually means the MCP server is misconfigured. Guide the user to check their MCP config.

Wallet Funding Guide

Base Sepolia (testnet — for development):

1. Get testnet ETH from Base Sepolia Faucet
2. Get test USDC from a USDC testnet faucet
3. Send to the wallet address shown by check_balance

Base Mainnet (production — real money):

1. Send USDC on Base network to the wallet address
2. Bridge from Ethereum via Base Bridge
3. Recommended minimum: $5 USDC

Important Notes

• No gas required: Payments use ERC-3009 off-chain signatures. The facilitator handles on-chain settlement.
• Budget is your safety net: Always recommend users set budget limits to prevent accidental overspending.
• Spending resets on restart: The in-memory spending tracker resets when the MCP server restarts. Lifetime totals are approximate.
• Network must match: The wallet's configured network must match the API's payment network. Most test APIs use Base Sepolia (eip155:84532).