用户余额 - DCS Technical Documentation

每个用户、每种资产，一个查询拿全

在 DeCard 托管模式下，每个终端用户都持有一份由 DCS 托管、按币种隔离的独立钱包余额，您用一个查询即可拿到该用户每种资产的可用 / 冻结 / 总额。作为持牌发卡机构、自有 BIN，DCS 替您托管这份用户级账本，授权与清算都直接作用于该用户的独立余额——本接口就是这套模型的查询入口。一个用户可同时持有多种资产，余额接口按币种逐项返回每种资产的可用 / 冻结 / 总额。本页只聚焦余额查询。资金的进出与流转分布在同组其他页，互不重复：

您想做的	用哪个接口 / 去哪页
查询用户各币种余额（本页）	`GET /user-asset/v1/balance`
给用户充值 / 扣款	`POST /user-asset/v1/credit` · `POST /user-asset/v1/debit` —— 见账户与资产模型
查资产流水 / 变动历史	`POST /user-asset/v1/transactions` · `POST /user-asset/v1/transaction-detail` —— 字段以 API 参考对应接口页为准
查内部划拨记录	`GET /user-asset/v1/transfer-query` —— 见同上流水页

余额模型：free / freeze / total

DCS 在托管下为每个用户、每种资产维护三个量：

字段	含义	说明
`free`	可用余额	可立即用于消费 / 划拨 / 提现的部分。授权（刷卡）会从这里扣减并移入 `freeze`。
`freeze`	冻结余额	已被占用、暂不可用的部分——典型来源是已授权未清算的在途交易（授权时把金额从 `free` 移入 `freeze`）。
`total`	总余额	恒等于 `free + freeze`。

一笔授权发生时：free 减少、freeze 增加、total 不变；清算（实际扣款）时从 freeze 中扣减，total 随之减少。授权 / 清算如何改写这三个量，见授权与清算；DCS 托管边界见账户与资产模型。

术语对齐：概念性资料中提到的「availableBalance / frozenBalance」即本接口的 free / freeze。集成时一律以接口字段名 free / freeze / total 为准，availableBalance / frozenBalance 仅作概念别名。

前置条件

用户已通过创建用户 / 用户状态管理注册，您持有其 externalUserId。
通常需用户已完成 KYC 并已有资产入账（充值 / 划拨）后，余额才非零；新用户可能返回空数组或全 0。
调用方为已开通 DeCard 托管方案的接入机构，按全站统一鉴权方式携带请求头（见快速开始）。

接口契约

user-asset 模块还提供 credit / debit / transactions / transaction-detail / transfer-query 等接口，分布于本组的交易查询概述与账户与资产模型。本页仅展开余额查询接口。 GET /user-asset/v1/balance

参数	位置	类型	必填	说明
`externalUserId`	query	string	✓	用户 ID（您侧用户的唯一标识）。脱敏占位示例 `<external-user-id>`。

仅此一个查询参数；无路径参数、无请求体。本接口不使用路径参数，也不存在 tenant 概念——余额始终以 externalUserId 为维度查询单个用户。

请求示例

GET /user-asset/v1/balance?externalUserId=<external-user-id>

curl -X GET \
  "https://<decard-host>/user-asset/v1/balance?externalUserId=usr_xxxxxxxx" \
  -H "X-DAPI-API-KEY: <your-api-key>" \
  -H "X-DAPI-SIGN: <hmac-sha256-signature>" \
  -H "X-DAPI-TIMESTAMP: <timestamp>" \
  -H "X-DAPI-NONCE: <nonce>"

示例中 usr_xxxxxxxx、密钥与签名全部为占位值。请勿在任何文档 / 日志 / 工单中粘贴真实用户 ID、API Key 或 secret。

响应

