wallet-payments

Wallet payments (USDC on Base)

You have a Coinbase Smart Wallet on Base loaded with USDC. Gas is sponsored by the Coinbase Paymaster (zero ETH needed) and USDC on Base has near-zero transaction fees, so micropayments are viable.

Wallet actions

• get_balance (token="USDC"): check your USDC balance before making payments.
• get_address: the wallet address (for the user to fund externally).
• pay_for_resource: pay for a paywalled HTTP resource via the x402 protocol. Signs the payment AND fetches the content in one call. Requires resource_url and amount; optional reason.
• fund_wallet: a URL for the user to fund the wallet (Coinbase Onramp on mainnet, faucet on testnet).
• send_usdc: send USDC to an address for user-initiated transfers, paying other agents or services, purchasing digital goods, or any prompt-driven payment.
• get_transaction_history: recent wallet transactions.

Approval

Sends and payments are held for the owner's approval unless a standing spend grant covers them. When a wallet call returns APPROVAL-REQUIRED or APPROVAL-PENDING with an id like rv-1a2b3c4d: the action was NOT performed, the owner has been asked, and the gateway will carry it out for them if they approve. Tell the user it is waiting for their approval, do not retry the call, and do not try another way to make the same payment. You will be told the outcome in a later turn.

Handling paywalls (HTTP 402)

When web_fetch returns a 402 Payment Required response, follow this workflow exactly:

1. Extract the price: if the 402 result has price_usdc, use it. The tool derives it from the x402 accepts[] offer only when the asset is USDC; x402_offer names the asset, network and amount in atomic units. Otherwise look at x402_headers for x-payment-amount. Do not convert raw amount or maxAmountRequired values from payment_required, payment_details or the body_snippet yourself: they are atomic units (10000 is 0.01 USDC) and easy to misread, so treat the price as unclear.
2. Handle unclear prices: if you cannot confidently determine the price, DO NOT GUESS. Ask: "This resource requires payment, but the price isn't clear. Would you like me to proceed, and what is your maximum budget?"
3. Check balance and rules: call get_balance (token="USDC"). If the cost exceeds your spending limits, ask the user for permission.
4. Inform the user: state the cost and your intent briefly (for example "This endpoint requires a 0.15 USDC micropayment. I have the funds and am purchasing it now.").
5. Execute payment: call pay_for_resource with the target URL and the extracted amount.
6. Process content directly: pay_for_resource returns the un-paywalled content. Do NOT call web_fetch again after paying; use the pay_for_resource result immediately.