Balance types
Main balance — The primary holding balance. Deposits arrive here. Withdrawals leave from here. Creating a U EARN (lending) investment debits funds from Main and moves the assets into a separate investment account; the platform UI surfaces the investment as a virtual Earn balance. Main balance is not used for direct trading.- Endpoint:
POST /api/v4/main-account/balance— API Reference
available amount (ready to trade) and a freeze amount (locked in open orders).
- Endpoint:
POST /api/v4/trade-account/balance— API Reference
- Endpoint:
POST /api/v4/collateral-account/balance— API Reference
API naming convention: WhiteBIT’s API uses “collateral” endpoints for both
Margin and Futures trading. The market pair determines the product:
spot pairs (e.g.,
BTC_USDT) for Margin, perpetual pairs (e.g., BTC_PERP)
for Futures. All endpoints under /api/v4/order/collateral/ and
/api/v4/collateral-account/ serve both products.Fund flow
Transfers between balance types use a single endpoint and are fee-free. The endpoint returns201 once the transfer is queued, and the funds show on the destination balance when the transfer completes.
spot → main and main → collateral, each carrying the full amount. The platform UI exposes the same direct Trade ↔ Collateral transfer, and the same Main-routed steps happen under the hood.
- Transfer endpoint:
POST /api/v4/main-account/transfer— API Reference - Transfer history endpoint:
POST /api/v4/main-account/transfer/history— API Reference
method parameter:
deposit— Main → Tradewithdraw— Trade → Maincollateral-deposit— Main → Collateralcollateral-withdraw— Collateral → Main
Available vs. frozen balance
Each balance entry includes two fields:
Total balance =
available + freeze. Only available funds can be transferred or used to place orders.
USDTB (bonus collateral)
USDTB is a bonus collateral token used for futures trading. USDTB cannot be deposited or withdrawn — the platform grants USDTB as a bonus asset. USDTB appears in the Collateral balance and counts toward futures margin requirements. USDTB enters futures margin calculations through the futures-specific parameters:futuresEquity=equity+ USDTB. Returned by Collateral account summary.futuresFreeMargin=freeMargin+ USDTB. Returned by Collateral account summary.- Futures Margin Fraction — includes the USDTB bonus balance. Used in the ADL execution price formula.
Balance normalization
Balance normalization is an automatic conversion inside the Collateral balance. When the balance of an asset in the Collateral balance goes negative, the platform places a system-generated order of type14 to settle the negative amount. A negative asset balance is the only trigger. Typical causes are realized funding, realized negative PnL, and fees on collateral orders.
Opening a position does not trigger normalization by itself, but the fee on the opening order can. Example: the Collateral balance holds only BTC and 0 USDT. An order on BTC_USDT charges the fee in USDT, the USDT balance goes negative, and a normalization order follows.
A borrow on its own does not trigger normalization. When the account closes a borrow, normalization runs as part of the closure.
Normalization always trades on a USDT-quoted market, <ASSET>_USDT. The side depends on which asset balance is negative:
A normalization order always executes as the taker, and the platform charges the account’s taker fee. The order is not subject to self-trade prevention, so the order can match the account’s own resting order. In that case, both sides of the trade belong to the account.
To avoid normalization, keep a buffer in the Collateral balance of each asset that fees, funding, and realized PnL settle in, such as USDT. Holding other assets, such as BTC, does not stop the USDT balance from going negative.
Normalization fills appear on two WebSocket account streams:
Deposit flow
- Generate a deposit address. Use
POST /api/v4/main-account/create-new-address(API Reference) to generate a unique address per request, orPOST /api/v4/main-account/address(API Reference) to retrieve a persistent reusable address. Alternatively, create an address through the platform UI. - Send crypto to the generated address.
- Funds arrive in Main balance once the network reaches the asset’s
confirmations_for_tradingcount. - Transfer from Main to Trade (for spot orders) or to Collateral (for margin/futures positions).
confirmations count, the Main balance endpoint reports the held amount as pending_deposit_amount. The account can move the held amount to the Trade balance and trade it. The platform blocks blockchain withdrawals of the held amount, transfers of it to the Collateral balance, and transfers of it from a sub-account to its main account. When the two counts are equal, the platform holds nothing. Asset Status returns both counts per network.
Withdrawal flow
- Ensure funds are in Main balance — transfer from Trade or Collateral if needed.
- (Optional) If the held currency differs from the withdrawal currency, transfer to Trade balance, convert via the Convert feature, and transfer back to Main balance. See Payment Integration for the full withdrawal-with-conversion flow.
- Submit a withdrawal request via
POST /api/v4/main-account/withdraw. - Withdrawal processes after security checks complete.
EEA users: Crypto withdrawals require a
travelRule object with beneficiary
information (name, address, VASP). Deposits may be held for Travel Rule
verification (status codes 27, 28). See Regulatory Compliance
for full details.What’s Next
Authentication
Generate API keys and sign requests.
First API Call
Choose an integration path.
Account & Wallet API
Full endpoint documentation for balances, deposits, and withdrawals.