加密货币充值（充值地址、链与币种）

概述

链上充值让您的用户通过区块链网络把加密货币转入 DCS 托管的充值地址，到账后计入用户在 DCS 的独立账户余额（availableBalance），即可用于绑定卡的消费。整个过程基于区块链网络完成，无需机构垫资中转。作为持牌发卡机构并拥有自有 BIN，DCS 负责链上监测、确认与记账，将「加密货币 → 可用余额 → 刷卡」连接成完整流程。本流程是：用户把加密货币打进来 → 平台监测确认 → 入账成为可用余额。核心三步：

调 GET /crypto/v1/network-coin 确认当前支持的链 + 币种 + 是否开启充值。
调 GET /crypto/v2/deposit-address（推荐）获取该用户在指定链/币种的充值地址。
用户向该地址转账 → 平台监测链上交易、达到确认数后入账 → 通过 WebSocket 推送状态。

前置条件

链上充值前，用户必须完成以下合规步骤，否则无法获取充值地址 / 无法入账：

前置条件	说明	入口
KYC 通过	用户身份验证须为通过态	见合规 · 概述
Travel Rule 完成	旅行规则合规信息须先提交	调 `POST /account/v1/update-travel-rule`；概念见旅行规则（Travel Rule）

方法说明：旅行规则更新用 POST /account/v1/update-travel-rule，查询用 GET /account/v2/query-travel-rule。

关键概念

链上模式

链上模式指用户直接通过区块链网络进行加密货币流转：向平台提供的链上地址转入（入金）。平台基于区块链交易哈希（txHash）实现全流程可追溯。

充值地址

平台为用户在「指定链 + 指定币种」上分配的收款地址。用户向此地址转入对应资产即视为向其 DCS 账户充值。

确认数

链上交易需要达到一定区块确认数才视为最终到账。每条链的最小确认数由 network-coin 配置返回（minConfirm），不同链不同。

API 流程

接口详解

前置步骤：完成旅行规则

此步骤已在前置条件中列出，属于充值流程开始前须完成的合规前置操作。此处给出完整请求示例供接入机构参考。

POST /account/v1/update-travel-rule

请求体（8 个顶层字段 + 6 个地址子字段，仅 externalUserId 必填，所有 PII 占位）：

{
  "externalUserId": "<DECARD_USER_ID>",
  "channelName": "<CHANNEL_NAME>",
  "institutionName": "<INSTITUTION_NAME>",
  "name": "<FULL_NAME>",
  "id": {
    "type": "<ID_TYPE>",
    "value": "<ID_VALUE>",
    "countryOfIssue": "SG"
  },
  "address": {
    "city": "<CITY>",
    "country": "SG",
    "dependentLocality": "<DISTRICT>",
    "postalCode": "<POSTAL_CODE>",
    "region": "<REGION>",
    "addressLines": "<ADDRESS_LINES>"
  },
  "dateOfBirth": "<YYYY-MM-DD>",
  "placeOfBirth": "<PLACE_OF_BIRTH>"
}

dateOfBirth（出生日期，格式 YYYY-MM-DD）、placeOfBirth（出生地）、address.dependentLocality（县/区名称）为可选合规字段，仅 externalUserId 必填。其余可选字段如 channelName、institutionName 的值由接入机构按需传入。查询接口（GET /account/v2/query-travel-rule）与 Travel Rule 背景见旅行规则（Travel Rule）。

第 1 步：确认支持的链 / 币种

GET /crypto/v1/network-coin?type=DEPOSIT

参数	位置	类型	必填	说明
`type`	query	string	✓	`DEPOSIT`（充值）/ `WITHDRAW`（提现）

返回当前用户钱包配置数组，充值场景应据此动态判断哪些链/币可用、确认数多少，而非硬编码静态清单。常用字段（data[]）：

字段	类型	说明
`network`	string	区块链网络标识
`networkNativeAsset`	string	网络原生资产
`asset`	string	币种代码
`depositEnable`	boolean	是否开启充值
`withdrawEnable`	boolean	是否开启提现
`minConfirm`	integer	充值最小确认数
`lockConfirm`	integer	锁定确认数
`estimatedArrivalTime`	integer	预计到账时间
`addressRegex`	string	地址校验正则
`memoRegex`	string	Memo/Tag 校验正则
`contractAddress`	string	合约地址（代币合约）
`depositDesc`	string	充值说明文案
`specialTips`	string	特别提示文案
`withdrawIsTag`	boolean	提现是否需要 Tag
`withdrawFee` / `withdrawMin` / `withdrawMax`	number	提现费/最小/最大（提现场景用）

充值前先调 network-coin 确认配置，再调 deposit-address。

第 2 步：获取充值地址

query 参数：

参数	位置	类型	必填	说明
`externalUserId`	query	string	✓	用户 ID
`network`	query	string	✓	区块链网络名称
`coin`	query	string	✓	币种代码

GET /crypto/v2/deposit-address — data 字段：

字段	类型	说明
`network`	string	区块链网络标识
`address`	string	充值地址
`fxRate`	number	汇率，用于币种转换
`coin`	string	币种代码
`status`	string (enum)	地址/分配状态：`PENDING` / `SUCCESS` / `FAILED`

