Skip to main content
The Wallet page gives your agents a funding source that is not a bank card: an on-chain wallet you top up, so they can pay for the online services they call. You fund it, choose which agent cards govern it, approve the payments that need it, and withdraw the balance while the wallet is active.
Agent wallets are a preview. The Wallet entry shows in the sidebar when your account and deployment have it turned on, and it stays visible if you have already set up a wallet, so you can still withdraw from it while it is active. Otherwise the page reads Wallets are not available on this account yet. Check the network the page shows before you send anything: on the sandbox network, balances and payments are test values; on mainnet they are real funds.

What the agent wallet is

The agent wallet is a crypto wallet that Agent Vault creates and holds the key for. You fund it with stablecoins. Your agents can then pay for an x402 service on Buy, a pay-per-call API marketplace. The wallet pays for API calls sold on Buy, not for website checkouts. Agent Vault makes the paid request on the agent’s behalf: your agents can pay from the wallet, but they never get the key or sign a payment. Only you can withdraw. An account has one wallet. An agent that may pay from it sees it once in its token catalog, as Agent wallet, however many agent cards govern it. A connection or key limited to chosen cards sees it only once you let it pay from the agent wallet, and one that fills a test card never does.

Set up your wallet

Open Wallet under Vault in the sidebar. Set up your agent wallet lists the terms under Before you set it up:
  • Custody: Agent Vault keeps the wallet’s key safe for you.
  • Payments are final: a payment on Buy cannot be reversed from here.
  • Supported tokens: the tokens and network the wallet takes.
Tick I understand and accept these terms and click Set up wallet. Agent Vault creates the wallet and its address, and you get a wallet_created notification. If none of your agent cards governs a card you still have (for example, you have no agent card yet, or only one whose card you deleted), setup also creates the Default agent card on the wallet, when your plan has room for another agent card, so its limits govern payments from the start. If an agent card already governs one of your cards, the wallet starts with No limits until you give an agent card access.

Fund it

The top of the page shows three panels:
  • Balance: what the wallet holds, and when it was last read. Click Refresh to read it again; it does not update on its own.
  • Address: the wallet’s address and its network, Celo or Celo Sepolia. Click Receive for the full address and a QR code of it.
  • Limits: which agent cards govern the wallet. See Govern it with agent cards.
Send the tokens the page lists to the address from any wallet or exchange. On Celo that is USDC, USDT or USAT; on the Celo Sepolia sandbox it is test USDC. No CELO is needed for fees. On the sandbox, Receive also shows Test funds: Buy’s faucet sends 1 test USDC to the address.
Send only the tokens the page lists, on the network it names. Other tokens sent to the wallet cannot be withdrawn.

Govern it with agent cards

Every agent card with access to the wallet governs its payments. Its spending limits, merchant rules and approval amount apply to wallet payments as they do to card fills. When several agent cards have access and the agent pays with the wallet itself:
  • a payment is allowed when an active one allows its seller,
  • every one of them that allows its seller and that you have not paused counts it against its limits, so another card’s cap can refuse a payment,
  • the lowest approval amount among the active ones that allow its seller asks you first.
When the agent pays with one agent card’s own number instead, only that card’s pause, merchant rules and approval amount apply. The spending limits of the other cards that allow the seller still count the payment, unless you paused them; one stopped at its limit still counts. An agent card can have a card, the wallet, or both. With both, one set of limits counts card fills and wallet payments together. Turn the wallet on for an agent card with Pay from the agent wallet on its page, or tick Also pay from the agent wallet when you create one. See Agent cards. If that agent card allows only listed merchants, turning the wallet on also adds sellers.usebuy.ai to its list, unless an entry already covers it, so it allows every seller on Buy. Each new seller still asks you once. On the Wallet page, Limits shows the state: Add limits gives an existing agent card access to the wallet (Add wallet access), or click New agent card instead to create one for it. Once one has access, Agent cards on this wallet lists each with its Limits, the amount it Asks you above, and its Status. Click Add another agent card to add more.
A wallet with No limits still asks you before it pays a seller your account has not approved yet, and before every payment from a connection or key set to ask before every purchase. No spending cap or approval amount applies until an agent card governs it.

Approve a payment

