User Balance - DCS Technical Documentation

One call returns every asset a user holds

In the DeCard-Managed model, every end user holds their own wallet balance, kept in custody by DCS and ledgered per currency, and a single call returns the available, frozen and total amount of each of their assets. As a licensed issuer running its own BINs, DCS keeps this user-level ledger in custody for you, and both authorization and settlement act directly on that user’s own balance. This endpoint is how that model is exposed to you. A user can hold several assets at once, and the balance endpoint returns the available, frozen and total amount per currency. This page covers balance queries only. Money moving in, out and around is documented on the sibling pages, with no overlap:

What you want to do	Endpoint or page
Read a user’s balances per currency (this page)	`GET /user-asset/v1/balance`
Top up or debit a user	`POST /user-asset/v1/credit` · `POST /user-asset/v1/debit`, see Account and Asset Model (Ledgering)
Read asset transactions and movement history	`POST /user-asset/v1/transactions` · `POST /user-asset/v1/transaction-detail`, see Overview (transaction and statement queries)
Read internal transfer records	`GET /user-asset/v1/transfer-query`, see the same page as above

The balance model: free / freeze / total

Under custody, DCS maintains three figures for each user and each asset:

Field	Meaning	Description
`free`	Available balance	The portion immediately usable for spending, transfers and withdrawals. An authorization (a card payment) is deducted from here and moved into `freeze`.
`freeze`	Frozen balance	The portion already committed and temporarily unusable, typically in-flight transactions that are authorized but not yet settled (authorization moves the amount from `free` into `freeze`).
`total`	Total balance	Always equal to `free + freeze`.

When an authorization happens, free decreases, freeze increases and total is unchanged; at settlement (the actual deduction) the amount comes out of freeze and total falls with it. For how authorization and settlement rewrite these three figures, see Authorizing Transactions and Settlement; for the boundary of DCS custody, see Account and Asset Model (Ledgering).

Term alignment: the “availableBalance / frozenBalance” you may see in conceptual material are the free and freeze of this endpoint. Always integrate against the API field names free / freeze / total; availableBalance and frozenBalance are conceptual aliases only.

Prerequisites

The user is registered through Managing Users and you hold their externalUserId.
Balances are normally non-zero only after the user has passed KYC and assets have arrived (a top-up or a transfer); a new user may return an empty array or all zeros.
The caller is a partner onboarded to the DeCard-Managed model and sends the site-wide authentication headers (see Quickstart).

Endpoint contract

The user-asset module also offers credit, debit, transactions, transaction-detail and transfer-query, documented in Overview (transaction and statement queries) and Account and Asset Model (Ledgering) within this group. This page covers only the balance query. GET /user-asset/v1/balance

Parameter	In	Type	Required	Description
`externalUserId`	query	string	✓	User ID (the unique identifier of the user on your side). Redacted placeholder: `<external-user-id>`.

That is the only query parameter; there are no path parameters and no request body. This endpoint takes no path parameters and has no notion of a tenant, since balances are always read for one user keyed by externalUserId.

Request example

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>"

The usr_xxxxxxxx, key and signature in the example are all placeholders. Never paste a real user ID, API key or secret into any document, log or support ticket.

Response

The response uses the site-wide envelope { code, message, messageDetail, data }, where data is an array with one entry per asset the user holds, each describing the balance of one currency.

{
  "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
    }
  ]
}

Fields of each data[] element:

Field	Type	Description
`asset`	string	Asset currency code; currently `USDT`, `USDC` and `USD` are known, the set may grow, so trust what is actually returned
`logo`	string	Currency logo image URL
`network`	string	Network name, such as `Bitcoin`, `Ethereum` or `Polygon`
`free`	number	Available balance
`freeze`	number	Frozen balance
`total`	number	Total balance (= `free` + `freeze`)

data is an array, not a single object. Iterate over it by asset (and by network where that matters), and do not assume an object carrying availableBalance and frozenBalance fields.The site-wide response envelope is { code, message, messageDetail, data }, and on success the code literal is SYS_SUCCESS (identical in both integration models).

Error handling

The user does not exist, or externalUserId is invalid: code is not the success value, message and messageDetail explain why, and data carries no valid balance. Confirm first that the externalUserId was registered through the create-user endpoint.
A required parameter is missing: a request without externalUserId is rejected.
Authentication failure: a missing authentication header (X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE), a bad signature or a replayed X-DAPI-NONCE all return the standard authentication error (see Quickstart).
Empty account: when the user exists but holds no assets yet, data may be an empty array [] or contain all zeros. That is not an error.

About the per-user account and DeCard-Managed model (why balances are queryable)

In the DeCard-Managed model, DCS holds each user’s funds in custody internally, keyed by externalUserId, with sub-accounts isolated per currency. That is precisely what allows this endpoint to return a balance per user and per currency. By contrast:

Partner-Managed: limits and authorization decisions belong to the partner, and DCS exposes no per-user balance endpoint.
DeCard-Managed (this documentation set): DCS keeps the user’s own balance in custody and decides authorizations internally, acting directly on that user’s free and freeze. This endpoint is how that model is exposed to you.

It also explains why whether an authorization succeeds depends mainly on whether the user’s free balance is sufficient and whether card transactions are blocked for that user; see Authorizing Transactions.

Real-time push of balance changes (WebSocket BALANCE_CHANGE)

Whenever an authorization, a settlement, a top-up (credit), a debit (debit) or an internal transfer changes a user’s free or freeze, DCS pushes a BALANCE_CHANGE event in real time over WebSocket, carrying freeDelta (the change in available balance), freezeDelta (the change in frozen balance) and the absolute free and freeze after the change. You do not need to poll /user-asset/v1/balance to track balances: subscribe to the WebSocket channel and receive the pushes. See Webhook & WebSocket.

Next steps

Top-ups and debits (credit / debit) and the accounts DCS holds in custody: Account and Asset Model (Ledgering)
How authorization rewrites free and freeze: Authorizing Transactions
How settlement deducts from freeze: Settlement
Asset transactions and movement history (transactions / transaction-detail / transfer-query): Overview (transaction and statement queries)
User status and transaction restrictions (forbidCardTransaction): Managing Users

​One call returns every asset a user holds

​The balance model: free / freeze / total

​Prerequisites

​Endpoint contract

​Request example

​Response

​Error handling

​About the per-user account and DeCard-Managed model (why balances are queryable)

​Real-time push of balance changes (WebSocket BALANCE_CHANGE)

​Next steps

One call returns every asset a user holds

The balance model: free / freeze / total

Prerequisites

Endpoint contract

Request example

Response

Error handling

About the per-user account and DeCard-Managed model (why balances are queryable)

Real-time push of balance changes (WebSocket BALANCE_CHANGE)

Next steps