# 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.

## Deposit-wallet model

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`](/products/custody/v1.38/reference/api/openapi/deposits/createdepositwallet).
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`](/products/custody/v1.38/reference/api/openapi/deposits/getdepositwallet) 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.

```mermaid
sequenceDiagram
    actor Client
    participant Omnibus as Omnibus Service
    participant Custody as Custody API

    Client->>Omnibus: POST virtual-account deposit-wallet
    Omnibus->>Omnibus: Check for existing deposit wallet
    alt Wallet exists
        Omnibus-->>Client: Existing wallet and addresses
    else Wallet does not exist
        Omnibus->>Custody: System-signed CreateAccount intent
        Custody-->>Omnibus: AccountCreated event
        Omnibus->>Custody: Get addresses
        Custody-->>Omnibus: Addresses
        Omnibus-->>Client: New wallet status and addresses
    end
```

## Deposit processing

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.

| Stage | What happens | Balance effect |
|  --- | --- | --- |
| Deposit detected | Omnibus detects an incoming transaction on a deposit wallet. | Local `quarantined` balance increases. |
| Confirmation and quarantine check | Omnibus waits for blockchain confirmation and compliance quarantine release. | Funds remain pending. |
| Dust threshold check | Omnibus checks whether the sweep amount is large enough to sweep. | Below-threshold deposits remain pending on the deposit wallet. |
| Sweep | Omnibus submits a system-signed sweep from the deposit wallet to the omnibus wallet. | Funds move on-chain into the omnibus wallet. |
| Accounting entry | Omnibus records an `OMNIBUS` `DEPOSIT` entry. | Accounting available balance increases. |
| Fee compensation | Omnibus records sweep fee compensation against the host virtual account. | Host virtual account balance decreases and can become negative. |


```mermaid
stateDiagram-v2
    [*] --> Quarantined: TransactionDetected
    Quarantined --> PendingSweep: Confirmed and unquarantined, below dust threshold
    Quarantined --> Sweeping: Confirmed and unquarantined, above threshold
    PendingSweep --> Sweeping: Later deposits exceed threshold
    Sweeping --> Available: Sweep confirmed and Accounting entry recorded
    Quarantined --> [*]: Expired or replaced
```

## Quarantine and compliance

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](/products/custody/v1.38/compliance/transaction-screening/concept).

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](/products/custody/v1.38/compliance/transaction-screening/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](/products/custody/v1.38/compliance/transaction-screening/concept#skip-quarantine-for-internal-transfers).


## Dust thresholds

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](/products/custody/v1.38/accounts-and-assets/omnibus/manage-omnibus-api#manage-sweep-thresholds) in the API procedures, or [Set sweep thresholds](/products/custody/v1.38/accounts-and-assets/omnibus/manage-omnibus-ui#set-sweep-thresholds) in the console procedures. Deployment packages can also expose per-ticker defaults — see [Omnibus reference](/products/custody/v1.38/deployment/reference/omnibus#configuration-fields).

## Gas Station funding

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.

## XRPL IOU readiness

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.

## Direct deposits to the omnibus wallet

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.

## Failure handling

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](#xrpl-iou-readiness)).