Check Balances and Ledger

Balances describe the customer's current asset position. The ledger is the append-only record of finalized balance movements. Use both views for different purposes.

Read balances

Retrieve every asset currently present on the account.

wallet_request GET "/accounts/$ACCOUNT_ID/balances" | jq

Retrieve the selected asset directly.

wallet_request GET "/accounts/$ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq

Important fields include the available amount and amounts reserved for pending operations. A new asset may be absent from the all-balances items until the account has activity.

The single-asset endpoint returns HTTP 404 with BALANCE_NOT_FOUND when no balance row exists yet. Check the account/asset IDs and deposit state rather than treating this as a service-wide outage or automatically retrying it. Keep your initial-balance display policy separate from confirming that a deposit has completed.

Amounts ending in _raw are integer strings in the asset's smallest unit. For a token with six decimals, 1000000 raw equals 1.00. Use BigInt, BigInteger, or a decimal library for calculations.

Read the ledger

wallet_request GET "/accounts/$ACCOUNT_ID/ledger?asset_type_id=$ASSET_TYPE_ID&after_id=0&limit=100" | jq

For a customer wallet, common transaction types are:

Transaction	Ledger type	Direction
External deposit	DEPOSIT	CREDIT
Internal payment sent	INTERNAL_OUT	DEBIT
External withdrawal	WITHDRAW	DEBIT

The ledger records completed balance changes. A pending deposit or withdrawal may not appear yet; use its detail API to follow the business status.

Retrieve one ledger entry

Store account_id and ledger_id together because a ledger ID belongs to one account.

export LEDGER_ID='{ledger-id-from-list}'
wallet_request GET "/accounts/$ACCOUNT_ID/ledger/$LEDGER_ID" | jq

Use ref_type and ref_id to join the ledger entry to the related deposit or withdrawal detail.

Synchronize incrementally

Save the ledger next_cursor, upsert items by ledger_id, and continue while has_more is true. The ledger is append-only, so cursor synchronization is sufficient for finalized entries. Keep a separate cursor for deposits and withdrawals.

Next: Request an external withdrawal.