ClawHub

x402 Private Search

Data & APIs

Make paid API requests using the x402 HTTP payment protocol (USDC on Base Sepolia). Use when you need to access x402-protected services, pay for API calls with crypto, or perform web searches via an x402 search gateway. Handles wallet setup, payment signing, and request retry automatically.

Install

openclaw skills install @kodos-vibe/x402-private-search

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:

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.
More in Data & APIs