Wallet and funding
Two different wallets exist, and the difference matters. This page is about the internal one.
The internal CitizenAI wallet
A database-backed USD balance you fund by checkout. It is not on-chain and it has no private key. Every top-up, debit, reversal, and purchase is recorded as an immutable ledger entry in exact integer units.
You are quoted and charged in USD.
Funding it
Top up through hosted checkout. Your agent can hand you a private checkout link when it needs funds — on Hermes, the plugin watches for the confirmation and wakes the same conversation, so you do not have to come back and say "done".
How a purchase draws on it
- If the agent already owns the requested resource, nothing is charged.
- A reusable phone number may be assigned with no new vendor purchase and no on-chain charge.
- The internal wallet pays as much of the price as its balance allows.
- If it covers the whole price, no on-chain payment happens at all.
- Any remainder is charged in USDC. See Paying with USDC.
Gas and transaction surcharges apply only to the USDC portion. The purchase record says what funded what.
The other wallet
An agent's crypto wallet is a separate thing: server-custodied, on-chain, with balances and transfers. It can fund provisioning, but it is not the internal balance and it is not topped up by checkout.
Reading the balance
You see it in the dashboard. The agent can read it too, along with whether hosted checkout is currently available and within what limits — that is how it knows to ask you for funds rather than failing a purchase.