Skip to main content
User funded is the default flow of funds. Every connected user has their own Agentcard balance: they top it up with Apple Pay or Google Pay, and when their agent creates a card, the amount comes out of that balance. Your organization is never in the money path — no pool to prefund, no collections to confirm, no treasury to reconcile.
The flow of funds is chosen when you create the company (user funded or company balance). A company owner can switch models from the dashboard’s Company balance page, but only until the company first moves money (a card is funded, a transfer runs, or a deposit lands). After that the two models’ funds would mix on the same collateral, so the choice locks; to change it then, create a new organization or contact us.

​
The flow of funds

User-funded flow of funds diagram

User funded: from create_card to the agent paying the merchant

Step by step, for one card:
  1. A connected user’s agent calls create_card. If the user’s balance covers the amount (plus fees), the card mints immediately and the agent pays the merchant.
  2. If the balance is short, create_card returns wallet_funding_required. The agent calls add_funds, which returns a secure checkout link — the user pays with Apple Pay, Google Pay, or card in their browser, in USD. Funding reuses the identity verification the user already completed to create cards, so there’s no extra step.
  3. While the deposit settles, create_card returns deposit_confirming — the agent waits the suggested interval and retries. No second payment is ever needed.
  4. The card mints, card.created fires, and the agent pays the merchant as usual. Unused balance from a closed card stays in the user’s balance for their next card.

​
What your integration looks like

Almost nothing. The funding conversation happens entirely between the user’s agent and Agentcard — your backend provisions cardholders, mints buy tokens, and listens to webhooks, but never handles a funding step. In create_card terms this is funds_source: "onramp_flow", the default, so agents never need to pass it.

​
Balance tools

These run in the user’s own MCP session (via Connect with Agentcard):

​
Funding from your own UI (API)

If you’re building an embedded funding experience — your app shows the balance and an “Add funds” button — the same flow is available server-to-server on the v2 API, so the user never leaves your product: See the Funding a wallet guide for the full server-to-server flow, including the embedded in-app checkout. All three endpoints work in test mode too: sandbox connect identities get a simulated balance whose funding sessions settle by themselves, so you can rehearse the whole loop before going live — see User wallet in test mode.

​
Funding with USDC directly

If you already hold USDC — say you’re paying a user a commission or reward they earned through your platform — you can skip the checkout entirely and send it straight to the user’s balance. Every verified user’s wallet is a real address on Base: USDC sent to it becomes their spending power, spendable on cards and withdrawable through their normal balance tools. There is no fee and no markup — what you send is what they get. The contract:
  1. The user must be verified first. Deposit addresses activate when identity verification approves — wait for identity.verification.updated with status: "approved" before sending. Funds sent earlier sit at the address untouched until the user completes verification; nothing is lost, but nothing settles either.
  2. Read the address fresh from GET /api/v2/wallet each time — don’t cache it in your database. The response’s address is the deposit address.
  3. Send USDC on Base only, at least $1 per transfer. Other tokens or networks are not credited.
  4. Settlement takes a few minutes (typically under 15): the deposit is detected, moved into the user’s spending collateral, and credited. Your confirmation is the user_wallet.funded webhook — user_id plus the settled amount_usdc — or poll GET /api/v2/wallet and watch spending_power_usdc rise. Your on-chain transaction hash is your receipt for the send itself.
This is the same rail the checkout uses — direct deposits and card payments land in the same balance and follow the same settlement. Per-payout bookkeeping (which transfer paid which reward) stays on your side today: correlate by user and amount, with your tx hash as the anchor.
Direct deposits are live-mode only — test-mode identities have no on-chain address (address is null). Rehearse the equivalent flow in test mode with funding sessions, which settle themselves.

​
When to choose it

Pick user funded when your users are the ones spending their own money — consumer agents, personal assistants, anything where “the user pays for what the agent buys” is the natural model. If instead you bill your customers and want to fund their cards from one pooled balance with your billing in the loop, use the company balance.