x402-client

x402 Client

Make HTTP requests to x402-protected APIs. The x402 protocol uses HTTP 402 responses to request payment — this skill handles signing USDC payments and retrying automatically.

Prerequisites

• Node.js 18+ installed
• A Base Sepolia wallet with ETH (gas) and USDC (payments)

First-Time Setup

1. Install dependencies

bash <skill-dir>/scripts/setup.sh

This installs the x402 SDK to ~/.x402-client/. Only needed once.

2. Generate a wallet (if you don't have one)

node <skill-dir>/scripts/wallet-gen.mjs --out ~/.x402-client/wallet.key

3. Fund the wallet

Get testnet tokens from faucets:

• Base Sepolia ETH (gas): https://www.alchemy.com/faucets/base-sepolia
• Base Sepolia USDC (payments): https://faucet.circle.com/ → select Base Sepolia + USDC

Send both to the wallet address printed by wallet-gen.

4. Store the key

Set the environment variable for future use:

export X402_PRIVATE_KEY=$(cat ~/.x402-client/wallet.key)

Or pass --key-file ~/.x402-client/wallet.key to each request.

Making Paid Requests

Use x402-fetch.mjs to make any x402-paid HTTP request:

# Search the web ($0.001 USDC per query)
node <skill-dir>/scripts/x402-fetch.mjs \
  "https://<service-url>/web/search?q=latest+AI+news&count=5" \
  --key-file ~/.x402-client/wallet.key

The script automatically:

1. Makes the HTTP request
2. If 402 received, parses payment requirements
3. Signs a USDC payment with your wallet
4. Retries with the payment header
5. Outputs the response JSON to stdout

All scripts must be run from ~/.x402-client/ (where node_modules lives):

cd ~/.x402-client && node <skill-dir>/scripts/x402-fetch.mjs "<url>" --key-file wallet.key

Known Services

See references/services.md for a list of known x402 endpoints including a web search service.

Troubleshooting

• "insufficient funds": Wallet needs more USDC or ETH. Use faucets above.
• 402 with no auto-payment: Ensure setup.sh was run and you're executing from ~/.x402-client/.
• Tunnel URL not working: The service URL may have changed. Ask the service operator or check /health.