💰 What is an Account Balance API?
An Account Balance API is a programmatic interface that allows you to retrieve your cryptocurrency balances from an exchange. It provides access to:
- Spot balances — funds in your spot wallet.
- Futures balances — funds in your futures account.
- Earn balances — funds in staking, savings, or other earn products.
- Balance types — available (free to use), locked (in orders or staking), and total (available + locked).
Account Balance APIs are authenticated endpoints — they require an API key with Read permissions. They are essential for trading bots, portfolio trackers, and any application that needs to know how much capital is available.
- Before placing orders: Ensure you have sufficient funds.
- Risk management: Monitor portfolio exposure.
- Position sizing: Calculate position sizes based on available capital.
- Reconciliation: Verify balances match your records.
📊 Understanding Balance Types
When you retrieve your balance, the API returns different types of balances. Understanding them is crucial for accurate position management.
The amount you can use for trading, withdrawals, or transfers. This is the balance you should check before placing orders.
Funds that are unavailable because they're in open orders, staking, or other active positions. You cannot use these funds until they are unlocked.
The sum of available and locked balances. This is your total position in the asset.
For futures accounts, this includes unrealized P&L. It represents the total value of your account if all positions were closed at current prices.
If you have 1.0 BTC in your spot wallet, with 0.2 BTC locked in an open order, then:
Available = 0.8 BTC, Locked = 0.2 BTC, Total = 1.0 BTC.
📋 Key Account Balance Endpoints
Here are the most important balance endpoints across major exchanges. Note that endpoints differ by exchange.
| Endpoint | Description | Method | Requires Auth? |
|---|---|---|---|
/api/v3/account |
Get all spot account balances | GET | Yes (Read) |
/fapi/v1/account |
Get futures account balances | GET | Yes (Read) |
/api/v3/account/asset |
Get balance for a specific asset | GET | Yes (Read) |
/api/v5/asset/balances |
OKX — Get spot account balances | GET | Yes (Read) |
/api/v5/asset/funding-balance |
OKX — Get funding account balances | GET | Yes (Read) |
/v5/account/wallet-balance |
Bybit — Get wallet balances | GET | Yes (Read) |
Endpoint URLs vary by exchange. Binance uses /api/v3/ for spot and /fapi/v1/ for futures. OKX uses /api/v5/. Bybit uses /v5/. Always refer to the exchange's official API documentation.
💎 Checking Spot Balances
Spot balances represent the funds in your main trading account. Here's how to retrieve them.
Get All Spot Balances
Get a Specific Asset Balance
The account endpoint returns a list of balances. Each balance typically includes:
- asset: The asset symbol (e.g., BTC, ETH, USDT).
- free: Available balance (can be used for trading or withdrawal).
- locked: Locked balance (in open orders, staking, etc.).
- total: free + locked.
Before placing an order, always check your available balance to ensure you have sufficient funds. Consider reserving a small buffer for fees, especially for market orders where the exact cost may vary.
📈 Checking Futures Balances
Futures balances are separate from spot balances and include margin, unrealized P&L, and available funds for leveraged trading.
Get Futures Account Info
The futures account endpoint returns:
- totalCrossMargin: Total margin in cross margin mode.
- totalIsolatedMargin: Total margin in isolated margin mode.
- totalUnrealizedProfit: Unrealized P&L across all positions.
- totalAvailableBalance: Available funds for trading.
- assets: List of assets with margin balances.
Futures balances include unrealized P&L. This means the balance can change rapidly with market movements. Always use the available balance (not total balance) when determining how much margin you can use.
🏦 Checking Earn Account Balances
Earn balances represent funds in staking, savings, or other earn products. These funds are typically locked and not available for trading.
Get Earn Balances
Some exchanges have separate endpoints for earn balances. Check the exchange's documentation for specific earn balance endpoints.
When calculating your total net worth on an exchange, sum up spot, futures, and earn balances. However, for trading decisions, only use the available balance in your spot account.
🏆 Best Practices for Balance APIs
Follow these best practices when working with Account Balance APIs.
-
1
Cache balances locally
Balances don't change every millisecond. Cache the response for 1-5 seconds to reduce API calls and rate limit usage.
-
2
Check available balance before orders
Always verify you have sufficient available balance before placing an order to avoid "insufficient balance" errors.
-
3
Monitor locked balances
If your locked balance is high, you may have open orders or positions that are consuming funds. Monitor this to understand your capital usage.
-
4
Use WebSocket for real-time updates
Some exchanges offer WebSocket streams for account balance updates, providing real-time balance changes without polling.
-
5
Handle authentication errors
If your API key expires or permissions change, your balance requests will fail. Implement proper error handling and monitoring.
-
6
Respect rate limits
Balance endpoints are authenticated and typically have lower rate limits than public endpoints. Cache responses to minimize requests.