Every account holds one balance per currency. Currencies are independent: an account can hold USD and still be unable to move NGN.
Read a balance
GET /v1/balances · scope accounts:read · full field reference →
Add X-Account-Id to read an account’s balance. This works from the moment the account exists, whatever state its capabilities are in.
available_balance funds transfers and withdrawals.pending_balance is charged money awaiting settlement. It cannot be moved.pending_settlements_by_day gives the date each pending amount becomes available, per currency. Schedule against it.total_balance_usd is a display total. No operation accepts it.
The response covers the currencies the account is configured to hold, always including USD, plus any currency with activity. A currency with neither is absent rather than zero.
A successful charge does not mean a movable balance. Transfers and withdrawals draw on available_balance only, so an operation sent before settlement is rejected with INSUFFICIENT_BALANCE.
The zero floor
A balance never goes below zero. A transfer or withdrawal above available_balance is rejected rather than creating a debt. For a withdrawal, the figure to compare is total_debited (what the destination receives plus the fee), not amount.
- Transferring more than an account holds fails.
- Once an account has withdrawn, that balance cannot be recovered.
The floor applies per currency. A large USD balance does not fund an NGN transfer, and a transfer never converts. See Split payments.
A lost dispute is the one exception to the floor. It can deliberately drive available_balance negative: the shortfall is the debt, and it heals as the account’s own future settlement credits land. While any currency is negative, every transfer and withdrawal for that account is blocked, not only in the negative currency. See Disputes.