响应套用全站统一结构 { code, message, messageDetail, data }；data 为数组，用户持有几种资产就有几项，每项描述一种币种的余额。

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": {
    "message": "",
    "title": "",
    "type": "",
    "icon": "",
    "action": "",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": [
    {
      "asset": "USDT",
      "logo": "https://<asset-logo-cdn>/usdt.png",
      "network": "Ethereum",
      "free": 100.000000,
      "freeze": 20.000000,
      "total": 120.000000
    },
    {
      "asset": "USDC",
      "logo": "https://<asset-logo-cdn>/usdc.png",
      "network": "Polygon",
      "free": 0.0,
      "freeze": 0.0,
      "total": 0.0
    }
  ]
}

data[] 元素字段：

字段	类型	说明
`asset`	string	资产币种代码；当前已知为 `USDT` / `USDC` / `USD`，后续可能扩展，以实际返回为准
`logo`	string	币种 Logo 图片链接
`network`	string	网络名称，如 `Bitcoin` / `Ethereum` / `Polygon` 等
`free`	number	可用余额数量
`freeze`	number	冻结余额数量
`total`	number	总余额数量（= `free` + `freeze`）

data 是数组而非单个对象。请按 asset（必要时结合 network）遍历取值，不要假设它是一个含 availableBalance / frozenBalance 字段的对象。全站统一响应结构 { code, message, messageDetail, data }，成功时 code 字面量为 SYS_SUCCESS（两种模式一致）。

错误处理

用户不存在 / externalUserId 无效：code 非成功值，message / messageDetail 给出原因，data 不返回有效余额。请先确认该 externalUserId 已通过创建用户接口注册。
缺少必填参数：未传 externalUserId 将被拒绝。
鉴权失败：鉴权头（X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE）缺失 / 签名错误 / X-DAPI-NONCE 重放，按统一鉴权错误返回（见 Quickstart）。
空账户：用户存在但尚无任何资产时，data 可能为空数组 [] 或各项均为 0，这不是错误。

关于「独立账户 / DeCard 托管」模型（为什么余额查得到）

DeCard 托管方案下，DCS 在内部按 externalUserId 维度托管每个用户的资金，并按币种隔离子账户——这正是本接口能返回每用户、每币种余额的前提。与之对照：

合作伙伴自管：额度与授权决策由接入机构掌握，DCS 侧无用户级独立余额接口。
DeCard 托管（本套）：DCS 托管用户独立余额，授权在系统内完成、直接作用于该用户的 free / freeze——本接口即该模型的余额查询入口。

这也解释了为什么「一笔授权能不能成」主要取决于用户 free 可用余额是否足额与用户交易状态是否被禁，详见授权。

余额变动实时推送（WebSocket BALANCE_CHANGE）

当授权、清算、充值（credit）、扣款（debit）或内部划拨导致用户的 free / freeze 发生变动时，DCS 会通过 WebSocket 实时推送 BALANCE_CHANGE 事件，包含 freeDelta（可用变动）与 freezeDelta（冻结变动）以及变动后的 free / freeze 绝对值。接入机构无需轮询 /user-asset/v1/balance 来跟踪余额变化——订阅 WebSocket 通道后即可接收推送。详见 Webhook 与 WebSocket 实时通知。

下一步

充值 / 扣款（credit / debit）与 DCS 托管账户模型：账户与资产模型
授权如何改写 free / freeze：授权
清算如何从 freeze 实际扣减：清算
资产流水 / 变动历史（transactions / transaction-detail / transfer-query）：交易查询概述
用户状态与交易限制（forbidCardTransaction）：创建用户 / 用户状态管理

​每个用户、每种资产，一个查询拿全

​余额模型：free / freeze / total

​前置条件

​接口契约

​请求示例

​响应

​错误处理

​关于「独立账户 / DeCard 托管」模型（为什么余额查得到）

​余额变动实时推送（WebSocket BALANCE_CHANGE）

​下一步

每个用户、每种资产，一个查询拿全

余额模型：free / freeze / total

前置条件

接口契约

请求示例

响应

错误处理

关于「独立账户 / DeCard 托管」模型（为什么余额查得到）

余额变动实时推送（WebSocket BALANCE_CHANGE）

下一步