Agent wallet readiness check
One call answers 'can this wallet pay right now?' - USDC balances on Base AND Solana, live Base gas, and a ready-to-share Coinbase Onramp funding link if it's running dry.
3 tools run server-side in one request. You pay once, settle once, and get a single response - no orchestration, no per-step payments, and a partial-success envelope if any step fails. USDC over x402 on any supported chain.
When to use this pack
An agent (or the human operating it) is about to start a paid work session and needs to know the wallet is actually ready: does it hold USDC on the chains it pays on, what's gas doing, and - if the balance is low - where does a human top it up with a card? Checking each of those separately means three tools and a docs page; this pack returns the whole preflight in one envelope. Run it at session start, before a batch job, or on a schedule as a balance monitor.
Tools in this pack
All 3 run inside the single $0.008 call above. Each is also callable on its own if you only need one part.
- Wallet token balances (indexed) GET /api/wallet-balances All token balances for any address in one call, from Coinbase's indexed data API - ERC-20 + native on EVM, SPL on Solana; no per-token contract calls, no RPC wrangling. Networks: base, ethereum, base-sepolia, solana, solana-devnet. Symbols/decimals populated for whitelisted tokens (USDC always included).
- Gas snapshot (slow / standard / fast) POST /api/gas-snapshot Live gas price snapshot for a chain - slow / standard / fast tiers in gwei, plus the latest base fee. Sampled from eth_feeHistory (last 4 blocks, 25th/50th/90th percentile priority fees). Use to estimate before broadcasting a transaction from another tool.
- Onramp link (fund a wallet with a card) POST /api/onramp-link Generate a single-use Coinbase Onramp URL that lets a human fund any wallet with a card or Apple Pay - the fastest way to put real USDC into an agent's wallet. Returns the ready-to-open URL, and a fee-inclusive quote when Coinbase provides one. Networks: base, ethereum, polygon, arbitrum, optimism, solana.
Bought one at a time, these 3 tools cost $0.008 together; the pack is that sum less a 10% bundle discount, rounded up to the $0.001 settlement floor, which is $0.008.
Workflow
- Call wallet-balances with {address, network: "base"} - returns every indexed ERC-20 + native balance. Find the USDC row (contract 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913) and read its amount: this is the wallet's x402 spending power on Base.
- If the agent also pays on Solana, call wallet-balances again with {address: <the Solana address>, network: "solana"} - same envelope, SPL balances, USDC mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. (x402 settlement is gasless via EIP-3009 / sponsored transactions, so USDC is the only balance that matters - no ETH or SOL required.)
- Call gas-snapshot with {network: "base"} for slow/standard/fast gas. The agent never pays gas on x402 buys, but gas context tells you whether any NON-x402 onchain action you're planning (a manual transfer, a contract call) is cheap right now.
- If the USDC balance is below your working budget, call onramp-link with {address, network: "base", amount: "<usd>"} - it mints a single-use Coinbase Onramp URL a human can open to fund the wallet with a card or Apple Pay. Include the URL in your report; it expires unvisited, so minting it costs nothing but the call.
- Assemble the verdict: { ready: usdcBase >= budget, balances: { base, solana }, gas, fundingLink } - 'ready' should be computed against the session budget the caller stated, not a fixed threshold.
Arguments
| Name | Required | Description | Example |
|---|---|---|---|
address | yes | The EVM wallet address to check (0x…) | 0xaBF4FAbd7c416fB67202E5f9002389Fc75e2a9D0 |
solanaAddress | no | Optional Solana address to check SPL USDC as well | J7aN3PLJnTCF5qpEnvJHJsnCjcGuqC2rYtEM8Gv3xwg |
What one call returns
A JSON object with pack, args, steps, summary; steps holds one entry per tool (wallet-balances, gas-snapshot, onramp-link), each with its own result or error. Full example on the API page.
Call it directly
Any x402 client pays the 402 and gets the whole workflow back in one response:
npx agent402-client call wallet-readiness {"address":"0xaBF4FAbd7c416fB67202E5f9002389Fc75e2a9D0","solanaAddress":"J7aN3PLJnTCF5qpEnvJHJsnCjcGuqC2rYtEM8Gv3xwg"}
Run it in Claude
claude mcp add agent402 -s user -- npx -y agent402-mcp@latest
Then paste this prompt into Claude:
Run a wallet readiness preflight for 0xaBF4FAbd7c416fB67202E5f9002389Fc75e2a9D0 (Solana: J7aN3PLJnTCF5qpEnvJHJsnCjcGuqC2rYtEM8Gv3xwg) using Agent402. (1) wallet-balances {address, network: "base"} - find the USDC row and note the amount. (2) wallet-balances {address: <the Solana address>, network: "solana"} - the SPL USDC amount. (3) gas-snapshot {network: "base"} - note standard gas. (4) If USDC < $5, onramp-link {address, network: "base", amount: "10"} and include the funding URL. Return {ready, usdcBase, usdcSolana, gas, fundingLink?} with ready = (usdcBase + usdcSolana) >= 5.