Making Paid x402 Requests

Use the npx awal@2.0.3 x402 pay command to call paid API endpoints with automatic USDC payment on Base.

Confirm wallet is initialized and authed

npx awal@2.0.3 status

If the wallet is not authenticated, refer to the authenticate-wallet skill.

Command Syntax

npx awal@2.0.3 x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]

Options

| Option | Description |

| ----------------------- | -------------------------------------------------- |

| -X, --method | HTTP method (default: GET) |

| -d, --data | Request body as JSON string |

| -q, --query | Query parameters as JSON string |

| -h, --headers | Custom HTTP headers as JSON string |

| --max-amount | Max payment in USDC atomic units (1000000 = $1.00) |

| --correlation-id | Group related operations |

| --json | Output as JSON |

USDC Amounts

X402 uses USDC atomic units (6 decimals):

| Atomic Units | USD |

| ------------ | ----- |

| 1000000 | $1.00 |

| 100000 | $0.10 |

| 50000 | $0.05 |

| 10000 | $0.01 |

IMPORTANT: Always single-quote amounts that use $ to prevent bash variable expansion (e.g. '$1.00' not $1.00).

Input Validation

Before constructing the command, validate all user-provided values to prevent shell injection:

• url: Must be a valid URL starting with https:// or http://. Reject if it contains spaces, semicolons, pipes, backticks, or shell metacharacters.
• data (-d): Must be valid JSON. Always wrap in single quotes to prevent shell expansion.
• max-amount: Must be a positive integer (^\d+$).

Do not pass unvalidated user input into the command.

Examples

# Make a GET request (auto-pays)
npx awal@2.0.3 x402 pay https://example.com/api/weather

Make a POST request with body
npx awal@2.0.3 x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'

Limit max payment to $0.10
npx awal@2.0.3 x402 pay https://example.com/api/data --max-amount 100000

Prerequisites

• Must be authenticated (npx awal@2.0.3 status to check, see authenticate-wallet skill)
• Wallet must have sufficient USDC balance (npx awal@2.0.3 balance to check)
• If you don't know the endpoint URL, use the search-for-service skill to find services first

Error Handling

• "Not authenticated" - Run awal auth login first, or see authenticate-wallet skill
• "No X402 payment requirements found" - URL may not be an x402 endpoint; use search-for-service to find valid endpoints
• "Insufficient balance" - Fund wallet with USDC; see fund skill