加密货币提现 - DCS Technical Documentation

概述

加密货币提现让您的用户把 DCS 托管账户内的可用余额（availableBalance），通过区块链网络提取到指定的外部链上地址。作为持牌发卡机构、自有 BIN，DCS 替您完成余额扣减、短信安全校验、链上转出与状态追踪，把「可用余额 → 链上到账」串联成一条完整流程。与充值方向相反，本流程是：用户发起提现 → 平台校验（含短信验证码）并扣减可用余额 → 链上转出到目标地址 → 通过资金流水查询到账。核心三步：

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

前置条件

调用本接口前请确认：

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

API 流程

发起提现

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 类型。存储与展示时请注意链上代币精度，避免精度丢失。

请求示例（已脱敏）

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 签名），规则统一见鉴权指南，本页不重复正文。

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

响应

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

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

查询提现进度

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

状态与到账时效

受理成功不等于到账：结构 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`，否则可能到账失败或丢失资金
余额不足	可用余额 < 提现金额 + 手续费：提示用户充值或减少提现金额

最佳实践

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

下一步

加密货币充值——反方向资金流（链上充值到可用余额），与本页共用 network-coin 链币种矩阵
旅行规则（Travel Rule）——提现涉及的合规前置
用户余额——free / freeze / total 余额语义与资金流水查询
账户与资产模型——availableBalance / frozenBalance 余额模型
鉴权指南——HMAC-SHA256 签名头统一说明

​概述

​前置条件

​API 流程

​发起提现

​请求字段

​请求示例（已脱敏）

​响应

​查询提现进度

​状态与到账时效

​错误处理

​最佳实践

​下一步

概述

前置条件

API 流程

发起提现

请求字段

请求示例（已脱敏）

响应

查询提现进度

状态与到账时效

错误处理

最佳实践

下一步