About x402
x402 is a CLI skill for finding, inspecting, and calling paid API endpoints through the X402 protocol. It supports endpoint discovery and requirement checks before requests, with automatic USDC payment on Base.
Key features
- 01Search paid services by keyword and filters
- 02Browse and refresh the service index
- 03Inspect price, payment terms, and schemas
- 04Call endpoints with automatic USDC payment
Use cases
- 01Find paid APIs for a specific task
- 02Check endpoint costs before making a request
- 03Send a paid API request with a payment limit
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/x402in Claude Code to confirm it loaded.
Details
From the project READMEx402 Payment Protocol
Use the npx [email protected] x402 commands to discover, inspect, and call paid API endpoints using the X402 payment protocol. Payments are made in USDC on Base.
Workflow
The typical x402 workflow is:
- Find a service - Search the bazaar or get details for a known endpoint
- Check requirements - Inspect price, method, and input schema
- Make the request - Call the endpoint with automatic USDC payment
Commands
Search the Bazaar
Find paid services by keyword using CDP's vector search:
npx [email protected] x402 bazaar search <query> [-k <n>] [--network <network>] [--scheme <scheme>] [--max-price <price>] [--json]
| Option | Description |
|---|---|
-k, --top <n> | Number of results, 1–20 (default: 20) |
--network <name> | Filter by chain (base, base-sepolia, polygon, solana, solana-devnet) |
--scheme <scheme> | Filter by payment scheme: exact or upto |
--max-price <price> | Maximum price in USD (e.g. 0.01) |
--asset <address> | Filter by payment asset address |
--pay-to <address> | Filter by recipient wallet address |
--extensions <type> | Filter by extension type (e.g. outputSchema, bazaar) |
--json | Output as JSON |
List Bazaar Resources
Browse all available resources:
npx [email protected] x402 bazaar list [--network <network>] [--full] [--refresh] [--json]
| Option | Description |
|---|---|
--network <name> | Filter by chain (base, base-sepolia, polygon, solana, solana-devnet) |
--full | Show complete details including schemas |
--refresh | Re-fetch resource index from CDP API |
--json | Output as JSON |
Discover Payment Requirements
Inspect an endpoint's x402 payment requirements without paying:
npx [email protected] x402 details <url> [--json]
Auto-detects the correct HTTP method (GET, POST, PUT, DELETE, PATCH) by trying each until it gets a 402 response, then displays price, accepted payment schemes, network, and input/output schemas.
Make a Paid Request
Call an x402 endpoint with automatic USDC payment:
npx [email protected] x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]
| Option | Description |
|---|---|
-X, --method <method> | HTTP method (default: GET) |
-d, --data <json> | Request body as JSON string |
-q, --query <params> | Query parameters as JSON string |
-h, --headers <json> | Custom HTTP headers as JSON string |
--max-amount <amount> | Max payment in USDC atomic units (1000000 = $1.00) |
--correlation-id <id> | Group related operations |
--json | Output as JSON |
Examples
# Search for weather-related paid APIs
npx [email protected] x402 bazaar search "weather"
# Search with more results
npx [email protected] x402 bazaar search "sentiment analysis" -k 10
# Check what an endpoint costs
npx [email protected] x402 details https://example.com/api/weather
# Make a GET request (auto-pays)
npx [email protected] x402 pay https://example.com/api/weather
# Make a POST request with body
npx [email protected] x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
# Limit max payment to $0.10
npx [email protected] x402 pay https://example.com/api/data --max-amount 100000
# Browse all bazaar resources with full details
npx [email protected] x402 bazaar list --full
USDC Amounts
X402 uses USDC atomic units (6 decimals):
| Atomic Units | USD |
|---|---|
| 1000000 | $1.00 |
| 100000 | $0.10 |
| 50000 | $0.05 |
| 10000 | $0.01 |
Prerequisites
- Search/Details: No authentication needed
- Pay: Must be authenticated (
npx [email protected] auth login <email>) with sufficient USDC balance (npx [email protected] balance)
Error Handling
- "Not authenticated" - Run
npx [email protected] auth login <email>first - "No X402 payment requirements found" - URL may not be an x402 endpoint
- "CDP API returned 429" - Rate limited; cached data will be used if available
- "Insufficient balance" - Fund wallet with USDC (
npx [email protected] balanceto check)