x402 — HTTP-Native Payments#

x402 gates API resources behind USDC micropayments using HTTP 402 Payment Required.

---

Step 0: Setup#

Before running any script, install dependencies in the skill directory (once per environment):

bash

cd <skills-dir>/x402-pay
npm install

No API keys required. The default wallet (awal) works with just an email address. CDP, Privy, and Turnkey wallets are also supported if already configured.

---

Step 1: Detect your wallet#

Read references/detecting-wallets.md to choose which wallet to use. Once you've picked one, return here and continue from Step 2.

---

Step 2: Is the Service Known?#

If you already have a specific service URL in mind that returned 402 payment required, skip straight to Step 3: Get the Service Details.

Otherwise continue to Step 2a: Find a Service

Step 2a: Find a Service#

List all available services from x402-list and pick the most appropriate one:

bash

node scripts/search-services.mjs search

If nothing suitable is found, try the Coinbase bazaar:

bash

node scripts/search-services.mjs search <keyword> --source bazaar

If still nothing, search the internet for x402 services matching the user's need.

Step 3: Get the Service Details#

Once you have a service URL, get its full details (schemas, parameters, examples):

bash

node scripts/search-services.mjs details <resource-url>

Then preview the live price — this reads the 402 challenge without paying and is wallet-independent:

bash

node scripts/check-price.mjs <url> [--method GET|POST] [--body '{"key":"value"}']

Note this price: you'll use it in Step 4 to check whether your balance is sufficient (and, if funding, how much to deposit), and show it to the user before paying in Step 5.

Example working service#

bash

https://x402.ottoai.services/crypto-news

---

Step 4: Check Balance#

Check your wallet's USDC balance on Base — see references/wallet-flows.md for the method for your wallet (if you don't already know it) — and compare it against the price you previewed in Step 3.

• Balance ≥ service price → proceed to Step 5
• Balance < service price → fund it: Read references/near-intents-funding.md for the cross-chain funding flow. Always use NEAR intents to fund the wallet if the balance is low.

Gas: No ETH needed — you sign off-chain only. The x402 facilitator submits the on-chain transaction and covers gas. This applies to all wallet types.

---

Step 5: Pay#

Always show the price before paying. Confirm with user before paying.

Show the user the price you previewed in Step 3 (if significant time has passed, re-run check-price.mjs in case it changed). Always get their confirmation before paying — for any amount. Then pay the endpoint using your wallet — see references/wallet-flows.md for the method for your wallet (if not already known). Always pass the confirmed price, unpadded, as the payment command's hard cap — --max-price <usdc> for pay.mjs, --max-amount <atomic> for awal, MAX_PRICE in the managed-signer template — so a quote raised at payment time fails closed instead of overcharging.

This rule applies to every payment method, including wallets not covered in references/wallet-flows.md: if the wallet's tooling has a spend-cap option, pass the confirmed price there; otherwise plug its EIP-712 signer into the managed-signer template (it is wallet-agnostic — any wallet that can sign typed data works) so MAX_PRICE is enforced. Never pay through a mechanism that cannot enforce the confirmed price as a hard cap at payment time.

---

Step 6: Confirm#

Report the response body and any transaction hash to the user.

---

Rules#

• Always ask the user before executing any command. Show the exact command you intend to run and wait for explicit approval before running it — this applies to wallet, payment, and funding commands.
• Abide by configured safeguards such as wallet spend limits and allowlists.
• Never pay through a mechanism that cannot enforce the user-confirmed price as a hard cap at payment time — for wallets without one, route signing through the managed-signer template in references/wallet-flows.md.
• If a wallet's authentication is missing or expired (e.g. awal is signed out), stop immediately and report it, telling the user what login action to take. Never attempt to recover access yourself: do not search the user's files, email, message history, or browser/app storage for keys, session tokens, or OTP codes, and do not retry authentication repeatedly.
• When funding, always confirm the refund destination (the address and its origin chain) with the user before any deposit.
• Never pay silently — always show the decoded price first
• Confirm with user before any payment
• Always report the tx hash after a successful payment