Exchange mechanics
Bybit Unified Trading Account: why availableToWithdraw is empty and what to use instead
Updated Ninja Terminal team
Short answer
Bybit deprecated the availableToWithdraw field for Unified Trading Account wallets on 9 January 2025, and API responses return it as an empty string. Available balance is derived instead. For cross margin and portfolio margin, use the account-level totalAvailableBalance. For a single coin, subtract locked balance, order margin, position margin and bonus from walletBalance.
If you read Bybit’s wallet endpoint and find "availableToWithdraw": "" on every coin, your code is not broken. The field changed. This guide explains what changed, which fields replace it, and the traps that make balances look like zero.
What changed on 9 January 2025?
The GET /v5/account/wallet-balance documentation marks availableToWithdraw as “Deprecated for accountType=UNIFIED from 9 Jan, 2025”. It points to the Get Transferable Amount (Unified) and Get All Coins Balance endpoints for transferable balances. In API responses for Unified accounts the field arrives as an empty string. The same applies to the wallet WebSocket topic in practice.
A Unified Trading Account shares one collateral pool across spot, derivatives and options. A single “available to withdraw” number no longer describes what you can trade, because the answer depends on haircuts, margin mode and open orders.
How is available balance calculated now?
Bybit documents the formulas in the wallet balance reference:
| Account situation | Available balance |
|---|---|
| Cross margin | totalAvailableBalance = totalMarginBalance - Haircut - totalInitialMargin (USD) |
| Portfolio margin | totalAvailableBalance = total equity - Haircut - totalInitialMargin (USD) |
| Isolated margin, per coin | walletBalance - totalPositionIM - totalOrderIM - locked - bonus |
| Spot margin | Use the Get Borrow Quota (Spot) endpoint |
Field meanings:
walletBalanceis the wallet balance of the coin.lockedis the balance locked by spot open orders.totalOrderIMis margin reserved for open orders.totalPositionIMis the initial margin of all positions plus the pre-occupied liquidation fee.bonusis bonus balance.totalAvailableBalanceis account level and in USD. It is net of collateral haircuts, so it is lower than the sum of coin balances.
For portfolio margin, totalOrderIM and totalPositionIM are returned as empty strings. Parse them defensively.
What goes wrong with an empty string?
Reading availableToWithdraw as a number turns an empty string into a bad value:
parseFloat("")isNaN. A client that drops invalid updates can keep an old balance forever.Number("")is0. A client that falls back to zero shows every coin as fully locked, and a spot form can show “Available 0.00 USDT” and a maximum buy of zero.
Both failures look like a trading problem, not a parsing problem.
What should I use for spot and what for perpetuals?
- Spot buy or sell of a single coin: use the per-coin formula with
walletBalance,locked,totalOrderIM,totalPositionIMandbonus. Do not cap it withtotalAvailableBalance. That number is net of haircuts on every collateral coin, so it can be far below what you can sell of a coin you hold. - Perpetual margin: use
totalAvailableBalancefor cross margin and portfolio margin accounts, because margin comes from the shared pool. - Exact spot capacity with margin: use the spot borrow quota endpoint that Bybit documents for spot margin.
How Ninja Terminal handles this
Ninja Terminal does not read availableToWithdraw for Bybit Unified accounts. Free balance per coin is walletBalance minus locked, totalOrderIM, totalPositionIM and bonus, the formula Bybit documents for isolated margin. It is not capped by totalAvailableBalance, so you can still sell a coin you hold. The same calculation runs for REST balances and for WebSocket wallet updates. Perpetual margin uses the account-level summary for cross and portfolio margin accounts.
Balances shown here come from your own Bybit account through your API key. Ninja Terminal is not a custodian. See Bybit in Ninja Terminal and the Bybit API key guide. This guide is not investment advice.
Frequently asked questions
Why is availableToWithdraw an empty string on Bybit?
Bybit marked availableToWithdraw as deprecated for accountType UNIFIED from 9 January 2025. The field is still in the response schema, but for Unified accounts the value comes back empty instead of a number.
Which Bybit field shows my available balance now?
For cross margin and portfolio margin accounts, read totalAvailableBalance. It is expressed in USD. For a single coin use walletBalance minus locked, totalOrderIM, totalPositionIM and bonus, which is the formula Bybit documents for isolated margin.
What does parseFloat of an empty string return?
In JavaScript, parseFloat of an empty string is NaN, and Number of an empty string is 0. Either result can make a Bybit coin look like it has zero free balance, so check for an empty value before you parse it.
Which Bybit endpoints give transferable balance?
Bybit's documentation points to Get Transferable Amount (Unified) and Get All Coins Balance for the amount you can transfer or withdraw. Use them when you need a withdrawable amount rather than a trading balance.