# Withdrawing funds

Product: Client Trade API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/trade-api/concepts/withdrawing-funds

A withdrawal moves funds from an Axiym account to a
[address book entry](/trade-api/concepts/address-book).
The Axiym account supplies the balance, and the bank account or wallet from
the client's address book receives the outgoing payment.

Unlike a deposit, a withdrawal is initiated through the Client Trade API. It
uses a two-step create-and-confirm flow: creation returns a
`PENDING_CONFIRMATION` withdrawal, and confirmation begins execution.

Third-party withdrawals are not supported.

## The three parts of a withdrawal

| Part                 | Role                                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| Source Axiym account | Holds the balance from which funds are withdrawn. Identified by `sourceAccountId`.                          |
| Address book entry   | The owned bank account or wallet that receives the payment. Identified by `destinationId`.                  |
| Withdrawal           | The outgoing payment record created and tracked through the Client Trade API. Identified by `withdrawalId`. |

These resources must belong to the same represented client. The source
Axiym account and address book entry must also use the same currency.

## Before creating a withdrawal

Confirm that:

* the external bank account or wallet is registered to the same client;
* the address book entry is `ACTIVE`;
* its currency matches the source Axiym account;
* a wallet uses the intended blockchain network; and
* the source Axiym account is active and has sufficient balance for
  `sourceAmount`.

Registering an external account does not move funds. It creates the reusable
record referenced by `destinationId`.

## Creating a withdrawal



```mermaid
flowchart LR
  source["Axiym account (sourceAccountId)"] -->|amount| external["Address book entry (destinationId)"]
```



Create the withdrawal using `sourceAccountId`, `destinationId`, and `sourceAmount`
to debit. Use an idempotency key so the request can be retried safely without
creating another withdrawal. Include `supportingDocuments` when required by
the destination corridor.

The fee is deducted from `sourceAmount`. The recipient receives
`destinationAmount`, which equals `sourceAmount` less `fee`.

For example, a USD withdrawal must use a USD Axiym account and an active USD
external bank account. A USDT withdrawal must use a USDT Axiym account and an
active USDT external wallet on the configured network.

The response contains the new `withdrawalId`, status `PENDING_CONFIRMATION`, amount, fee, and
the address book entry details used for that payment. The embedded
details record where the specific withdrawal was instructed to go;
`destinationId` remains the reusable reference to the registered account.

## Confirming a withdrawal

Confirm the returned `withdrawalId` with
`POST /clients/{clientId}/withdrawals/{withdrawalId}/confirm`. The request has
no body and requires a new idempotency key. Confirmation changes the withdrawal
to `PENDING` and begins execution.

Creation and confirmation are distinct operations and use distinct idempotency
keys. If either response is lost, retry that exact operation with its original
key.

## Withdrawal lifecycle

Do not infer the next status from the current one. Use webhook events or
retrieve the withdrawal again to observe changes.

| Status                 | Meaning                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `PENDING_CONFIRMATION` | The withdrawal was created and awaits explicit confirmation. Execution has not begun.            |
| `PENDING`              | The withdrawal was accepted and is awaiting execution.                                           |
| `HELD`                 | Processing is temporarily on hold. Continue monitoring the withdrawal for a later status change. |
| `COMPLETED`            | The outgoing payment completed.                                                                  |
| `CANCELED`             | The withdrawal was canceled before completion.                                                   |
| `REJECTED`             | The withdrawal was rejected and did not complete.                                                |

A canceled or rejected withdrawal can include a `reasonCode`. A completed
wallet withdrawal can include a blockchain `transactionHash`.

## Withdrawal record and account balance

The withdrawal represents the outgoing payment and its processing status. The
source Axiym account represents the balance held with Axiym.

Use `externalReference` to associate the withdrawal with your own payment,
invoice, or treasury record. The withdrawal also receives an Axiym-generated
payment `code`.

Use the withdrawal for the business status, amount, fee, and payment details.
Use the source Axiym account statement to reconcile the posted debit and
running balance.

## Common mistakes

* Passing an `accountId`, bank account number, or raw wallet address as
  `destinationId`.
* Mixing identifiers from different clients.
* Retrying creation or confirmation without its original idempotency key.

The [Idempotency](/trade-api/integration-guide/fundamentals/idempotency) guide
explains how to retry funds-moving requests safely.