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.
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 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.
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.
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 a0x 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.
For developers
The agent side of wallet payments is one tool or endpoint:- MCP:
pay_requestpays 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:
payRequestmakes the same call from the Playwright SDK. Its fields are onPOST /v1/wallet/pay. - HTTP:
POST /v1/wallet/payon the proxy.
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_requestkeeps running and answerspendingwith a wait id. The agent tells the user, then keeps callingget_pending_resultin 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 sameidempotencyKeyto complete it.
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.