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

# 加密货币提现

> DeCard 托管模式下链上加密货币提现的接口页：确认链币种（network-coin）与提现开关 → 发起链上提现（/crypto/v1/withdraw-apply，带短信验证）→ 通过资金流水查询到账，含短信校验、地址 Tag 与手续费说明。

## 概述

加密货币提现让您的用户把 DCS 托管账户内的可用余额（`availableBalance`），**通过区块链网络提取到指定的外部链上地址**。作为持牌发卡机构、自有 BIN，DCS 替您完成余额扣减、短信安全校验、链上转出与状态追踪，把「可用余额 → 链上到账」串联成一条完整流程。

与充值方向相反，本流程是：**用户发起提现 → 平台校验（含短信验证码）并扣减可用余额 → 链上转出到目标地址 → 通过资金流水查询到账**。

核心三步：

1. 调 `GET /crypto/v1/network-coin` 确认目标链/币种是否**开启提现**（`withdrawEnable`），并读取提现手续费与上下限（`withdrawFee` / `withdrawMin` / `withdrawMax`）、是否需要地址 Tag（`withdrawIsTag`）。
2. 引导用户获取**短信验证码**（`smsCode`，见 [前置条件](#前置条件)），调 `POST /crypto/v1/withdraw-apply` 发起提现。
3. 通过 `POST /user-asset/v1/transactions` 查询加密货币资金变动流水，跟踪本笔提现的链上状态与 `txHash`。

***

## 前置条件

调用本接口前请确认：

1. **用户已开户并通过 KYC**：用户已分配 `externalUserId`。参见[管理用户](../managing-users/overview)。
2. **目标链/币种已开启提现**：先查 `GET /crypto/v1/network-coin`，确认该 `network` + `coin` 的 `withdrawEnable = true`，并据 `withdrawIsTag` 判断是否必须携带 `addressTag`。
3. **可用余额足额**：用户 `availableBalance` 需 ≥ 提现金额 + 手续费。余额模型见 [账户与资产模型](../../basic-concepts/ledgering-system)。
4. **已完成短信验证**：提现是资金出口的高风险操作，需携带短信验证码 `smsCode`（通过 `POST /captcha/v1/send-mobile-code` 下发）。
5. **合规前置**：涉及旅行规则（Travel Rule）的场景，须先满足合规要求，见 [旅行规则（Travel Rule）](./travel-rule)。

## API 流程

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-withdraw-flow-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=a72963b26e13ca1fa7eae5dae2254ba8" alt="加密货币提现（Off-ramp）流程" width="560" height="572" data-path="imgs/diagrams/va-withdraw-flow-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-withdraw-flow-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=ab68d3e9a55bbbaf6c9a41dadb19b811" alt="加密货币提现（Off-ramp）流程" width="560" height="572" data-path="imgs/diagrams/va-withdraw-flow-dark.svg" />
</Frame>

## 发起提现

**`POST /crypto/v1/withdraw-apply`**

### 请求字段

| 字段               | 类型     | 必填   | 说明                                                                 |
| :--------------- | :----- | :--- | :----------------------------------------------------------------- |
| `externalUserId` | string | 是    | 外部用户 ID                                                            |
| `smsCode`        | string | 是    | 短信验证码，通过 `POST /captcha/v1/send-mobile-code` 下发                    |
| `network`        | string | 是    | 提现链，如 `TRON` / `ETH`（取值以 `network-coin` 返回为准）                      |
| `coin`           | string | 是    | 提现币种，如 `USDT` / `USDC`（取值以 `network-coin` 返回为准）                    |
| `name`           | string | 否    | 提现地址标签/收款方名称（用于地址备注/白名单）                                           |
| `address`        | string | 是    | 目标链上提现地址                                                           |
| `addressTag`     | string | 条件必填 | 地址 Tag / Memo；当 `network-coin` 的 `withdrawIsTag = true` 时必填        |
| `amount`         | number | 是    | 提现金额（须 > 0；上下限以 `network-coin` 的 `withdrawMin` / `withdrawMax` 为准） |
| `fee`            | number | 是    | 提现手续费（以 `network-coin` 的 `withdrawFee` 为准）                         |

> **金额精度**：请求体 `amount` / `fee` 为 number 类型。存储与展示时请注意链上代币精度，避免精度丢失。

### 请求示例（已脱敏）

```bash theme={null}
curl -X POST "{{dicard-server}}/crypto/v1/withdraw-apply" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_demo_001",
    "smsCode": "000000",
    "network": "TRON",
    "coin": "USDT",
    "name": "my-wallet",
    "address": "T-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "addressTag": "",
    "amount": 100.0,
    "fee": 1.0
  }'
```

> **鉴权**：上例为聚焦业务字段省略了鉴权头，实际调用必须携带 `X-DAPI-API-KEY` / `X-DAPI-SIGN` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE`（HMAC-SHA256 签名），规则统一见 [鉴权指南](../../integration-resources/overview)，本页不重复正文。

<Warning>
  所有示例值均为占位符。**切勿**在请求或日志中写入真实的链上地址、`externalUserId`、`smsCode`、金额或任何持卡人个人信息、API Key/Secret。链上地址与用户标识属敏感区，务必脱敏处理。
</Warning>

### 响应

响应使用全站统一结构 `{ code, message, messageDetail, data }`（**无 `success` 布尔字段**）。成功时 `code = SYS_SUCCESS`，表示提现请求已受理。

> 业务判定请以资金流水中的实际状态为准，不要仅凭结构 `code = SYS_SUCCESS` 即认为提现已到账——`code` 只代表请求被成功受理，链上转出为异步过程。

## 查询提现进度

链上提现受理后，通过 **`POST /user-asset/v1/transactions`**（查询加密货币资金变动流水）跟踪本笔提现，读取链上状态与交易哈希 `txHash`；单笔明细可用 `POST /user-asset/v1/transaction-detail`。字段定义见 [用户余额](../managing-transactions/user-balance) 与 [报告字段说明](../managing-transactions/reporting-field-descriptions)。

## 状态与到账时效

* **受理成功不等于到账**：结构 `code = SYS_SUCCESS` 只代表 DCS 已受理并扣减余额；资金真正到达目标地址以链上确认为准。
* **到账时效取决于链上确认速度**：不同链的出块与确认数不同，请以 `network-coin` 的确认数配置与目标链实际网络状况为准。

## 错误处理

| 情况                        | 处理建议                                                                                                                     |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------- |
| 响应 `code` 非 `SYS_SUCCESS` | 请求未被受理：按 `message` 校验请求参数（`smsCode` 是否有效/过期、`network`/`coin` 是否开启提现、`address`/`addressTag` 是否合法、`amount` 是否在上下限内、余额是否足额） |
| 短信验证码无效/过期                | 引导用户重新获取 `smsCode`（`send-mobile-code`）后重试                                                                                |
| 该链/币种未开启提现                | `network-coin` 返回 `withdrawEnable = false`：提示用户当前不可提现，改用已开启的链/币种                                                         |
| 需要 Tag 但未填                | `withdrawIsTag = true` 的链必须携带 `addressTag`，否则可能到账失败或丢失资金                                                                 |
| 余额不足                      | 可用余额 \< 提现金额 + 手续费：提示用户充值或减少提现金额                                                                                         |

## 最佳实践

1. **先查 `network-coin` 再提现**：以 `withdrawEnable` / `withdrawFee` / `withdrawMin` / `withdrawMax` / `withdrawIsTag` 为准做前端校验，减少无效请求与到账失败。
2. **强制地址与 Tag 校验**：在用户填写阶段就按链规则校验地址格式与 Tag，`withdrawIsTag = true` 时 Tag 必填——链上地址错误或 Tag 缺失可能导致资金不可找回。
3. **短信验证不可省**：提现为资金出口，务必走 `smsCode` 二次校验。
4. **以链上状态判到账**：受理成功不等于到账，向用户提示「已到账」前请以资金流水中的链上确认状态为准。
5. **PII 最小化**：链上地址、用户标识属敏感信息，日志脱敏、按合规要求最小化留存。

## 下一步

* [加密货币充值](./crypto-deposit)——反方向资金流（链上充值到可用余额），与本页共用 `network-coin` 链币种矩阵
* [旅行规则（Travel Rule）](./travel-rule)——提现涉及的合规前置
* [用户余额](../managing-transactions/user-balance)——`free` / `freeze` / `total` 余额语义与资金流水查询
* [账户与资产模型](../../basic-concepts/ledgering-system)——`availableBalance` / `frozenBalance` 余额模型
* [鉴权指南](../../integration-resources/overview)——HMAC-SHA256 签名头统一说明