Skip to main content
Open a first leveraged position on WhiteBIT. Margin Trading and Futures Trading share identical API endpoints — only the pair name differs. Select a tab below to follow the steps for the preferred product.
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.

​
Prerequisites

WhiteBIT has no public testnet or sandbox. All leveraged orders execute against the live orderbook. Use minimum order amounts, low leverage (2x–5x), and prices far from market to safely test. Leveraged positions carry liquidation risk — see Margin Trading or Futures Trading for risk details.

​
Authentication Helper

All Python examples in the steps below use the following signing helper. See Authentication for the full explanation. 
import base64
import hashlib
import hmac
import json
import time
import requests

API_KEY = "YOUR_API_KEY"        # Replace with actual API key
API_SECRET = "YOUR_API_SECRET"  # Replace with actual API secret
BASE_URL = "https://whitebit.com"

def send_request(path, data=None):
    if data is None:
        data = {}
    data["request"] = path
    data["nonce"] = str(int(time.time() * 1000))
    data_json = json.dumps(data)
    payload_b64 = base64.b64encode(data_json.encode()).decode()
    signature = hmac.new(
        API_SECRET.encode(), payload_b64.encode(), hashlib.sha512
    ).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-TXC-APIKEY": API_KEY,
        "X-TXC-PAYLOAD": payload_b64,
        "X-TXC-SIGNATURE": signature,
    }
    return requests.post(BASE_URL + path, headers=headers, data=data_json).json()
For Go and PHP examples, see SDKs.

​
Steps

Margin Trading uses spot pairs (e.g., BTC_USDT) with up to 10x leverage.
1

Check collateral balance

Verify available collateral funds.
curl -X POST https://whitebit.com/api/v4/collateral-account/balance \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"request":"/api/v4/collateral-account/balance","nonce":"1700000000000"}'
Expected response:
{
  "USDT": 1000.50,
  "BTC": 0.0
}
The response maps each collateral asset to an available balance amount.
2

Set leverage

Set the account leverage to 5x. Leverage applies account-wide across all collateral positions.
curl -X POST https://whitebit.com/api/v4/collateral-account/leverage \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"leverage":5,"request":"/api/v4/collateral-account/leverage","nonce":"1700000000000"}'
Expected response:
{
  "leverage": 5
}
Allowed leverage values: 1, 2, 3, 5, 10. Margin Trading supports up to 10x.
3

Place a collateral limit order

Create a limit buy order on BTC_USDT. Set the price well below the current market price — the order remains open without filling, allowing safe testing.
curl -X POST https://whitebit.com/api/v4/order/collateral/limit \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"market":"BTC_USDT","side":"buy","amount":"0.001","price":"30000","request":"/api/v4/order/collateral/limit","nonce":"1700000000000"}'
Expected response:
{
  "order_id": 12345678,
  "market": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "amount": "0.001",
  "price": "30000",
  "...": "..."
}
When a collateral limit order fills, a position is created. Open positions include a liquidationPrice field — monitor the liquidation price for risk management. See the open positions endpoint for details.
4

Check open positions

Query open positions. If the limit order from the previous step has not filled, the response is empty. Once an order fills, positions appear with key risk fields.
curl -X POST https://whitebit.com/api/v4/collateral-account/positions/open \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"market":"BTC_USDT","request":"/api/v4/collateral-account/positions/open","nonce":"1700000000000"}'
Expected response (when a position exists):
[
  {
    "positionId": 87654321,
    "market": "BTC_USDT",
    "amount": "0.001",
    "basePrice": "65000.00",
    "pnl": "0",
    "margin": "13.00",
    "liquidationPrice": "52100.00",
    "positionSide": "LONG",
    "...": "..."
  }
]
Key fields: basePrice (entry price), liquidationPrice (price at which the position is force-closed), positionSide (LONG, SHORT, or BOTH), margin (funds allocated to the position).
5

Cancel the order

Cancel the limit order to release the reserved collateral.
curl -X POST https://whitebit.com/api/v4/order/cancel \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"market":"BTC_USDT","order_id":12345678,"request":"/api/v4/order/cancel","nonce":"1700000000000"}'
To close an open position (after a filled order), use the close position endpoint with positionId and market:
# Close an open position (when one exists)
close = send_request("/api/v4/collateral-account/position/close", {
    "positionId": 87654321,
    "market": "BTC_USDT"
})
Position successfully managed through the collateral trading API. The Margin and Futures tabs demonstrate API symmetry — identical endpoints, identical request structure, differentiated only by pair name (BTC_USDT vs. BTC_PERP).
Collateral balance isolation — Leveraged trading requires funds in the Collateral balance specifically. Depositing to the Main balance is not sufficient — an explicit transfer to Collateral is required before any collateral order can be placed. The Collateral balance is shared between Margin and Futures; there is no separate pool per product.How leverage amplifies risk — At 5x leverage, 1 USDT of collateral controls 5 USDT of market exposure. A 20% adverse price move against a 5x position wipes the allocated margin entirely, triggering partial liquidation. WhiteBIT’s partial liquidation mechanism closes 20–30% of the position first to restore margin; full liquidation follows only if that is insufficient. The liquidationPrice field in position responses shows exactly where this occurs — monitor it alongside the collateral balance in production.Why the pair name determines the product — The API has no “margin” or “futures” parameter. The endpoint paths (/api/v4/order/collateral/limit, etc.) are identical for both products. Sending BTC_USDT routes the order to Margin Trading; sending BTC_PERP routes it to Futures Trading. Leverage is also set account-wide — a single call to /api/v4/collateral-account/leverage affects all open and future positions across both products.

​
What’s Next

Margin Trading Overview

Capabilities, integration patterns, and risk context for up to 10x leverage.

Futures Trading Overview

Perpetual contracts, Hedge Mode, funding rates, and risk mechanics.

API Reference

Full endpoint documentation for all 19 collateral trading endpoints.