An exchange API's available balance is the amount usable for a particular action under that account's rules; total balance describes a broader holding or valuation. They differ when funds are reserved, margin is committed, liabilities apply or observations come from different times. Match the account, asset, units, field definitions and snapshot timing before treating a difference as missing money or sizing another order.
Start with the field's question
“My account holds 1,000 USDT” and “I can submit a 1,000 USDT order” are different statements. Some of that holding may already support an open order. A valuation may also include other assets or unrealized profit that is not interchangeable with spendable USDT.
Before comparing two numbers, record the venue, account or subaccount, environment, wallet type, margin mode, asset and observation time. Comparing a funding wallet with a trading wallet cannot establish a discrepancy in either one. Nor can comparing a testnet account with a live account.
Confirm that the request reached the intended authenticated account. If authentication itself fails, use the passphrase versus API-secret guide to identify the credential fields; changing a credential cannot explain an otherwise valid free-versus-total calculation. The broader connection-health checklist helps distinguish a successful private read from stale application data.
Spot buckets and margin capacity need different mappings
Binance Spot account information returns an asset's free and locked amounts. For an ordinary spot-asset reconciliation, their sum is the holding represented by those two buckets:
Spot asset holding = free + locked
Locked funds remain part of that holding. Adding the locked amount to a total that already includes it counts the reservation twice. A buy order can reserve quote currency before acquiring any base asset; an unfilled sell can reserve base units without disposing of them.
The same shortcut does not define every venue's available balance. Bybit's Unified wallet documentation distinguishes coin-level walletBalance from account-wide USD fields. It defines cross-margin totalAvailableBalance as totalMarginBalance − Haircut − totalInitialMargin, while portfolio margin starts from total equity. Account-wide fields do not apply to isolated margin, and locked specifically describes Spot open-order funds.
That is why walletBalance − locked is not a universal buying-power formula. Read the account mode and intended action before choosing an available, transferable or borrow-related endpoint. Bybit also marks availableToWithdraw deprecated for Unified accounts from 9 January 2025. An old field name in an integration is not evidence that it still answers today's withdrawal or order-sizing question.
Keep a small mapping beside the integration:
| Observation | Unit and scope | Useful question | Unsafe substitution |
|---|---|---|---|
| Spot free amount | One asset in one spot account | What is unreserved in this bucket? | Assuming every order using it will pass all rules |
| Spot locked amount | Same asset and account | What remains committed? | Treating it as a second holding |
| Coin wallet balance | Native asset units, venue-defined | What does this wallet field contain? | Calling it account-wide margin capacity |
| Account available margin | Usually a valuation unit, mode-specific | What capacity does this margin model report? | Reading USD as the same number of BTC or USDT |
| Transferable amount | Asset and transfer route | What can move through this route? | Reusing it as a universal trade limit |
A reservation, partial fill and cancellation
The following is a hypothetical, unleveraged spot example in one account. It starts with 1,000 USDT and no BTC. A limit buy requests 0.010 BTC at 40,000 USDT per BTC. Only 0.004 BTC fills, at the limit price. The example assumes a 0.16 USDT fee debited from free USDT, no other activity, and exact decimal accounting. It is not an exchange fee schedule or a guarantee about a venue's reservation mechanics.
Each row represents the fully reconciled state after that step, rather than several independently timed API replies.
| Confirmed state | Free USDT | Locked USDT | Total USDT | BTC holding |
|---|---|---|---|---|
| Before order | 1,000.00 | 0.00 | 1,000.00 | 0.000 |
| Order accepted; 400 USDT reserved | 600.00 | 400.00 | 1,000.00 | 0.000 |
| 0.004 BTC filled for 160 USDT; fee charged | 599.84 | 240.00 | 839.84 | 0.004 |
| Remaining order confirmed cancelled; reservation released | 839.84 | 0.00 | 839.84 | 0.004 |
The unfilled quantity is 0.010 − 0.004 = 0.006 BTC, reserving 0.006 × 40,000 = 240 USDT. After the fill, the USDT holding is 1,000 − 160 − 0.16 = 839.84. Cancelling the remainder moves 240 USDT from locked to free; it does not add 240 USDT to the total.
Before that release, a new 700 USDT purchase exceeds the example's 599.84 free amount even though total USDT is 839.84. After the confirmed release it passes that particular cash comparison, though fees, instrument rules and concurrent activity can still affect acceptance.
At a hypothetical valuation of 40,000 USDT per BTC, cash plus BTC is 839.84 + 0.004 × 40,000 = 999.84 USDT. The 0.16 reduction is the assumed fee. The 160 USDT cash reduction became BTC rather than disappearing. For fees charged in BTC or a third token, use the separate fee-currency reconciliation instead of copying this quote-fee assumption.
A snapshot race can manufacture a discrepancy
Suppose the application reads USDT before the fill but reads BTC after it. Combining 1,000 USDT with 0.004 BTC at the example's valuation produces an apparent 1,160 USDT holding. That composite never existed in the example. The reverse timing can temporarily omit acquired BTC and make the account look too small.
Record local request and receipt times as well as documented exchange timestamps. A timestamp's presence does not prove that separately requested orders, balances and valuations share one atomic cutoff. Keep each observation's provenance until the views can be reconciled.
Binance's Spot user-data stream sends account updates containing assets possibly changed by the event. This is not a promise that each event replaces the entire account. Merge changed asset records according to the documented schema; do not zero every asset absent from a partial update. After a connection gap, follow the WebSocket recovery process before treating a newly active feed as a complete balance history.
If several orders were submitted together, inspect each order's outcome before attributing all reserved funds to the batch. The bulk-order partial-success guide explains why one request can leave a mixed set of accepted and rejected instructions.
Reconcile the mismatch before the next decision
Use this worksheet in order. Preserve the unresolved difference instead of adjusting a local balance until the display matches.
| Check | Evidence to collect | What it resolves |
|---|---|---|
| Same boundary | Account, wallet, environment, asset and margin mode | A valid comparison scope |
| Same meaning | Raw field names, units and current endpoint definitions | Free, total, equity and transfer limits being confused |
| Same period | Observation times and intervening account activity | Snapshot races and stale caches |
| Reservations | Current open orders, confirmed fills and cancellation results | Funds still committed to instructions |
| Other movements | Transfers, deposits, withdrawals, fees and liabilities where applicable | Changes not explained by the selected order |
| Exact values | Original decimal strings and documented increments | Rounding or parsing differences |
Preserve decimals through that last step; the API decimal-precision guide covers implementation mistakes that can create a small but real mismatch. Distinguish a missing field or failed read from a confirmed zero. In particular, do not quietly replace a deprecated or unavailable capacity field with wallet balance.
One difficult case is a cancellation request whose outcome is still unknown. A local “cancel sent” label does not prove the reservation has been released, and a fill may have occurred while cancellation was in flight. Refresh authoritative order and account state through the supported recovery path before reusing those funds. A prior available-balance read also cannot reserve funds for a later request when another client shares the account.
The useful end state is an explained difference with a defined timestamp: this much is held, this much is reserved, this much is usable for this action, and these observations remain unresolved. That account-level explanation comes before assigning holdings or returns to an individual bot.
Method and limits
Prepared with AI assistance using primary Binance Spot and Bybit Unified API documentation reviewed on 23 October 2026. The tables and calculations are original educational examples. No live account was queried, and these field mappings do not establish KLINEO support for a particular venue capability or a dedicated balance-reconciliation screen.