x402 Payment Protocol
Use the npx awal@2.10.0 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 awal@2.10.0 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 awal@2.10.0 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 awal@2.10.0 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 awal@2.10.0 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 awal@2.10.0 x402 bazaar search "weather"
# Search with more results
npx awal@2.10.0 x402 bazaar search "sentiment analysis" -k 10
# Check what an endpoint costs
npx awal@2.10.0 x402 details https://example.com/api/weather
# Make a GET request (auto-pays)
npx awal@2.10.0 x402 pay https://example.com/api/weather
# Make a POST request with body
npx awal@2.10.0 x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
# Limit max payment to $0.10
npx awal@2.10.0 x402 pay https://example.com/api/data --max-amount 100000
# Browse all bazaar resources with full details
npx awal@2.10.0 x402 bazaar list --fullUSDC 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 awal@2.10.0 auth login <email>) with sufficient USDC balance (npx awal@2.10.0 balance)
Error Handling
- "Not authenticated" - Run
npx awal@2.10.0 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 awal@2.10.0 balanceto check)
