x402

SKILL.md

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 --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 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 balance to check)

26