> ## 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 托管模式下查询单个用户各币种独立钱包余额（free / freeze / total）的接口页：GET /user-asset/v1/balance 用法、余额模型与「为什么余额查得到」的 DeCard 托管原理。

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

在 DeCard 托管模式下，每个终端用户都持有一份由 DCS 托管、按币种隔离的独立钱包余额，您用一个查询即可拿到该用户每种资产的可用 / 冻结 / 总额。作为持牌发卡机构、自有 BIN，DCS 替您托管这份用户级账本，授权与清算都直接作用于该用户的独立余额——本接口就是这套模型的查询入口。

一个用户可同时持有多种资产，余额接口按**币种逐项**返回每种资产的可用 / 冻结 / 总额。

本页**只聚焦余额查询**。资金的进出与流转分布在同组其他页，互不重复：

| 您想做的              | 用哪个接口 / 去哪页                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **查询**用户各币种余额（本页） | `GET /user-asset/v1/balance`                                                                                     |
| 给用户**充值 / 扣款**    | `POST /user-asset/v1/credit` · `POST /user-asset/v1/debit` —— 见 [账户与资产模型](../../basic-concepts/ledgering-system) |
| 查**资产流水 / 变动历史**  | `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` 随之减少。授权 / 清算如何改写这三个量，见 [授权](./authorizing-transactions) 与 [清算](./settlement)；DCS 托管边界见 [账户与资产模型](../../basic-concepts/ledgering-system)。

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

## 前置条件

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

## 接口契约

`user-asset` 模块还提供 `credit` / `debit` / `transactions` / `transaction-detail` / `transfer-query` 等接口，分布于本组的 [交易查询概述](./overview) 与 [账户与资产模型](../../basic-concepts/ledgering-system)。本页仅展开余额查询接口。

**`GET /user-asset/v1/balance`**

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

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

### 请求示例

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

```bash theme={null}
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` 为**数组**，用户持有几种资产就有几项，每项描述一种币种的余额。

```json theme={null}
{
  "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`）                      |

<Warning>
  `data` 是**数组**而非单个对象。请按 `asset`（必要时结合 `network`）遍历取值，**不要**假设它是一个含 `availableBalance` / `frozenBalance` 字段的对象。

  全站统一响应结构 `{ code, message, messageDetail, data }`，成功时 `code` 字面量为 `SYS_SUCCESS`（两种模式一致）。
</Warning>

## 错误处理

* **用户不存在 / `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` 可用余额是否足额**与**用户交易状态是否被禁**，详见 [授权](./authorizing-transactions)。

### 余额变动实时推送（WebSocket BALANCE\_CHANGE）

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

## 下一步

* 充值 / 扣款（`credit` / `debit`）与 DCS 托管账户模型：[账户与资产模型](../../basic-concepts/ledgering-system)
* 授权如何改写 `free` / `freeze`：[授权](./authorizing-transactions)
* 清算如何从 `freeze` 实际扣减：[清算](./settlement)
* 资产流水 / 变动历史（`transactions` / `transaction-detail` / `transfer-query`）：[交易查询概述](./overview)
* 用户状态与交易限制（`forbidCardTransaction`）：[创建用户 / 用户状态管理](../managing-users/overview)