Guide: Manage your wallet & budgets (for buyers)

When you buy through the connector, payments come from a managed wallet the platform custodies for your account, and you cap autonomous spend with buy jobs and an account policy. This guide is the buyer’s lifecycle companion to Buying with the connector: how to top up, read balances, control budgets, and recover your funds.

Don’t need a managed wallet? You can always pay non-custodially by signing your own X-PAYMENT — see Buy: raw x402 flow. This guide is for the custodial (managed-wallet) path.

Wallets — one per chain

create_wallet(chain) — base | solana | stellar. Creates a managed wallet and returns its deposit address plus a one-time mnemonic/key. Save the secret immediately — it is shown once and is your only way to recover funds outside the platform (see Recovering / withdrawing).
get_wallet — lists each chain’s wallet: address, on-chain USDC balance, and spendable (credited) balance. There’s one active wallet per chain per account.

Topping up (funding)

There is no card / fiat on-ramp — you fund a wallet by sending USDC on that chain to its address:

create_wallet("base") (or get_wallet to read an existing address).
Send USDC on the matching network to that address. Use the right chain — USDC on Base for a Base wallet, on Solana for a Solana wallet, etc. Sending the wrong asset or wrong chain can lose the funds.
get_wallet — this scans the deposit and credits your spendable balance.

Gotcha — fund, then get_wallet. Spendable balance is credited by a deposit scan that runs when you call get_wallet. If a buy fails with “insufficient wallet balance” right after sending USDC, call get_wallet once to credit the deposit, then retry. The on-chain balance and the spendable balance are shown side by side so you can see when a deposit has been picked up.

Reading balances

get_wallet returns, per chain:

Field	Meaning
`address`	deposit address (send USDC here)
`balance` (on-chain)	USDC actually on-chain at the address
`spendable` / credited	what you can spend now (after the deposit scan)
`status`	`active`, or `not_created` if you haven’t made one on that chain

A freshly-funded wallet shows the on-chain balance immediately but only becomes spendable after the crediting scan (above).

Spending & limits

You don’t need a budget object to buy. Fund the wallet, then call_endpoint(..., confirmed=true) pays straight from it. To bound spend, use the account policy; buy jobs are an optional advanced tool for delegation.

Account policy (the simple guardrail)

set_buy_policy(max_per_call_usd?, confirm_above_usd?) — a standing rule on your account: a call over max_per_call_usd is refused; a call over confirm_above_usd needs confirmed: true.
get_buy_policy reads it; set_buy_policy(clear=true) removes it.

Buy jobs (advanced — delegation)

Only needed to hand a capped, disposable budget to a separate agent process (so it can spend without your session). Most buyers never use these.

create_buy_job(chain, budget_usd?, max_per_call_usd?, ttl?, label?) → a spending_key (spk_…) shown once; the other agent passes it to call_endpoint and spends within the budget with no per-call confirmation.
list_buy_jobs(chain) — budget vs. spent vs. remaining + expiry.
close_buy_job(chain, key_id) — revoke early. Unspent budget simply stays in the wallet (a job is a limit, not a separate pot of money).

Expired or spent jobs

A buy job stops working when any limit is hit:

Symptom	Meaning	Fix
`amount exceeds this key's remaining budget`	the job’s total budget is used up	`create_buy_job` again (the wallet still holds the funds)
per-call refusal	the call price is over the job’s `max_per_call_usd`	make a job with a higher per-call cap, or confirm under policy
key expired	the job’s `ttl` elapsed	create a fresh job

Expiring or closing a job never loses money — it only revokes the spending permission. Your USDC stays in the managed wallet, available to the next job.

Recovering / withdrawing your funds

There is no in-app “withdraw” button — the managed wallet is a real on-chain wallet you control via the mnemonic/key returned at create_wallet. To move funds out:

Import that mnemonic/key into any standard wallet for the chain (e.g. a Base/EVM wallet for base, a Stellar wallet for stellar).
Send the USDC wherever you like.

This is why the secret is shown once and must be saved: it is custody of the funds. If you didn’t save it, the platform cannot reissue it — keep deposits small and topped-up as needed rather than parking a large balance.

Security. Treat the mnemonic like a private key. Anyone with it can move the wallet’s funds. Never paste it into a tool result, a webpage, or a chat you don’t control.