# Omnibus

Executive summary
**Omnibus lets an organization hold pooled on-chain funds in a single custody account while tracking each tenant's share off-chain.**

- A single omnibus wallet holds accepted funds on-chain.
- Virtual accounts track tenant balances and movements off-chain.
- Dedicated deposit wallets identify incoming funds before Omnibus sweeps them into the omnibus wallet.
- Intra-omnibus transfers are off-chain and do not create blockchain transactions.
- Withdrawals and other on-chain movements still follow custody policies, approvals, and signing controls.


Why this matters
Omnibus reduces blockchain fees and settlement delays for high-volume pooled custody, trading, tokenization, asset-management, and repurchase-agreement workflows. Instead of creating and operating many segregated wallets, operators can pool accepted assets on-chain and use off-chain accounting to represent each tenant's position.

For architects and operators, Omnibus changes how you design domains, policies, fee sponsorship, and monitoring. Operators must monitor the on-chain balance of the omnibus wallet and the off-chain virtual account records together.

Current scope
This release does not support native assets, cross-chain liquidity, automatic tenant assignment for direct deposits to the omnibus wallet, or delivery of Omnibus events to external consumers. Omnibus currently supports non-native assets on Solana, XRPL, and EVM networks, constrained by Gas Station coverage.

## How Omnibus works

Omnibus scopes each structure to a Ripple Custody domain. The structure combines:

| Component | Purpose |
|  --- | --- |
| Omnibus wallet | Custody account that holds pooled funds on-chain. Withdrawals leave from this account. |
| Virtual accounts | Off-chain records that represent tenant positions in the pooled funds. The API uses `tenantId` and `/tenants` for these resources. |
| Host virtual account | First virtual account created with the omnibus structure. It holds unassigned funds and absorbs fee compensation. |
| Deposit wallets | Custody accounts dedicated to virtual accounts for external deposits. Omnibus sweeps funds into the omnibus wallet after confirmation and quarantine release. |
| Accounting Service | Source of truth for settled virtual account balances, statements, audit trail, and exports. |
| Gas Station | Fee funding for non-native token sweeps on supported Solana, XRPL, and EVM networks. |



```mermaid
flowchart LR
    External["External wallet"] -->|"Deposit"| DepositWallet["Deposit wallet"]
    DepositWallet -->|"Sweep after confirmation and quarantine release"| OmnibusWallet["Omnibus wallet"]
    OmnibusWallet -->|"Withdrawal"| Destination["External or same-instance destination"]

    subgraph Records["Off-chain virtual account records"]
        Host["Host virtual account"]
        TenantA["Tenant A virtual account"]
        TenantB["Tenant B virtual account"]
    end

    DepositWallet -. "Credits after sweep" .-> TenantA
    TenantA -. "Internal transfer" .-> TenantB
    Host -. "Fee compensation" .-> OmnibusWallet
```

## Common use cases

Use Omnibus when you need to:

- Hold assets for many tenants while minimizing the number of on-chain custody accounts.
- Give each tenant a dedicated deposit address while pooling accepted funds.
- Support instant, fee-free movements between virtual accounts in the same omnibus structure.
- Monitor a pooled blockchain balance against tenant-level off-chain positions.
- Sponsor sweep gas centrally rather than requiring every deposit wallet to hold native tokens.


## Omnibus vs. regular accounts

Regular Ripple Custody accounts are on-chain custody wallets. Balances, transactions, and policies attach directly to those accounts.

Omnibus adds an off-chain accounting layer. The omnibus wallet is still a regular custody account, but virtual accounts do not hold private keys or blockchain addresses themselves. They represent claims on pooled funds and can move value internally without creating blockchain transactions.

## Lifecycle

At a high level, an omnibus structure moves through these stages:

1. **Plan** the domain, Gas Station setup, Omnibus system-signed policy, and balance-monitoring model.
2. **Create** the omnibus structure and omnibus wallet through the normal intent flow.
3. **Configure automation** for deposit wallet creation, sweeps, and ledger propagation.
4. **Create virtual accounts** for tenants.
5. **Generate deposit wallets** lazily when a tenant requests deposit addresses.
6. **Operate** deposits, withdrawals, and internal transfers.
7. **Monitor** virtual account balances against the omnibus wallet and customer systems.


## Limitations

- A tenant is not a Ripple Custody user or domain. A virtual account represents the tenant's Omnibus position. Mapping users to tenants and virtual accounts is the customer's responsibility unless the Omnibus UI or customer integration enforces a stricter model.
- Omnibus can't automatically assign funds sent directly to the omnibus wallet to a specific tenant in this release. Omnibus credits those funds to the host virtual account after confirmation and quarantine release.
- Tenants must withdraw assets on the same ledger where they deposited them. Cross-chain liquidity is out of scope.
- Omnibus currently supports non-native assets on Solana, XRPL, and EVM networks only.
- The host virtual account can become negative when Omnibus compensates fees after deposits or withdrawals.
- Deposit wallets inherit ledgers from the omnibus wallet. Adding a ledger directly to a deposit wallet can cause sweeps to fail if the omnibus wallet cannot receive that ledger.


## Next steps

| Task | Documentation |
|  --- | --- |
| Plan setup and controls | [Setup and governance](/products/custody/accounts-and-assets/omnibus/setup-and-governance) |
| Understand deposits | [Deposits](/products/custody/accounts-and-assets/omnibus/deposits) |
| Understand withdrawals | [Withdrawals](/products/custody/accounts-and-assets/omnibus/withdrawals) |
| Move funds between virtual accounts | [Internal transfers](/products/custody/accounts-and-assets/omnibus/internal-transfers) |
| Review balances | [Balances](/products/custody/accounts-and-assets/omnibus/balances-and-reconciliation) |
| Manage omnibus | [Manage omnibus](/products/custody/accounts-and-assets/omnibus/manage-omnibus) |