> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Crypto Withdrawal

> Withdraw crypto from a merchant's VelaFi custody wallet to an address on your withdrawal whitelist.

Use this endpoint to send crypto from a merchant's VelaFi wallet to another address. The destination must already be on your withdrawal address whitelist. Before you call it, use [Get Withdrawal Quota](https://docs.velafi.com/api-reference/crypto-wallet/get-withdrawal-quota.md) to find the valid `chainType` values and the minimum amount.

> [!NOTE]
>
> All requests must include the `X-BH-TOKEN` header with a business token from `GET /v2/token/generate`, and `Content-Type: application/json`.

## Endpoint

`POST https://api.velafi.com/v2/assets/withdraw`

## Request Parameters

**merchantId** `number` *required*

ID of the merchant whose wallet is debited.

**clientId** `string` *required*

Your unique identifier for this withdrawal. Reusing a `clientId` from an earlier withdrawal of the same kind (external or VelaFi destination) for this merchant is rejected with `Duplicate withdrawal request`.

**crypto** `string` *required*

Token symbol, for example `USDT`.

**chainType** `string` *required*

Network name, for example `TRC20`. Use a `chainType` returned by Get Withdrawal Quota. It must match the `chainType` of the whitelist entry for this address. A missing or non-matching value makes the request fail.

**address** `string` *required*

Destination address. It must be on your whitelist.

**addressTag** `string`

Memo or tag, for networks that use one. It must match the `addressTag` of the whitelist entry.

**cryptoAmount** `number` *required*

Amount to withdraw. It must be greater than `0`. For external addresses, see the amount rules under Validation and Behavior.

**remark** `string`

Free-text note stored with the withdrawal.

## Response Fields

**code** `number`

`200` indicates success.

**msg** `string`

`SUCCESS` on success.

**data** `object`

**data fields**

**orderId** `number`

ID of the withdrawal record.

The `needBrokerAudit` and `refuseReason` fields in `data` are not populated by this endpoint.

## Example

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/assets/withdraw \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 151209,
    "clientId": "withdraw-0001",
    "crypto": "USDT",
    "chainType": "TRC20",
    "address": "YOUR_WHITELISTED_ADDRESS",
    "cryptoAmount": 100,
    "remark": "supplier payout"
  }'
```

## Validation and Behavior

> [!WARNING]
>
> The request is rejected unless your whitelist has an active entry that matches the `address`, `chainType` and `addressTag` and covers this `crypto`. Whitelist entries belong to your API user, so they apply to every merchant under it. Account-level controls, such as a withdrawal freeze, can also reject a request to a whitelisted address.

* **Crypto limit.** The withdrawal counts toward the merchant's crypto limit. A request that would exceed the limit is rejected.
* **External addresses.** These rules apply only when the destination is not a VelaFi wallet address:
  * The amount is truncated to the token's decimal precision.
  * The amount must be greater than the network fee. Otherwise the request fails with `The quantity cannot be less than the handling fee`.
  * If the token has a minimum (`minCryptoAmount` greater than `0`), the amount must be at least that minimum. Otherwise the request fails with `Order amount is too small`.
  * If the token has a maximum single withdrawal amount, a larger amount fails with `The quantity cannot exceed the maximum quantity`.
  * If on-chain withdrawals are disabled on the network (`allowWithdraw` is `false` in Get Withdrawal Quota), the request fails with `Withdrawals are temporarily unavailable due to system maintenance.`
* **VelaFi destination addresses.** If the destination is a VelaFi wallet address, no on-chain transaction is made. The withdrawal is booked as an internal transfer with a zero network fee. It appears in [Crypto Transfer History](https://docs.velafi.com/api-reference/merchant/query-crypto-transfers.md).

> [!NOTE]
>
> To be notified of the final status, subscribe to [Crypto Withdrawal Event](https://docs.velafi.com/api-reference/webhooks/crypto-withdraw-message-push.md). VelaFi sends it when the withdrawal succeeds, fails, or is cancelled. You can also poll [Get Crypto Withdrawal History](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md) with your `clientId` until `status` is `6` (successful), `7` (failed) or `9` (cancelled). A withdrawal to a VelaFi wallet address appears in [Crypto Transfer History](https://docs.velafi.com/api-reference/merchant/query-crypto-transfers.md) instead. Don't keep the user's balance locked on your side indefinitely while you wait: reconcile pending withdrawals against Get Crypto Withdrawal History and apply a timeout.


## Related topics

- [Crypto Withdrawal Event](https://docs.velafi.com/api-reference/webhooks/crypto-withdraw-message-push.md)
- [List Crypto Withdrawals](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [Get Withdrawal Quota](https://docs.velafi.com/api-reference/crypto-wallet/get-withdrawal-quota.md)
- [Create a Crypto Transfer](https://docs.velafi.com/api-reference/merchant/crypto-transfer.md)
- [Changelog](https://docs.velafi.com/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.