Returns the authenticated user’s wallet balance and withdrawal preferences.
Dashboard rule: Only available_balance should be shown to the user on the main
dashboard — it is the only figure they can actually spend or withdraw. total_balance
and locked_balance are provided for reference (e.g. a locked-funds tooltip) but
should not be surfaced as separate balances.
Balance semantics:
| Field | Meaning |
|---|---|
available_balance | Spendable right now — fund escrows or withdraw |
locked_balance | Held funds: active escrow locks + KYC-gated received funds |
total_balance | available + locked — all funds ever credited |
auto_withdraw | Whether released funds are automatically sent to the default payout account |
To see why funds are locked, call GET /wallet-balance?escrow_id=<id>.
JWT access token obtained from /auth-verify (login context) or /auth-signup. Set the bearer_token environment variable in your API client to apply it globally.