fxRate（换汇汇率）用于展示折算金额，status 用于判断地址是否就绪。最小充值额与确认数不在本接口返回，可从 network-coin 的 minConfirm 等字段获取。

请求示例（占位/脱敏；鉴权头见接入资源 · 鉴权指南）：

curl -X GET "https://api.thedecard-sandbox.com/crypto/v2/deposit-address?externalUserId=usr_xxx&network=TRON&coin=USDT" \
  -H "X-DAPI-API-KEY: <YOUR_API_KEY>" \
  -H "X-DAPI-TIMESTAMP: 1760943263227" \
  -H "X-DAPI-NONCE: 12345" \
  -H "X-DAPI-SIGN: <YOUR_SIGNATURE>"

响应示例（v2，填充态，地址为占位）：

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": null,
  "data": {
    "network": "TRON",
    "address": "T...占位地址，请勿照抄...",
    "fxRate": 1.0,
    "coin": "USDT",
    "status": "SUCCESS"
  }
}

响应结构全站统一为 { code, message, messageDetail, data }（无 success 布尔）；messageDetail 通常为 null，需要时为对象 {message, title, type, icon, action, linkTitle, linkUrl}。成功码 code 字面量为 SYS_SUCCESS（两种模式一致）。

资金到账后会发生什么

用户转账：用户向充值地址转入对应链/币种的加密货币，链上产生交易哈希 txHash。
平台监测：DCS 监测区块链网络，等待交易确认数达到该链的 minConfirm / minConfirmationNo。
入账：达到确认数后，资金计入用户在 DCS 的账户余额（独立账户 availableBalance）。
WebSocket 推送：DCS 通过 WebSocket 实时推送交易状态变动通知（参见接入资源 · WebSocket 实时推送）。
机构查询：接入机构可随时调 GET /card/v1/fiat/transactions?externalUserId=... 查询充值/法币流水记录核对入账。

fiat/transactions 充值流水的链上明细在 transferDetails 子对象中，含字段：channelCode、txnAmt、txnCcy、sender、receiving、timeStamp、txHash、network、asset。

实时推送是「主动到账通知」；fiat/transactions 是「按需对账查询」。建议两者结合：以 WebSocket 触发 UI 更新，以 fiat/transactions 做最终对账。

到账时效：DPT 模式充值到账时间大概在 2 分钟左右（达到链上确认数后入账）。实际时效随链拥堵与确认数要求浮动，以 WebSocket 推送 / fiat/transactions 实际状态为准。

支持的链 / 币种矩阵

支持的链与币种以 GET /crypto/v1/network-coin?type=DEPOSIT 的实时返回为准，请勿硬编码静态清单（配置会随业务调整）。该接口会返回每条链/币种的 depositEnable、minConfirm、addressRegex、contractAddress 等。

关于具体取值：生产环境的链 / 币种以 GET /crypto/v1/network-coin 的动态配置为准，请勿硬编码静态清单。沙盒模拟接口实际接受的取值范围如需确认，请联系 DCS 团队。

沙盒模拟充值

测试链上充值入账流程时，可用模拟接口直接造一笔到账：

POST /simulation/v1/deposit

请求体（占位模板，请勿照抄具体链/币）：

{
  "chain": "",
  "currency": "",
  "amount": 0.0,
  "address": ""
}

填入时 address 用第 2 步获取的充值地址；chain / currency 的取值范围如需确认，请联系 DCS 团队。模拟充值仅沙盒可用，用于触发到账 / WebSocket 推送以验证您的对接。模拟接口与其它沙盒能力的整体说明见模拟交易。

错误处理

场景	说明	处理建议
旅行规则未完成	未先调 `update-travel-rule` 即取地址	先完成 `POST /account/v1/update-travel-rule`
KYC 未通过	用户身份验证未达通过态	引导用户完成 KYC，见合规 · 概述
链/币种不支持或未开启	`network`/`coin` 组合不在 `network-coin` 返回中，或 `depositEnable=false`	先调 `network-coin` 校验后再取地址
v2 地址 `status=PENDING`	充值地址尚在分配中	轮询直至 `SUCCESS` 再展示给用户；`FAILED` 时重试或联系支持
地址格式/Memo 不符	用户转账时地址或 Memo 不符合 `addressRegex`/`memoRegex`	前端按正则校验，必填 Memo 的链须提示用户带 Memo/Tag

完整错误码字典请向 DCS 团队索取；具体错误以接口返回的 code/message 为准。

下一步

加密货币提现见加密货币提现
实时到账通知见接入资源 · WebSocket 实时推送

​概述

​前置条件

​关键概念

​链上模式

​充值地址

​确认数

​API 流程

​接口详解

​前置步骤：完成旅行规则

​第 1 步：确认支持的链 / 币种

​第 2 步：获取充值地址

​资金到账后会发生什么

​支持的链 / 币种矩阵

​沙盒模拟充值

​错误处理

​下一步

概述

前置条件

关键概念

链上模式

充值地址

确认数

API 流程

接口详解

前置步骤：完成旅行规则

第 1 步：确认支持的链 / 币种

第 2 步：获取充值地址

资金到账后会发生什么

支持的链 / 币种矩阵

沙盒模拟充值

错误处理

下一步