Prepay USDC deposits — refill virtual balance

Use when an authenticated agent exhausts virtual_balance_usd and the host LLM cannot sign x402 payments (no wallet key in the LLM runtime).

When to use

GET /api/v1/agents/balance shows virtual_balance_usd below the route price.
402 billing_reason is virtual_balance_insufficient or payment_required.
The human operator can send USDC once; the LLM should not loop on wallet signatures.

Prerequisites

Wallet-bound bearer (mint at /connect or via SIWE wallet-register).
Sender wallet linked to the agent (POST /api/v1/agents/wallet-link if needed).
Sender holds enough USDC on Base (chain id 8453).

Human flow (SPA)

Open /connect?action=topup with the bearer cached in the browser.
Pick a linked wallet, enter amount (minimum $1 USDC).
Click Send USDC & credit balance (one MetaMask / Base passkey transfer).
Wait for six confirmations (~12s on Base).

LLM flow

GET /api/v1/balance/deposit/receive-address with bearer → read receive_address, min_usd, confirmations_required.
Ask the user to send USDC from a linked wallet to receive_address (or use /connect?action=topup).
After the user provides tx_hash, POST /api/v1/balance/deposit/claim:

{ "tx_hash": "0x…", "chain_id": 8453 }

On CONFIRMATIONS_PENDING, poll every few seconds until 200.
Retry the original paid call — BalanceWaterfall debits virtual balance; no 402 if balance covers price.

Idempotency

Same tx_hash claimed twice returns the original credit (no double-balance).

Errors

Code	Meaning
`SENDER_NOT_LINKED`	Transfer `from` is not in `dbo.agent_wallet` for this bearer — run `/wallet-link` first.
`CONFIRMATIONS_PENDING`	Tx mined but < 6 confirmations — retry claim.
`DEPOSIT_IS_X402_SETTLEMENT`	Tx is an on-chain x402 payment, not a prepay deposit.

Billing order (unchanged)

Virtual USD balance is debited before any wallet x402 draw. Prepay only refills virtual balance.

x402 top-up (wallet can sign)

When the client can sign x402 (browser wallet, WAIAAS, agent with keys):

POST /api/v1/balance/topup/x402 with { "amount_usd": 5, "chain_id": 8453 } (no PAYMENT-SIGNATURE) → 402 with xpay exact and CDP upto accepts at that amount (default $5, min $2.50, max $500).
Sign one accept (exact for xpay, upto for CDP).
Retry the same POST with the same amount_usd and header PAYMENT-SIGNATURE: <base64> → immediate settle + virtual balance credit.

Optional Authorization: Bearer credits that agent; otherwise the payer wallet is resolved (linked agent credited, or new wallet minted with bearer shown once).

Top-ups over $100 also get an independent Base RPC receipt check before credit.

Requires PREPAY_DEPOSITS_ENABLED=1 and PREPAY_X402_TOPUP_ENABLED=1.