# 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/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/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/compliance/transaction-screening/concept).

## 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. Omnibus deployment values commonly expose per-ticker thresholds as `MIN_SWEEP_AMOUNT_<TICKER>` entries, expressed in the ticker's smallest unit:


```yaml
omnibus:
  dustThresholds:
    MIN_SWEEP_AMOUNT_USDC: "1000000"
```

The exact key format depends on your deployment package. For deployment-level configuration, see [Omnibus reference](/products/custody/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.

## 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, or a custody API failure.