Omnibus balance views combine settled balances from the Accounting Service with transient Omnibus state for reservations and quarantined deposits.
| Data | Source | Meaning |
|---|---|---|
availableBalance | Accounting Service | Settled virtual account balance available for withdrawal or internal transfer. |
reserved | Omnibus local state | Amount held for pending withdrawals or other in-flight operations. |
quarantined | Omnibus local state | Deposits detected on deposit wallets but not yet available. |
| Omnibus wallet balance | Custody account balance | On-chain balance held in the omnibus wallet. |
| Deposit wallet balance | Custody account balance | Pending or unswept funds held outside the omnibus wallet. |
The Accounting Service is the source of truth for settled virtual account balances. Omnibus local balances are operational overlays for pending states.
| Event | Available balance | Reserved | Quarantined | Host virtual account |
|---|---|---|---|---|
| Deposit detected on deposit wallet | No change | No change | Increases | No change |
| Deposit confirmed but below dust threshold | No change | No change | No change | No change |
| Deposit swept and recorded | Increases | No change | Decreases | No change |
| Deposit sweep fee compensation | No change | No change | No change | Decreases by fee |
| Withdrawal initiated | No change | Increases | No change | No change |
| Withdrawal confirmed | Decreases | Decreases | No change | No change |
| Native-asset withdrawal fee | No change | No change | No change | Decreases by fee |
| Withdrawal cancelled | No change | Decreases | No change | No change |
| Internal transfer | Source decreases, destination increases | No change | No change | No change |
| Direct deposit to omnibus wallet | No change | No change | No change | Increases after confirmation |
Omnibus creates the host virtual account with the omnibus structure. The host virtual account represents:
- Unassigned funds sent directly to the omnibus wallet.
- Fee compensation for deposit sweeps.
- Native-asset withdrawal fees.
Because Omnibus records host-funded fees after settlement, the host virtual account can become negative. Monitor this balance and define an operational process for topping it up or investigating fee drift. Fee compensation or reimbursement records for Gas Station-funded non-native withdrawal gas depend on the final Omnibus accounting behavior for your release.
The Portfolio Data Export Service generates reconciliation-grade Position Reports (point-in-time balance snapshots) and Movement Reports (transaction history for a date range) as CSV or JSON files with request metadata and control totals.
With omnibus support enabled for your environment, the Position Report labels the omnibus wallet omnibus and the deposit wallets deposit wallet, and excludes virtual account balances, so it gives you the on-chain side of the reconciliation: the omnibus wallet, deposit wallets, and the Gas Station sponsor account. The Omnibus Position Report gives you the virtual side in the same shape: every virtual account balance, mapped to its deposit wallet and parent omnibus wallet, with the host virtual account and its possible negative balance included. Per asset, the sum of virtual account available balances equals the omnibus wallet total.
Without omnibus support, exports cover the vault and gas station account types only, and virtual account balances aren't available through exports. In that case, reconcile the virtual side against the balance fields above and the Accounting Service operation records below. See Omnibus support.
Omnibus relies on the Accounting Service for immutable settled operation records, virtual account statements, and exports.
Omnibus operation records preserve enough context to trace:
- The custody event or transaction that triggered a balance change.
- The virtual account credited or debited.
- The source and destination virtual accounts for internal transfers.
- The related operation for fee compensation.
- The custody account and transaction references for on-chain movement.
For broader custody data-integrity concepts, see Data integrity and governance.