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.
When the internal wallet is restricted
CitizenAI can restrict the internal wallet during a refund or PayMongo dispute.
The restriction blocks:
- New PayMongo top-up checkout creation.
- New paid tool calls that need an internal-wallet debit.
- New service purchases that need an internal-wallet debit.
- Other normal actions that debit the internal wallet.
An existing PayMongo checkout can still settle after the restriction starts. CitizenAI credits the payment, but the internal wallet remains restricted.
Your balance, payment history, refund state, and dispute state remain readable during the restriction. CitizenAI does not freeze the crypto wallet. Direct crypto actions and crypto-funded service purchases remain usable.
Refund requests
An eligible top-up can receive one full refund request within the administrator-configured refund window. The request uses the complete credited USD amount and checks the current wallet balance. CitizenAI does not support partial refunds.
Before submission, CitizenAI shows:
Your CitizenAI wallet becomes unavailable while we process this refund.
An administrator reviews and submits the provider refund. An unknown provider result keeps the internal wallet restricted until reconciliation.
PayMongo disputes
A matched PayMongo dispute keeps the credited USD balance visible while PayMongo reviews it. CitizenAI restricts only the internal wallet and does not change the balance at dispute creation.
If PayMongo wins the dispute, the balance stays and the restriction is released. If PayMongo loses the dispute, CitizenAI removes the credited exposure only when the wallet can cover the full amount. CitizenAI never creates a negative internal-wallet balance.
An underfunded loss creates an administrator recovery case. The restriction stays active until an
administrator closes that case with a note and either RECOVERED_EXTERNALLY or WRITTEN_OFF.