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:
- Makes the HTTP request
- If 402 received, parses payment requirements
- Signs a USDC payment with your wallet
- Retries with the payment header
- 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.