> For the complete documentation index, see [llms.txt](https://docs.omypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omypayments.com/api/api-endpoints/withdrawals.md).

# Withdrawals

Send funds from your merchant assets to on-chain addresses and track each withdrawal to completion. This page documents the HTTP endpoints you’ll call from your backend. Authentication and the error-envelope format follow the public API style.

> **Base URL**: `https://api.omypayments.com`\
> **Version**: `v1` (all endpoints below start with `/1.0/...`)\
> **Auth**: add your API key in the header: `apiKey: <yourApiKey>`\
> **Permission**: the API key must have the **withdrawal** permission enabled, otherwise requests are rejected with `403 Forbidden`. Listing withdrawals additionally accepts the **invoice** permission.

**Prerequisites**

* API withdrawals must be enabled for your merchant account (otherwise `400` with `API withdrawals are currently inactive`).
* `amount` is expressed in the token’s base units (integer string, no decimal point). For a token with 6 decimals, `100` = `"100000000"` — see `crypto.decimals` on the “Get Merchant Asset Data” endpoint to convert.
* Each withdrawal must meet the per-crypto **minimum USD amount**, and the asset must have enough available balance to cover `amount` plus the system fee (for API withdrawals the fee is always paid by the sender).
* The destination `address` is optional: if omitted, the asset’s **default wallet** is used. The address must be valid for the asset’s network and — when a **whitelist** is enabled for your merchant — must be whitelisted. Destinations are also screened against our AML policy.

**Typical flow**

1. `asset-withdrawal` (reserves funds, starts processing)
2. `asset-withdrawal-info` and/or `asset-withdrawals` and/or callbacks to track status.

**Withdrawal statuses**

| Status    | Meaning                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------ |
| `pending` | Withdrawal created, funds reserved from the available balance, awaiting/processing the on-chain send.              |
| `success` | Withdrawal sent on-chain; `txHash` is populated.                                                                   |
| `failed`  | Withdrawal was declined or the transaction was reverted; the reserved funds are returned to the available balance. |

***