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

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
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)
order_id = order.get("order_id")
print(f"Order ID: {order_id}")

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.

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

cancel = send_request("/api/v4/order/cancel", {
    "market": "BTC_USDT",
    "order_id": order_id
})
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)
order_id = order.get("order_id")
print(f"Order ID: {order_id}")

Expected response:

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

cancel = send_request("/api/v4/order/cancel", {
    "market": "BTC_PERP",
    "order_id": order_id
})
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"
})

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

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

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

Margin & Futures Quickstart

Prerequisites

Authentication Helper

Steps

What’s Next

Margin Trading Overview

Futures Trading Overview

API Reference

​Prerequisites

​Authentication Helper

​Steps

​What’s Next

Margin Trading Overview

Futures Trading Overview

API Reference

Prerequisites

Authentication Helper

Steps

What’s Next