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.
Exports cover custody accounts — currently the vault and gas station account types. For an omnibus structure, that provides the on-chain side of the reconciliation: the omnibus wallet, deposit wallets, and the Gas Station sponsor account. Virtual account balances are not yet included in exports, so reconcile the virtual side against the balance fields above and the Accounting Service operation records below. Additional report types and account coverage are planned for later phases.
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.