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

# Accounts and Asset Model

> A concept page on the account and asset model: per-user balances (free / freeze / total), booking per user and per asset, and custody strategy. For the actual API calls and field details, go to the matching How-to page (see "Next steps" at the end). This page does not repeat the field tables.

## 📄 Guide

In DeCard-Managed mode, DCS holds a dedicated funding ledger for every user. Both the reservation of funds (an authorization hold) and the deduction of funds (settlement) act directly on that user's balance, with no authorization request forwarded to the partner. As a licensed issuer running its own BINs, DCS therefore keeps regulated custody and booking of user assets entirely inside its own systems.

DCS holds the user's spendable balance directly and describes the state of those funds at any point in time with three numbers: **available, frozen, and total**.

## Balance model (free / freeze / total)

Each user account is booked separately **per currency (asset)**. A call to `/user-asset/v1/balance` returns one balance object per asset:

| Field    | Meaning           | Description                                                          |
| -------- | ----------------- | -------------------------------------------------------------------- |
| `free`   | Available balance | The part currently available to spend or withdraw                    |
| `freeze` | Frozen balance    | The part held by an authorization and not yet released by settlement |
| `total`  | Total             | Normally equal to `free + freeze`                                    |

> The balance object also carries `asset`, `network`, and `logo`. The assets known today are `USDT`, `USDC`, and `USD`. The list may grow, so always rely on what the balance endpoint actually returns rather than hard-coding today's list as the permanent set.
> **Terminology**: what the business side calls "available balance" and "frozen balance" are the API fields `free` and `freeze`. This documentation set uses the API field names `free` / `freeze` / `total` as canonical and glosses their plain meaning in parentheses where useful.

Funds move between `free` and `freeze` as a transaction progresses:

* **Authorization (hold)**: when a purchase is approved, the amount moves from `free` into `freeze`. The funds are held but do not leave the account, so `total` is unchanged.
* **Settlement (debit)**: once the merchant submits the final amount, the actual deduction takes place, the matching `freeze` is released, and the account balance drops accordingly.
* **Deposits and refunds**: incoming funds land in `free`.
* **Fee debits**: card production fees (`CARD_PRINTING_FEE`), postage fees (`CARD_POSTAL_FEE`), freeze fees (`CARD_VIP_FROZEN_FEE`), and similar charges are debited straight from `free`. `free` goes down and `total` goes down with it, without passing through `freeze`, unlike the two-step authorization-then-settlement path of a purchase.

> For how the two stages affect balances, see [Authorizing Transactions](../how-to-use/managing-transactions/authorizing-transactions) and [Settlement](../how-to-use/managing-transactions/settlement).

## Deposits and debits (credit / debit)

In DeCard-Managed mode, per-user balances are adjusted and queried through a set of user-asset endpoints:

| Endpoint                                 | Purpose                                      |
| ---------------------------------------- | -------------------------------------------- |
| `POST /user-asset/v1/credit`             | Credit (increase a user balance)             |
| `POST /user-asset/v1/debit`              | Debit (decrease a user balance)              |
| `GET  /user-asset/v1/balance`            | Query a user balance (free / freeze / total) |
| `GET  /user-asset/v1/transactions`       | List asset movements                         |
| `POST /user-asset/v1/transaction-detail` | Retrieve one movement in detail              |
| `GET  /user-asset/v1/transfer-query`     | Look up a transfer result by externalTranId  |

`credit` and `debit` take the same request body: `{ externalTranId, asset, amount, externalUserId, remark }`. Here `externalTranId` is the unique idempotency ID, `asset` must be a currency that DCS supports, and `amount` must be positive with at most 18 decimal places.

> For the full field tables and runnable examples, see How to Use › [User Balance](../how-to-use/managing-transactions/user-balance) and [Managing Transactions](../how-to-use/managing-transactions/overview).

## Movement types (transaction type)

`POST /user-asset/v1/transactions` and `POST /user-asset/v1/transaction-detail` use the `type` field to mark the business nature of each movement, effectively the ledger entry type:

| type value            | Meaning              | Direction                        |
| --------------------- | -------------------- | -------------------------------- |
| `DEPOSIT`             | Deposit              | Balance increases                |
| `WITHDRAW`            | Withdrawal           | Balance decreases                |
| `CARD_PRINTING_FEE`   | Card production fee  | Balance decreases                |
| `CARD_POSTAL_FEE`     | Postage fee          | Balance decreases                |
| `CARD_VIP_FROZEN_FEE` | VIP freeze fee       | Balance decreases                |
| `CONVERSION`          | Currency conversion  | Balance changes (two currencies) |
| `REWARD_DISTRIBUTION` | Reward distribution  | Balance increases                |
| `REWARD_PAY`          | Reward payment       | Balance decreases                |
| `REWARD_REFUND`       | Reward refund        | Balance increases                |
| `MIGRATION`           | User asset migration | Balance changes                  |

## Key principles

1. **Available and frozen are kept apart**: an authorization moves funds from `free` into `freeze` immediately, reserving the limit ahead of actual settlement so a user cannot overspend; settlement then releases the hold from `freeze` and completes the debit.
2. **Booked per user and per asset**: every asset of every user has its own `free`, `freeze`, and `total`, with no commingling.
3. **Idempotency**: both credit and debit use `externalTranId` as the idempotency key, so a repeated request is rejected.

## Next steps

* The mental model for the transaction flow (two stages, the Outstanding bridge, the invariants): [Transaction Lifecycle · Overview](./transaction-lifecycle)
* How an authorization freezes funds: [Authorizing Transactions](../how-to-use/managing-transactions/authorizing-transactions)
* How funds are actually debited: [Settlement](../how-to-use/managing-transactions/settlement)
* Querying user balances (free / freeze / total): [User Balance](../how-to-use/managing-transactions/user-balance)
* Crypto deposits, chains, and assets: [Crypto Deposit](../how-to-use/virtual-accounts/crypto-deposit)
* Crypto withdrawals: [Crypto Withdrawal](../how-to-use/virtual-accounts/withdraw-offramp)