Balances and Ledger

A balance answers how much is available now. The ledger answers which finalized movements changed that amount. Deposit and withdrawal details describe transaction progress. Use the appropriate resource for wallet displays, transaction tracking, and reconciliation.

Three balance amounts

Balances are maintained by account and asset type. USDT and ETH balances are separate; do not aggregate raw units across different assets.

Field	Meaning	Used for
available_amount_raw	Currently spendable funds	Checking funds before withdrawals/transfers
pending_withdraw_amount_raw	Funds reserved for pending withdrawals	Displaying pending withdrawal amounts
total_amount_raw	Available funds plus withdrawal reservations	Current wallet holdings
decimals	The decimal scale for raw units	Converting to display amounts

When total and available balances differ, inspect pending withdrawal reservations. For uncompleted external deposits, retrieve deposit state rather than adding the detected amount to your own spendable-balance calculation.

Customer wallet withdrawal example

Assume a customer holds 100 USDT and withdraws 20 USDT externally with an illustrative 1 USDT fee. No other transactions are concurrent.

Point	Available	Reserved	Total	Interpretation
Before withdrawal	100	0	100	All funds are spendable
After acceptance	79	21	100	Reserve principal 20 + fee 1
Completed	79	0	79	Reserved funds are withdrawn
Reservation released after failure/rejection/cancellation	100	0	100	Principal and fee become available again

Completion and release are different outcomes. Check final withdrawal detail and the returned balance together. These are display amounts; with decimals=6, the 21 USDT reservation is 21000000 raw units.

What a ledger entry represents

The ledger appends records of finalized balance movements. An entry represents one movement within a transaction, so multiple entries can refer to one transaction.

transaction_type	Code	entry_type	Meaning
DEPOSIT	1000	CREDIT	Completed external deposit
WITHDRAW	2000	DEBIT	Completed external withdrawal
INTERNAL_OUT	3000	DEBIT	Internal transfer sent
INTERNAL_IN	4000	CREDIT	Internal transfer received
ADJUSTMENT	5000	Depends on entry	Adjustment movement

Names in the table describe meaning; the API returns numeric transaction_type codes. amount_raw is an absolute value: CREDIT increases funds and DEBIT decreases them. entry_code distinguishes principal, fees, and other entry purposes.

ref_type and ref_id link entries to a transaction. ref_type=1000 refers to a deposit; ref_type=2000 refers to a withdrawal or internal transfer. Distinguish principal and fee entries, then inspect all relevant entries with the same reference.

Reconcile balances and ledger entries

Reconciliation verifies that transactions, ledger entries, and balances agree. For a finalized interval involving one account and asset without other reservations or concurrent activity:

closing balance = opening balance + CREDIT total - DEBIT total

After a 100 USDT deposit and a completed 20 USDT withdrawal with a 1 USDT fee, the finalized balance is 79 USDT. When reservations are pending, do not substitute the available balance alone into this equation; account for reserved funds and the comparison interval.

Validate with raw amounts, balance_after_raw, and transaction references. Store account IDs with ledger_id and preserve ledger order. See Transaction Reconciliation for synchronization guidance.

Internal transfer and payment movements

An internal transfer records INTERNAL_OUT / DEBIT on the source account and INTERNAL_IN / CREDIT on the recipient. Both sides share the withdrawal reference; internal transfer fees are zero.

For example, a customer pays 10 USDT from a 100 USDT balance. The customer holds 90 USDT afterward, and a merchant with an initial zero balance holds 10 USDT. Other account transfers work the same way. Confirm individual transfers/payments through transaction detail rather than balance differences alone.

Interpret query results

An asset without activity may be absent from the all-balances response. A single-asset query can return BALANCE_NOT_FOUND when no balance exists; check the account, asset, and deposit state.

Follow Check Balances and Ledger for queries. Deposit Flow explains crediting, and Withdrawal Flow explains reservation and finalization.