> ## 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）→ 获取充值地址（deposit-address）→ 用户转账并计入余额，同时列出支持的网络和币种、确认数与沙盒模拟充值方式。 ## 概述 链上充值让您的用户通过区块链网络把加密货币转入 DCS 托管的充值地址，到账后计入用户在 DCS 的独立账户余额（`availableBalance`），即可用于绑定卡的消费。整个过程基于区块链网络完成，无需机构垫资中转。作为持牌发卡机构并拥有自有 BIN，DCS 负责链上监测、确认与记账，将「加密货币 → 可用余额 → 刷卡」连接成完整流程。 本流程是：**用户把加密货币打进来 → 平台监测确认 → 入账成为可用余额**。 核心三步： 1. 调 `GET /crypto/v1/network-coin` 确认当前支持的链 + 币种 + 是否开启充值。 2. 调 `GET /crypto/v2/deposit-address`（推荐）获取该用户在指定链/币种的充值地址。 3. 用户向该地址转账 → 平台监测链上交易、达到确认数后入账 → 通过 **WebSocket** 推送状态。 *** ## 前置条件 链上充值前，用户必须完成以下合规步骤，否则无法获取充值地址 / 无法入账： | 前置条件 | 说明 | 入口 | | ------------------ | ------------ | ------------------------------------------------------------------------------ | | **KYC 通过** | 用户身份验证须为通过态 | 见 [合规 · 概述](../../basic-concepts/compliance-kyc-flow) | | **Travel Rule 完成** | 旅行规则合规信息须先提交 | 调 `POST /account/v1/update-travel-rule`；概念见 [旅行规则（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 占位）： ```json theme={null} { "externalUserId": "", "channelName": "", "institutionName": "", "name": "", "id": { "type": "", "value": "", "countryOfIssue": "SG" }, "address": { "city": "", "country": "SG", "dependentLocality": "", "postalCode": "", "region": "", "addressLines": "" }, "dateOfBirth": "", "placeOfBirth": "" } ``` > `dateOfBirth`（出生日期，格式 YYYY-MM-DD）、`placeOfBirth`（出生地）、`address.dependentLocality`（县/区名称）为可选合规字段，仅 `externalUserId` 必填。其余可选字段如 `channelName`、`institutionName` 的值由接入机构按需传入。查询接口（`GET /account/v2/query-travel-rule`）与 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` 等字段获取。 **请求示例**（占位/脱敏；鉴权头见 [接入资源 · 鉴权指南](../../integration-resources/overview)）： ```bash theme={null} curl -X GET "https://api.thedecard-sandbox.com/crypto/v2/deposit-address?externalUserId=usr_xxx&network=TRON&coin=USDT" \ -H "X-DAPI-API-KEY: " \ -H "X-DAPI-TIMESTAMP: 1760943263227" \ -H "X-DAPI-NONCE: 12345" \ -H "X-DAPI-SIGN: " ``` **响应示例**（v2，填充态，地址为占位）： ```json theme={null} { "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`**（两种模式一致）。 *** ## 资金到账后会发生什么 1. **用户转账**：用户向充值地址转入对应链/币种的加密货币，链上产生交易哈希 `txHash`。 2. **平台监测**：DCS 监测区块链网络，等待交易确认数达到该链的 `minConfirm` / `minConfirmationNo`。 3. **入账**：达到确认数后，资金计入用户在 DCS 的账户余额（独立账户 `availableBalance`）。 4. **WebSocket 推送**：DCS 通过 **WebSocket 实时推送**交易状态变动通知（参见 [接入资源 · WebSocket 实时推送](../../integration-resources/webhook-websocket)）。 5. **机构查询**：接入机构可随时调 `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 ``` 请求体（占位模板，请勿照抄具体链/币）： ```json theme={null} { "chain": "", "currency": "", "amount": 0.0, "address": "" } ``` > 填入时 `address` 用第 2 步获取的充值地址；`chain` / `currency` 的取值范围如需确认，请联系 DCS 团队。 > 模拟充值仅沙盒可用，用于触发到账 / WebSocket 推送以验证您的对接。模拟接口与其它沙盒能力的整体说明见 [模拟交易](../simulating-transactions/overview)。 *** ## 错误处理 | 场景 | 说明 | 处理建议 | | ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | | 旅行规则未完成 | 未先调 `update-travel-rule` 即取地址 | 先完成 `POST /account/v1/update-travel-rule` | | KYC 未通过 | 用户身份验证未达通过态 | 引导用户完成 KYC，见 [合规 · 概述](../../basic-concepts/compliance-kyc-flow) | | 链/币种不支持或未开启 | `network`/`coin` 组合不在 `network-coin` 返回中，或 `depositEnable=false` | 先调 `network-coin` 校验后再取地址 | | v2 地址 `status=PENDING` | 充值地址尚在分配中 | 轮询直至 `SUCCESS` 再展示给用户；`FAILED` 时重试或联系支持 | | 地址格式/Memo 不符 | 用户转账时地址或 Memo 不符合 `addressRegex`/`memoRegex` | 前端按正则校验，必填 Memo 的链须提示用户带 Memo/Tag | > 完整错误码字典请向 DCS 团队索取；具体错误以接口返回的 `code`/`message` 为准。 *** ## 下一步 * 加密货币提现见 [加密货币提现](./withdraw-offramp) * 实时到账通知见 [接入资源 · WebSocket 实时推送](../../integration-resources/webhook-websocket)