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

# 创建加密货币提现

> 将加密货币从商户的 VelaFi 托管钱包提现至提现白名单中的地址。

使用此端点将加密货币从商户的 VelaFi 钱包发送至其他地址。目标地址必须已在您的提现地址白名单中。调用前，请先使用[获取提现额度](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-withdrawal-quota.md)查询有效的 `chainType` 值和最低金额。

> [!NOTE]
>
> 所有请求都必须在 `X-BH-TOKEN` 请求头中携带通过 `GET /v2/token/generate` 获取的业务令牌，并设置 `Content-Type: application/json`。

## 端点

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

## 请求参数

**merchantId** `number` *required*

被扣款钱包所属商户的 ID。

**clientId** `string` *required*

您为此次提现设置的唯一标识符。如果该商户此前同类提现（外部地址或 VelaFi 目标地址）已使用过某个 `clientId`，重复使用将被拒绝并返回 `Duplicate withdrawal request`。

**crypto** `string` *required*

代币符号，例如 `USDT`。

**chainType** `string` *required*

网络名称，例如 `TRC20`。请使用获取提现额度返回的 `chainType`。它必须与该地址白名单条目的 `chainType` 一致。缺失或不匹配都会导致请求失败。

**address** `string` *required*

目标地址。必须在您的白名单中。

**addressTag** `string`

Memo 或标签，适用于需要使用它的网络。必须与白名单条目的 `addressTag` 一致。

**cryptoAmount** `number` *required*

提现金额。必须大于 `0`。对于外部地址，请参阅“校验与行为”中的金额规则。

**remark** `string`

随提现记录保存的自由文本备注。

## 响应字段

**code** `number`

`200` 表示成功。

**msg** `string`

成功时为 `SUCCESS`。

**data** `object`

**data 字段**

**orderId** `number`

提现记录的 ID。

此端点不会填充 `data` 中的 `needBrokerAudit` 和 `refuseReason` 字段。

## 示例

```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"
  }'
```

## 校验与行为

> [!WARNING]
>
> 除非您的白名单中存在与 `address`、`chainType` 和 `addressTag` 匹配且涵盖该 `crypto` 的有效条目，否则请求将被拒绝。白名单条目归属于您的 API 用户，因此适用于其下的所有商户。账户级别的管控（例如提现冻结）也可能拒绝发送至白名单地址的请求。

* **加密货币限额。** 提现金额计入商户的加密货币限额。超出限额的请求将被拒绝。
* **外部地址。** 以下规则仅在目标地址不是 VelaFi 钱包地址时适用：
  * 金额会按代币的小数精度截断。
  * 金额必须大于网络手续费，否则请求失败并返回 `The quantity cannot be less than the handling fee`。
  * 如果代币设有最低金额（`minCryptoAmount` 大于 `0`），金额必须不低于该最低值，否则请求失败并返回 `Order amount is too small`。
  * 如果代币设有单笔最大提现金额，超出该金额的请求将失败并返回 `The quantity cannot exceed the maximum quantity`。
  * 如果该网络已禁用链上提现（获取提现额度中 `allowWithdraw` 为 `false`），请求将失败并返回 `Withdrawals are temporarily unavailable due to system maintenance.`
* **VelaFi 目标地址。** 如果目标地址是 VelaFi 钱包地址，则不会发起链上交易。该提现将记为内部划转，网络手续费为零，并显示在[加密货币划转记录](https://docs.velafi.com/cn/api-reference/merchant/query-crypto-transfers.md)中。

> [!NOTE]
>
> 如需获取最终状态通知，请订阅[加密货币提现事件](https://docs.velafi.com/cn/api-reference/webhooks/crypto-withdraw-message-push.md)，VelaFi 会在提现成功、失败或被取消时发送该事件。您也可以使用您的 `clientId` 轮询[加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)，直到 `status` 为 `6`（成功）、`7`（失败）或 `9`（已取消）。提现到 VelaFi 钱包地址的操作则显示在[加密货币划转记录](https://docs.velafi.com/cn/api-reference/merchant/query-crypto-transfers.md)中。等待期间，请勿在您的系统中无限期锁定用户余额：请通过加密货币提现记录接口核对处理中的提现，并设置超时。


## Related topics

- [加密货币提现事件](https://docs.velafi.com/cn/api-reference/webhooks/crypto-withdraw-message-push.md)
- [获取加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [获取提现额度](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-withdrawal-quota.md)
- [创建加密货币划转](https://docs.velafi.com/cn/api-reference/merchant/crypto-transfer.md)
- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)


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