# Withdrawals

Omnibus withdrawals move funds from a tenant's virtual account balance to an external destination by sending an on-chain transaction from the omnibus wallet.

Withdrawals concentrate loss-of-funds risk, so they follow the normal custody intent, policy, approval, signing, and broadcast flow.

## Withdrawal flow

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

    Client->>Omnibus: Request withdrawal
    Omnibus->>Accounting: Get virtual account available balance
    Omnibus->>Omnibus: Check available minus reserved balance
    Omnibus->>Omnibus: Reserve amount
    Omnibus->>Custody: Dry-run transaction order
    Omnibus-->>Client: Withdrawal and unsignedIntent
    Client->>Client: Sign unsignedIntent
    Client->>Custody: POST /v1/intents with signed request
    Custody-->>Omnibus: Transaction order events
    Omnibus->>Accounting: Record OMNIBUS WITHDRAWAL
    Omnibus->>Omnibus: Release reservation
```

The withdrawal request includes `amount`, `tickerId`, `ledgerId`, and `destAddress`. The amount is a positive integer string in the ticker's smallest unit.

The Omnibus response includes the withdrawal operation and an unsigned Custody `Propose` intent. The client signs the intent and submits the signed payload to `POST /v1/intents` in the `request` field. Omnibus tracks confirmation asynchronously through the generated custody transaction order.

## Procedures

To initiate a withdrawal, see [Initiate a withdrawal](/products/custody/v1.38/accounts-and-assets/omnibus/manage-omnibus-api#initiate-a-withdrawal) in the API procedures, or [Withdraw](/products/custody/v1.38/accounts-and-assets/omnibus/manage-omnibus-ui#withdraw) in the console procedures. Withdrawal status values are `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`, and `CANCELLED`.

## Balance reservation

When a client initiates a withdrawal, Omnibus reserves the amount locally before submitting the on-chain transaction. This prevents another withdrawal or internal transfer from using the same virtual account balance while the first withdrawal is in flight.

The available amount for a new withdrawal is:

```text
Accounting available balance - local reserved balance
```

The Accounting Service remains the source of truth for settled available balances. Omnibus local state tracks only transient reservations and quarantined deposits.

## Policy and signing

Withdrawals move funds on-chain and follow the same governance model as other custody transactions:

- Omnibus dry-runs the withdrawal intent before submission.
- Omnibus returns an unsigned intent payload to the client.
- The initiating user signs the payload and submits it to Custody.
- Domain policies determine whether the request needs additional approvals.
- Compliance controls can apply according to the domain's configuration.
- The request continues through the Notary and vault signing flow.


For the general transaction lifecycle, see [Transactions](/products/custody/v1.38/transactions/overview) and [Transaction processing](/products/custody/v1.38/transactions/processing).

## Withdrawal fee handling

Omnibus debits the source tenant's virtual account for the withdrawal amount. Network-fee handling depends on the asset being withdrawn:

| Withdrawal type | Fee behavior |
|  --- | --- |
| Native asset withdrawal | The host virtual account is responsible for the native network transaction fee in Omnibus accounting. |
| Non-native token withdrawal | Gas Station funds the native gas required for the withdrawal on supported Solana, XRPL, and EVM networks. |


Fee compensation or reimbursement records for Gas Station-funded non-native withdrawal gas depend on the final Omnibus accounting behavior for your release. Confirm this behavior before relying on host virtual account fee balances for non-native withdrawals.

## Same-instance destinations

Transfers from the omnibus wallet to another wallet in the same Ripple Custody instance follow the withdrawal flow:

- Funds leave the omnibus wallet on-chain.
- Omnibus reserves the source virtual account balance.
- Domain policies apply.
- The client notarizes and signs the operation.
- Fee handling follows the same native-asset or non-native token behavior as other withdrawals.


Use [sending assets](/products/custody/v1.38/transactions/send-and-receive/sending-assets) for ordinary account-to-account custody transfers. Use Omnibus withdrawals when the source is a tenant's virtual account in an omnibus structure.

## Cancellations and failures

If the returned custody intent is rejected, expires, is cancelled before
broadcast, or fails before confirmation:

- Omnibus releases the local reservation.
- The Accounting Service records no settled `WITHDRAWAL` entry.
- The virtual account available balance remains unchanged.


After the transaction confirms on-chain, use Accounting Service reversal or correction processes for later corrections rather than editing the original ledger entry.

## Ledger restrictions

This release does not support cross-chain liquidity. Tenants must withdraw balances on the same ledger where they deposited them.

For example, a tenant who deposits USDC on Arbitrum must withdraw that USDC on Arbitrum.