A wallet payment asks you first when:
  • It goes to a seller on Buy your account has not approved yet. A seller is approved when it is on Destinations (approving it on the Marketplace or in a prompt adds it there), when you have a saved login for it, or when an active agent card on the wallet that allows only listed merchants lists it. An active agent card with a card that allows only listed merchants counts too when its list names usebuy.ai, which covers every seller on Buy. A paused or limit-stopped card’s list, and a blocklist, approve no seller. You see Your agent wants to pay the amount to the provider, named as provider (via Buy). Approving allows that seller from now on and lets your agent make that one payment when it calls again; nothing moves until it does. Any agent card limits still apply.
  • It is at or over the approval amount. When the agent pays with the wallet itself, that is the lowest approval amount among the active agent cards on the wallet that allow the seller. When it pays with one agent card’s own number, only that card’s approval amount counts. You get A wallet payment is waiting for your approval, naming the seller, the amount and the token.
  • The connection or key is set to ask before every purchase.
Otherwise it goes ahead without you. Nothing is paid while you decide. When you approve a payment that asked about its amount, or because the connection asks before every purchase, your agent can make that payment once within 15 minutes. Approving only the seller does not run out: the seller stays approved until you revoke it, and your agent can pay when it calls again, under the same agent card limits. Approved sellers show on Destinations as provider (via Buy), where you can revoke them.

Activity

Activity has two lists, Payments and Withdrawals. Payments keeps each payment with When, Paid to, Amount, Status and Transaction. An amount under a cent shows its digits, such as $0.0044. A payment shows one of these statuses:

Marketplace

Once the wallet is set up, on an account with the marketplace turned on, the page has a second tab, Marketplace: the services your agents can pay for from the wallet, grouped by provider, with Buy’s list prices. Search the services, filter by All, Approved or Asks first, or by platform. A retired wallet keeps the tab, but only as a catalog: it makes no payments, so your agents cannot pay anything listed there. Each provider shows whether your agents can pay it: Approving a provider approves only the seller. The exact amount, the agent cards’ limits and approval amounts, and a connection set to ask before every purchase still apply when your agent pays.

Withdraw

Click Withdraw to move funds to an address you control. Enter the To address as a 0x address of 40 hex characters, all lowercase or with a correct checksum, pick the Token, and enter the Amount, or Max for the balance less the fee cap. Click Review withdrawal, check the address, and confirm. The network fee is paid in the token you withdraw, from the wallet, and has a small cap the page shows. A withdrawal cannot be reversed, and funds sent to an address you do not control cannot be recovered. If no answer comes back, click Send again: the same withdrawal is never sent twice. Withdrawals under Activity shows each one as Starting, Sent, waiting to confirm, Being checked, Confirmed, Failed, nothing sent or Expired, nothing sent. You get wallet_withdrawal notifications as it moves through its stages. A retired wallet makes no payments.

Notifications

Two wallet notifications are always on and cannot be switched off:
  • wallet_created, when the wallet is set up.
  • wallet_withdrawal, as a withdrawal moves through its stages.
See Approvals and notifications.

For developers

The agent side of wallet payments is one tool or endpoint:
  • MCP: pay_request pays a Buy route and returns its answer. It is listed on the hosted and self-run servers for an account with wallet payments on, except on a self-run server whose API key fills a test card.
  • SDK: payRequest makes the same call from the Playwright SDK. Its fields are on POST /v1/wallet/pay.
  • HTTP: POST /v1/wallet/pay on the proxy.
The agent pays with the wallet’s handle, av_wallet_<userId>, from the token catalog’s wallets. Until the agent can pay, the catalog lists no wallets. When the next step is yours, its walletNote names it: set the wallet up, or, for a connection or key limited to chosen cards, tick pay from the agent wallet for it. A key that fills the test card gets a note to use one with real cards. A retired wallet, or an account without wallet payments, gets no walletNote. When a payment needs your approval, nothing is paid until you approve it:
  • Over MCP, pay_request keeps running and answers pending with a wait id. The agent tells the user, then keeps calling get_pending_result in the same turn; the original call pays once you approve.
  • Over HTTP and the SDK, the first call comes back pending; after you approve it, the agent calls again with the same idempotencyKey to complete it.
The refusal codes, and whether retrying each is safe, are on Wallet payments; the endpoint can also reject a malformed or oversized request (bad_request, request_too_large, invalid_resource, invalid_envelope). A payment that was sent is checked again with the same key, never paid again with a new one unless that check answers payment_released.