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

## API payload

Use [POST `/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/withdrawals`](/products/custody/v1.36/reference/api/openapi/withdrawals/createwithdrawal)
to initiate a withdrawal:


```sh
curl -X POST "${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/withdrawals" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000000",
    "tickerId": "ticker-uuid",
    "ledgerId": "ledger-id",
    "destAddress": "destination-address"
  }'
```

| Field | Required | Description |
|  --- | --- | --- |
| `amount` | Yes | Positive integer string in the ticker's smallest unit. |
| `tickerId` | Yes | Ticker to withdraw. |
| `ledgerId` | Yes | Blockchain ledger to broadcast on. |
| `destAddress` | Yes | Destination address outside this omnibus. |


Successful requests return `201 Created` with a `withdrawal` object and an
`unsignedIntent`. Sign the returned Custody `Propose` intent and submit it to
`POST /v1/intents` in the `request` field.

The withdrawal object contains `operationId`, `transferId`, `status`, `amount`,
`tickerId`, `ledgerId`, `destAddress`, `createdAt`, and `updatedAt`. It can also
include `estimatedFee` and `custodyTransactionOrderId`. 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.36/transactions/overview) and [Transaction processing](/products/custody/v1.36/transactions/processing).

## Withdrawal fee handling

The source tenant's virtual account is debited 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.36/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.