Skip to main content

Fund a wallet

An agent wallet pays in USDC, so it needs USDC on its own network. You can fund it by sending USDC you already hold, by buying USDC with a bank card, by asking a teammate to do it, or from your organization multisig treasury, available from the Growth plan. A new account may also receive a Keyban welcome offer that pays the first x402 payments. Where the money sits and who signs is explained in Funding sources; the networks are in Networks and assets.

From the dashboard​

Open Agent Wallets, then the wallet. The page has a Top up menu. Which entries it shows depends on your rights, on the network of the wallet and on whether card top-ups are enabled for your account.

Send USDC you already hold​

This works for any wallet and any network. The wallet's address is known as soon as the wallet is created, even before the agent has connected, and a banner on a new empty wallet shows it with a copy button.

  1. Copy the wallet address from the wallet page.
  2. Send USDC to it on the wallet's network, for example Base mainnet for a wallet created on Base mainnet.

The balance is read from an indexer that lags the blockchain by a few seconds. If it has not moved yet, use the refresh control next to the balance.

Buy USDC with a card​

The By card entry buys USDC through Stripe Link and delivers it to the wallet's address.

  • It runs on Base mainnet only. On a wallet of another network the entry is disabled with the note "Base mainnet only", and on a wallet that is not deployed yet with "Not deployed yet".
  • Each purchase is between 5 and 999 euros.
  • It needs the update right on agent wallets (Owner and Admin), and card top-ups must be enabled for your account. If the entry is missing, one of the two is not met.
  • The organization must have accepted Keyban's terms. Until it has, the purchase is refused with LEGAL_ACCEPTANCE_REQUIRED; the guided setup shows the terms in its Accept our legal documents screen. A verified e-mail address is not needed for a card purchase.

The dialog walks you through four steps: the amount, Stripe Link, the payment, and the tracking of the purchase.

  1. Enter an amount in euros. The dialog shows an estimate of the USDC you will receive, based on the current rate and Stripe fees, so the amount delivered may differ slightly.
  2. Enter the e-mail of your Stripe Link account. Stripe sends a one-time code to it. If no Link account exists for that address, the dialog asks for a country and a phone number and creates one.
  3. Complete the identity verification if Stripe asks for it: your identity details, then an ID document and a selfie. It is a one-time check tied to the Link e-mail. If Stripe rejects it, the dialog tells you whether you can try again.
  4. Pay, then follow the purchase. You can close the dialog and come back: your progress is kept.

The card purchase is made by a person. The agent has no tool to buy funds. Completed purchases appear in the wallet's recent movements as "Card top-up".

Ask a teammate for a top-up​

If you can run the wallet but cannot top it up yourself, use Request a top-up. It is shown to people with the operate right on the wallet who do not hold the treasury top-up right.

  1. Optionally type an amount, in your display currency, and a note.
  2. Send the request. It lands in the Inbox of the people who manage the treasury, who are also notified by e-mail.

A wallet can have one open request at a time; the menu then reads Top-up requested and takes you to the request. The request stays open until a treasury manager declines it (with an optional reason), you cancel it with Cancel my request, or it is fulfilled: either a treasury transfer delivered the requested amount, or a treasury manager marked it as handled, for example after a card top-up.

Top up from the organization treasury​

If your organization has a treasury, a member who holds the treasury top-up right sees From the treasury in the menu, and can also refill a wallet from the Inbox when answering a request. The treasury is available from the Growth plan; see Multisig treasury.

The Keyban welcome offer​

A new account can receive a small USDC credit, granted for your first agent wallet on Base, that pays x402 payments for a limited time. It does not put USDC in the wallet: Keyban pays the seller itself from a Keyban sponsor wallet, and the amount is deducted from the offer.

  • It covers a payment only when the whole price fits in what is left of the offer. A bigger payment is paid entirely from the wallet, never in two parts.
  • It applies only to x402 payments of the wallet that earned it, on the network of the offer, before it expires.
  • It pays only an agent that declares the sponsored-x402 capability. The Keyban wallet MCP declares it on its own, so there is nothing to configure. A custom agent that does not declare it is never covered, and its payments come from the wallet.
  • The spending policy applies to these payments like any other.
  • It is granted when the wallet is created, but it pays only once the organization has accepted Keyban's terms. Until then, a payment the offer would cover is refused with policy/terms-not-accepted, and the wallet's own USDC does not pay in its place. Accept the terms in the dashboard, then the agent retries.
  • It is not guaranteed: it depends on the offer still being available when the wallet is created. The wallet page shows what is left and when it expires, and the offer appears once in the expense history as a row without an amount.

Warm wallet Coming soon​

A warm wallet Coming soon is planned to make topping up smoother. It is not available yet.

What the agent can do​

The agent can see what it has, and tell the user how to fund it. It cannot add funds.

ToolUse
balanceThe wallet's balance, led by its value in the display currency, with the welcome offer as its own line when one is active.
get_account_infoThe wallet address and network, plus the welcome offer while it lasts.

When the offer is active, the agent should tell the user that payments are covered up to the remaining amount, and not that the wallet needs funding. When the wallet is empty and no offer applies, the agent should give the user the address and the network from get_account_info, and suggest the dashboard. An assistant using the admin tools of the Keyban MCP server, after keyban admin login, can read the same figures with get_wallet_balance and get_wallet_welcome_offer; see the Admin tools. All the tools are listed on the Wallet MCP tools page.

Limits​

  • The wallet pays in USDC. Other assets that reach its address are left out of the expense totals and of the expense history.
  • Card top-ups: Base mainnet only, between 5 and 999 euros per purchase, through Stripe Link, when enabled for your account.
  • The welcome offer pays x402 payments on Base mainnet only. x402 payments themselves also work on XDC mainnet, from the wallet's own USDC. See Networks and assets and x402 protocol.
  • One open top-up request per wallet.
  • Every payment from the funded wallet still goes through its spending policy, and a paused wallet refuses all of them.