> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet

> Fund an on-chain agent wallet, let your agents pay for Buy services from it within agent card limits, approve the payments that need it, and withdraw what is left.

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.

> [!WARNING]
>
> **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](https://www.x402.org) service on [Buy](https://usebuy.ai), 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](https://docs.agentvault.io/dashboard/api-keys.md#pay-from-the-agent-wallet-with-chosen-cards),
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](https://docs.agentvault.io/dashboard/agent-cards.md#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](#govern-it-with-agent-cards).

## 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](#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.

> [!NOTE]
>
> 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](https://docs.agentvault.io/dashboard/agent-cards.md).
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:

| Limits shows | What it means |
| - | - |
| **No limits** | No agent card governs the wallet. Once you approve a seller on Buy, it pays that seller any amount without asking again, unless the connection asks before every purchase. Click **Add limits** |
| A count of agent cards | Each payment is governed by the agent cards that allow its seller |
| **Paused** | No agent card can pay right now, so the wallet refuses payments. Click **Resume** on an agent card to let it pay again. One that paused at its limit stays paused until you resume it: first raise the limit, or wait for a daily, weekly or monthly limit to reset. A per-payment limit never resets, so raise it or pay less |

**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.

> [!NOTE]
>
> 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](https://docs.agentvault.io/dashboard/destinations.md) (approving
  it on the [Marketplace](#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](https://docs.agentvault.io/dashboard/destinations.md) 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:

| Status | What it means |
| - | - |
| **Waiting for you** | The payment needs your approval before anything is paid |
| **Approved, not paid yet** | You approved it. The agent sends it on its next call; until then nothing moves |
| **Being settled** | The payment is held or sent, and still settling |
| **Paid** | The seller was paid |
| **Released, not paid** | The hold was released. Nothing was paid |
| **Not paid: the approval ran out** | You approved it, but the agent did not pay within 15 minutes. Nothing was paid |
| **Refused: ...** | A control stopped it: an agent card's limit, merchant rule or pause, the account pause, or the plan's payment quota. Nothing was paid |
| **Declined** / **Declined: the approval ran out** | You declined it, or did not answer in time |

## 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:

| Shows | What it means |
| - | - |
| **Asks you first** | The first payment to it asks you to approve the seller. Click **Approve** to approve it now |
| **Approved** | The seller is approved, so a payment to it does not ask about the seller. Click **Revoke** to remove that approval. The next payment asks again unless something else still approves the seller, and then it shows what does |
| **Approved via** ... | Approved by a broader destination or an agent card's merchant list on the wallet. Change it there |
| **Approved in Destinations** | Approved by another source, such as a saved login. See [Destinations](https://docs.agentvault.io/dashboard/destinations.md) for which one |
| **Not payable** | Your agents cannot pay this provider through Agent Vault |

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](https://docs.agentvault.io/dashboard/approvals-and-notifications.md).

## For developers

The agent side of wallet payments is one tool or endpoint:

* MCP: [`pay_request`](https://docs.agentvault.io/mcp/tool-reference#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`](https://docs.agentvault.io/reference/http-api#wallet-payments-preview).
* HTTP: [`POST /v1/wallet/pay`](https://docs.agentvault.io/reference/http-api#wallet-payments-preview) 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](https://docs.agentvault.io/dashboard/api-keys.md#pay-from-the-agent-wallet-with-chosen-cards)
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`](https://docs.agentvault.io/mcp/tool-reference#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](https://docs.agentvault.io/sdk/error-codes.md#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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.