x402 Private Search

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 wi...

Security Scan

The skill's files and instructions line up with its stated purpose (making x402-paid HTTP requests), but it asks you to generate and store a full EVM private key and runs an npm install in your home directory — so take normal crypto and dependency precautions before installing.

Purpose & Capability

The name/description promise (x402 paid requests / paid search) matches the included code: a wallet generator, a fetch wrapper that handles 402/payment signing, and a services list. The scripts and docs are coherent with this purpose.

Instruction Scope

SKILL.md instructs the agent/user to run setup.sh, generate a wallet, store the private key (env or file), and call x402-fetch.mjs. The scripts only read a local key and sign payments; they do not attempt to read unrelated files or send arbitrary data elsewhere. The instructions do require you to keep and expose a private key to the local environment (sensitive) and to run commands from ~/.x402-client.

Install Mechanism

Installation is a local npm install (setup.sh) into ~/.x402-client which will fetch @x402/fetch, @x402/evm and viem from the npm registry. This is a common pattern but does execute network installs and writes files to your home directory; review those npm packages if you need higher assurance.

Credentials

The skill requires access to a full EVM private key (via X402_PRIVATE_KEY, X402_KEY_FILE, or --key-file). That is necessary for signing payments but is highly sensitive. Registry metadata did not declare required env vars, even though SKILL.md relies on them — a metadata/documentation mismatch you should note.

Persistence & Privilege

The skill does not request always:true or modify other skills; it installs to and operates within ~/.x402-client. That local persistence is limited in scope and expected for a CLI-style client.

Assessment

This skill appears to do what it claims, but it requires you to create and store an EVM private key and installs npm packages into ~/.x402-client. Before installing: (1) use a throwaway/test wallet with only the small testnet funds needed, not a mainnet or valuable key; (2) inspect the npm dependencies (@x402/* and viem) and/or run npm install in a sandbox/container if you are unsure; (3) prefer storing the key in a file with restrictive permissions (mode 600) rather than exposing it widely in your environment; (4) verify the service URL(s) you intend to call (the provided search endpoint is a Cloudflare tunnel and may be ephemeral); and (5) if you need stronger assurance, request a signed upstream source or official homepage for the x402 packages before trusting them.

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.