Margin & Futures Quickstart

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

A WhiteBIT account (register)
An API key with Trading permission (create one)
Funds in the Collateral balance (transfer from Main balance if needed — see Balances & Transfers)
Familiarity with HMAC-SHA512 signing — see Authentication

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

The signing helper signs every Python example in this page. See Authentication for the full HMAC-SHA512 derivation.

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
Futures Trading

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

Check collateral balance

Verify available collateral funds.

cURL
Python

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"}'

balance = send_request("/api/v4/collateral-account/balance")
print(balance)

Expected response:

{
  "USDT": 1000.50,
  "BTC": 0.0
}

The response maps each collateral asset to an available balance amount.

Set leverage

Set the account leverage to 5x. Leverage applies account-wide across all collateral positions.

cURL
Python

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"}'

result = send_request("/api/v4/collateral-account/leverage", {
    "leverage": 5
})
print(result)

Expected response:

{
  "leverage": 5
}

Allowed leverage values: 1, 2, 3, 5, 10. Margin Trading supports up to 10x.

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
Python

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"}'

order = send_request("/api/v4/order/collateral/limit", {
    "market": "BTC_USDT",
    "side": "buy",
    "amount": "0.001",
    "price": "30000"  # Price far below market — order will not fill
})
print(order)
orderId = order.get("orderId")
print(f"Order ID: {orderId}")

Expected response:

{
  "orderId": 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.

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
Python

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"}'

positions = send_request("/api/v4/collateral-account/positions/open", {
    "market": "BTC_USDT"
})
print(positions)
for pos in positions:
    print(f"  Position {pos['positionId']}: {pos['positionSide']} "
          f"liquidation at {pos['liquidationPrice']}")

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).

Cancel the order

Cancel the limit order to release the reserved collateral.

cURL
Python

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","orderId":12345678,"request":"/api/v4/order/cancel","nonce":"1700000000000"}'

cancel = send_request("/api/v4/order/cancel", {
    "market": "BTC_USDT",
    "orderId": orderId
})
print(cancel)

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"
})

Futures Trading uses perpetual pairs (e.g., BTC_PERP) with up to 100x leverage and optional Hedge Mode.

Check collateral balance

Verify available collateral funds. The same Collateral balance serves both Margin and Futures.

cURL
Python

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"}'

balance = send_request("/api/v4/collateral-account/balance")
print(balance)

Expected response:

{
  "USDT": 1000.50,
  "BTC": 0.0
}

Set leverage

Set account leverage to 5x. Leverage applies account-wide. Futures supports up to 100x, but use a conservative value for testing.

cURL
Python

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"}'

result = send_request("/api/v4/collateral-account/leverage", {
    "leverage": 5
})
print(result)

Expected response:

{
  "leverage": 5
}

Allowed leverage values: 1, 2, 3, 5, 10, 20, 50, 100.

Enable Hedge Mode (optional)

Hedge Mode allows simultaneous long and short positions on the same pair. Skip to disable (default: one-directional positions only).

cURL
Python

curl -X POST https://whitebit.com/api/v4/collateral-account/hedge-mode/update \
  -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 '{"hedgeMode":true,"request":"/api/v4/collateral-account/hedge-mode/update","nonce":"1700000000000"}'

hedge = send_request("/api/v4/collateral-account/hedge-mode/update", {
    "hedgeMode": True
})
print(hedge)

Check the current mode at any time:

mode = send_request("/api/v4/collateral-account/hedge-mode")
print(mode)  # {"hedgeMode": true}

Place a collateral limit order

Create a limit buy order on BTC_PERP. Set the price well below the current market price — the order remains open without filling, allowing safe testing.

cURL
Python

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_PERP","side":"buy","amount":"0.001","price":"30000","request":"/api/v4/order/collateral/limit","nonce":"1700000000000"}'

order = send_request("/api/v4/order/collateral/limit", {
    "market": "BTC_PERP",
    "side": "buy",
    "amount": "0.001",
    "price": "30000"  # Price far below market — order will not fill
})
print(order)
orderId = order.get("orderId")
print(f"Order ID: {orderId}")

Expected response:

{
  "orderId": 12345678,
  "market": "BTC_PERP",
  "side": "buy",
  "type": "limit",
  "amount": "0.001",
  "price": "30000",
  "...": "..."
}

The only difference from the Margin tab: BTC_PERP (perpetual pair) instead of BTC_USDT (spot pair). The API endpoint and request structure are identical.

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 including liquidationPrice.

cURL
Python

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_PERP","request":"/api/v4/collateral-account/positions/open","nonce":"1700000000000"}'

positions = send_request("/api/v4/collateral-account/positions/open", {
    "market": "BTC_PERP"
})
print(positions)
for pos in positions:
    print(f"  Position {pos['positionId']}: {pos['positionSide']} "
          f"liquidation at {pos['liquidationPrice']}")

Expected response (when a position exists):

[
  {
    "positionId": 87654321,
    "market": "BTC_PERP",
    "amount": "0.001",
    "basePrice": "65000.00",
    "pnl": "0",
    "margin": "13.00",
    "liquidationPrice": "52100.00",
    "positionSide": "LONG",
    "...": "..."
  }
]

Key fields: basePrice (entry price), liquidationPrice (price triggering forced closure — uses mark price, not last traded price), positionSide (LONG, SHORT, or BOTH in Hedge Mode), margin (funds allocated to the position).

Cancel the order

Cancel the limit order to release the reserved collateral.

cURL
Python

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_PERP","orderId":12345678,"request":"/api/v4/order/cancel","nonce":"1700000000000"}'

cancel = send_request("/api/v4/order/cancel", {
    "market": "BTC_PERP",
    "orderId": orderId
})
print(cancel)

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_PERP"
})

The limit order is canceled and the reserved collateral returns to the available Collateral balance. Margin and Futures share endpoint paths verbatim — only the pair name (BTC_USDT vs BTC_PERP) routes the order.

What just happened?

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.

What’s Next

Margin Trading Overview

Isolated Margin mode, 6 order types (Limit, Market, Stop-Limit, Trigger-Market, OCO, Bulk-Limit), partial-liquidation flow at 20–30%, and the borrowed-funds fee model.

Futures Trading Overview

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

API Reference

Full endpoint documentation for all 19 collateral trading endpoints.

Group

Documentation Index

​Prerequisites

​Authentication Helper

​Steps

​What’s Next

Margin Trading Overview

Futures Trading Overview

API Reference

Prerequisites

Authentication Helper

Steps

What’s Next