> ## 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.

# 账户与资产模型

> 说明用户独立余额（free / freeze / total）、按用户和资产记账以及托管策略。具体 API 调用与字段请参阅文末的相关操作指南。

## 📄 正文

DeCard 托管模式为每个用户托管一份独立的资金账本。资金的占用（授权冻结）与扣减（清算入账）都直接作用于该用户的余额，无需把授权请求转发给接入机构。作为持牌、自有 BIN 的发卡机构，DCS 由此把用户资产的合规托管与记账都在自有系统内完成。

DCS 直接托管用户的可支配余额，用 **可用 / 冻结 / 总额** 三个数描述任意时刻的资金状态。

## 余额模型（free / freeze / total）

每个用户账户按<b>币种（资产）</b>分别记账。查询 `/user-asset/v1/balance` 返回一组按资产维度的余额对象：

| 字段       | 含义   | 说明                   |
| -------- | ---- | -------------------- |
| `free`   | 可用余额 | 当前可用于消费或提现的部分        |
| `freeze` | 冻结余额 | 已被授权占用、尚未清算释放的部分     |
| `total`  | 总额   | 一般等于 `free + freeze` |

> 余额对象还含 `asset`、`network`、`logo`。当前已知资产为 `USDT`、`USDC`、`USD`；后续可能扩展，请仍以 balance 接口实际返回为准，不要把当前清单硬编码为永久全集。
> **术语对应**：业务上常说的"可用余额 / 冻结余额"即 API 字段 `free` / `freeze`；本套文档统一以 API 字段名 `free` / `freeze` / `total` 为准，行文中括注其中文语义。

资金随交易生命周期在 `free` 与 `freeze` 之间流动：

* **授权（冻结）**：批准一笔消费时，对应金额从 `free` 移入 `freeze`——资金被冻结但不离开账户，`total` 不变。
* **清算（入账）**：商户提交最终金额后完成实际扣减，对应的 `freeze` 被释放、账户余额相应下降。
* **充值 / 退款**：资金增加时进入 `free`。
* **费用扣款**：制卡费（`CARD_PRINTING_FEE`）、邮寄费（`CARD_POSTAL_FEE`）、冻结费（`CARD_VIP_FROZEN_FEE`）等直接从 `free` 扣除。`free` 减少、`total` 同步下降（不经过 `freeze`，与消费授权-清算两段路径不同）。

> 授权/清算两阶段对余额的影响详见 [授权](../how-to-use/managing-transactions/authorizing-transactions) 与 [清算](../how-to-use/managing-transactions/settlement)。

## 充值与扣款（Credit / Debit）

DeCard 托管模型下，用户独立余额通过一组 user-asset 接口调整与查询：

| 接口                                       | 作用                            |
| ---------------------------------------- | ----------------------------- |
| `POST /user-asset/v1/credit`             | 充值（增加用户余额）                    |
| `POST /user-asset/v1/debit`              | 扣款（减少用户余额）                    |
| `GET  /user-asset/v1/balance`            | 查询用户余额（free / freeze / total） |
| `POST /user-asset/v1/transactions`       | 查询资产变动流水                      |
| `POST /user-asset/v1/transaction-detail` | 查询单笔变动详情                      |
| `GET  /user-asset/v1/transfer-query`     | 按 externalTranId 查转账结果        |

`credit` / `debit` 请求体一致：`{ externalTranId, asset, amount, externalUserId, remark }`——其中 `externalTranId` 为幂等唯一 ID，`asset` 须是 DeCard 支持的币种，`amount` 必须为正数且小数位 ≤ 18 位。

> 字段全表与可跑示例见 使用指南 → [用户余额](../how-to-use/managing-transactions/user-balance) 与 [交易查询](../how-to-use/managing-transactions/overview)。

## 资金变动类型（Transaction Type）

`POST /user-asset/v1/transactions` 与 `POST /user-asset/v1/transaction-detail` 通过 `type` 字段标识每笔变动的业务类型，相当于"账本分录类型"：

| type 枚举值              | 语义      | 方向        |
| --------------------- | ------- | --------- |
| `DEPOSIT`             | 充值入金    | 余额增加      |
| `WITHDRAW`            | 提现出金    | 余额减少      |
| `CARD_PRINTING_FEE`   | 制卡费     | 余额减少      |
| `CARD_POSTAL_FEE`     | 邮寄费     | 余额减少      |
| `CARD_VIP_FROZEN_FEE` | VIP 冻结费 | 余额减少      |
| `CONVERSION`          | 换汇      | 余额变动（两币种） |
| `REWARD_DISTRIBUTION` | 奖励发放    | 余额增加      |
| `REWARD_PAY`          | 奖励支付    | 余额减少      |
| `REWARD_REFUND`       | 奖励退款    | 余额增加      |
| `MIGRATION`           | 用户资产迁移  | 余额变动      |

## 关键原则

1. **可用与冻结分离**：授权立即把资金从 `free` 移入 `freeze`，先于实际清算占用额度，防止超额消费；清算时再从 `freeze` 释放并完成扣减。
2. **按用户、按资产独立记账**：每个用户的每种资产各有一份 `free`/`freeze`/`total`，互不混淆。
3. **幂等保护**：充值、扣款均以 `externalTranId` 作幂等键，重复请求被拒绝。

## 下一步

* 交易主线（授权、清算、Outstanding 与余额变化）：[交易生命周期 · 概述](./transaction-lifecycle)
* 授权如何冻结资金：[授权](../how-to-use/managing-transactions/authorizing-transactions)
* 资金如何实际入账：[清算](../how-to-use/managing-transactions/settlement)
* 查询用户余额（free/freeze/total）：[用户余额](../how-to-use/managing-transactions/user-balance)
* 加密货币充值与链/币种：[加密货币充值](../how-to-use/virtual-accounts/crypto-deposit)
* 加密货币提现：[加密货币提现](../how-to-use/virtual-accounts/withdraw-offramp)