WalletsBalances

Wallet Balances

Query wallet balances across all supported currencies. View available, held, and total balances for any customer or your merchant wallet.

Looking for the Embedded Wallet API?

This page covers the direct balance query API. If you need to create wallets, sync users, or manage wallet operations (transfers, holds, releases), see the Embedded Wallet API documentation.

Get wallet balances

Retrieve the balance breakdown for a specific wallet. Returns available, held, and total amounts for each currency the wallet holds.

GET/wallets/{wallet_id}/balances

Get all currency balances for a wallet.

Path parameters

Name	Type	Required	Description
wallet_id	string	required	The wallet ID (e.g., "wal_abc123") or "me" for your merchant wallet.

# Get a customer's wallet balances
curl https://wallet.e-mazad.store/api/v1/wallets/wal_abc123/balances \
  -H "Authorization: Bearer sk_sandbox_..."

# Get your merchant wallet balances
curl https://wallet.e-mazad.store/api/v1/wallets/me/balances \
  -H "Authorization: Bearer sk_sandbox_..."

Balance breakdown

Each currency balance is split into three components.

Field	Description
available	Funds that can be spent or transferred immediately. This is `total - held`.
held	Funds reserved by active holds (escrow). Cannot be spent until released or captured.
total	Total wallet balance for this currency. Equals `available + held`.

Check available, not total

When verifying if a wallet has sufficient funds for a transfer, always check the available balance, not total. Held funds cannot be used for new transactions.

Merchant wallet shortcut

Use me as the wallet ID to query your merchant wallet without needing to look up its ID.

curl https://wallet.e-mazad.store/api/v1/wallets/me/balances \
  -H "Authorization: Bearer sk_sandbox_..."

Wallets Overview Transactions