Deposits

Omnibus deposits use dedicated deposit wallets. A tenant receives one deposit wallet through a virtual account, and that wallet provides deposit addresses for the ledgers supported by the omnibus wallet.

Omnibus makes funds available to the tenant's virtual account only after the blockchain confirms them, compliance releases them from quarantine, Omnibus sweeps them into the omnibus wallet, and the Accounting Service records them.

Omnibus creates deposit wallets lazily:

1. A client requests a deposit wallet for a virtual account with POST /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/deposit-wallet.
2. If a deposit wallet already exists, Omnibus returns the existing wallet and addresses.
3. If no deposit wallet exists, Omnibus creates one by submitting a system-signed v0_CreateAccount intent.
4. The new deposit wallet inherits the ledgers activated on the omnibus wallet.
5. Omnibus returns the wallet status and any generated addresses.

Use GET /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/deposit-wallet to retrieve the wallet status and addresses later.

Deposit-wallet create requests return 201 Created when Omnibus creates a wallet and 200 OK when the virtual account already has a deposit wallet.

Deposit wallet responses contain depositWalletId, custodyAccountId, status, and addresses. Status values are CREATING, ACTIVE, and INACTIVE; each address entry contains ledgerId and address.

This endpoint is a direct Omnibus API call. It does not return an unsigned intent for the caller to sign. Configure the Omnibus system-signed policy during setup so deposit-wallet creation can complete without a separate user-signed proposal for each virtual account request.

This keeps tenant onboarding lightweight. A new virtual account does not need deposit wallets for every ledger until a tenant requests a deposit address.

After an external sender sends funds to a deposit wallet, the deposit follows the normal custody transaction detection and compliance flow. Omnibus monitors the resulting custody events and processes the deposit.

The existing custody compliance layer handles compliance screening. Omnibus does not perform transaction screening itself.

Omnibus waits until:

• The blockchain confirms the transaction.
• Compliance releases all value transfers for the deposit from quarantine.

Only then does Omnibus sweep the funds and credit them as available. For related concepts, see Transaction screening.

For fully automated operation, configure two things yourself; Omnibus configures skip quarantine on the omnibus wallet only, not on deposit wallets:

• An automatic quarantine release policy that covers external deposits, so confirmed deposits release without manual action and the sweep proceeds.
• skipQuarantineFrom on each deposit wallet, set manually after Omnibus creates the wallet, so internal transfers that arrive at the deposit wallet are not quarantined. Gas Station gas funding and XRPL reserve prefunding are internal transfers of this kind: they prefund the deposit wallet and never pass through the sweep flow, so without this setting each one quarantines and waits for a release. See Skip quarantine for internal transfers.

Very small deposits may cost more to sweep than they are worth. Omnibus supports minimum sweep thresholds per ticker.

If a confirmed, unquarantined deposit is below the configured threshold:

• The funds remain on the deposit wallet.
• The virtual account's local quarantined balance remains.
• A later deposit can push the cumulative unswept amount above the threshold.
• Omnibus then sweeps the cumulative amount.

Configure thresholds to balance customer experience, fee cost, and operational clarity. Thresholds are keyed by ticker and ledger pair, expressed in the ticker's smallest unit, and apply per domain. Assets without a configured threshold default to "0", which sweeps immediately.

To set thresholds, see Manage sweep thresholds in the API procedures, or Set sweep thresholds in the console procedures. Deployment packages can also expose per-ticker defaults — see Omnibus reference.

For non-native token sweeps, the deposit wallet may need native tokens to pay gas. If Gas Station sponsors the deposit wallet, it can fund the required gas just in time on supported Solana, XRPL, and EVM networks.

Gas Station funding transactions appear as incoming transactions on deposit wallets. Omnibus uses an ignored-account list to avoid treating those funding transactions as customer deposits.

The create Omnibus request accepts ignoredAccountIds; include the Gas Station account ID when you create the omnibus structure. The current Omnibus update request changes sponsoringGasStationId, but does not accept ignoredAccountIds, so verify the returned omnibus details after any sponsor change.

An XRPL account must hold an XRP reserve that grows with the number of objects the account owns: the base reserve (currently 1 XRP) plus an owner reserve (currently 0.2 XRP) for each owned object. Every trustline you create for an IOU adds an owned object, and other setup can add objects too. Each object raises the deposit wallet's required reserve.

If you want a deposit wallet to hold or transfer IOUs (tokens), complete all IOU setup before the first deposit reaches that wallet:

1. Create the TrustSet for each IOU and currency the wallet holds.
2. Enable rippling where your use case requires it.
3. Confirm the authorization and freeze state of each trustline.
4. Complete any other setup the account needs to transfer IOUs.

Do not interleave this setup with deposit activity. Omnibus estimates the reserve a sweep must leave behind when it prepares the sweep. If a TrustSet lands while a native XRP sweep is in flight, the estimate can miss the new trustline's owner reserve, the sweep can leave the wallet below its required reserve, and the sweep's Payment transaction fails on-chain with tecUNFUNDED_PAYMENT. Failed XRPL transactions still burn the network fee, so each failed attempt leaves the wallet slightly shorter until you top it up.

Before you rely on native XRP sweeps, confirm the deposit wallet holds enough XRP to cover its base reserve plus the owner reserve for every object it owns. You can prefund the deposit wallet directly from the Gas Station sponsor account.

This release cannot automatically assign funds sent directly to the omnibus wallet to a specific tenant. When Omnibus detects an external direct deposit to the omnibus wallet:

1. It waits for confirmation and quarantine release.
2. It credits the host virtual account.
3. Operators can later redistribute funds using an internal transfer or return funds through a withdrawal.

Use tenant deposit addresses for normal deposit flows.

If a sweep fails after retries:

• The deposit remains pending.
• The local quarantined balance stays in place.
• Operators must investigate the deposit wallet, ledger support, Gas Station funding, policy behavior, and custody transaction status.

Common causes include insufficient gas sponsorship, ledger mismatch between deposit wallet and omnibus wallet, Omnibus system-signed policy misconfiguration, a custody API failure, or an XRPL deposit wallet left below its required reserve by IOU setup that ran during deposit activity (see XRPL IOU readiness).