Spot Trading Quickstart

Place a limit order on BTC_USDT against the live orderbook with HMAC-SHA512 signing. The four-step block below uses a price far below market, so the order opens but does not fill — safe for testing without risking a fill.

Prerequisites

A WhiteBIT account (register)
An API key with Trading permission (create one)
Funds in the Trade 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 orders execute against the live orderbook. For risk-free practice, use Demo Tokens (DBTC/DUSDT) — activate from the WhiteBIT Codes page. For real-asset testing, use minimum order sizes and cancel test orders after verification.

Check Trade balance

Verify available funds before placing an order.

cURL
Python

# See /api-reference/authentication for signing details.
curl -X POST https://whitebit.com/api/v4/trade-account/balance \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -d '{"ticker":"USDT","request":"/api/v4/trade-account/balance","nonce":"1700000000000"}'

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_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()

# Check USDT balance
balance = send_request("/api/v4/trade-account/balance", {"ticker": "USDT"})
print(balance)

Expected response:

{
  "USDT": {
    "available": "1000.00",
    "freeze": "0"
  }
}

available = funds ready for trading. freeze = funds locked in active orders.

The cURL examples show request structure with placeholder headers. For a runnable signing implementation, use the Python tab or the API Quick Start Helper library (Python, Go, PHP, Node.js, and more).

For Go and PHP examples, see SDKs.

Place a limit order

Create a limit buy order on BTC_USDT. Set the price well below the current market price to avoid immediate execution — the order remains open for safe testing.

cURL
Python

# Set price well below current market to prevent execution.
curl -X POST https://whitebit.com/api/v4/order/new \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -d '{"market":"BTC_USDT","side":"buy","amount":"0.0001","price":"30000","request":"/api/v4/order/new","nonce":"1700000000000"}'

order = send_request("/api/v4/order/new", {
    "market": "BTC_USDT",
    "side": "buy",
    "amount": "0.0001",
    "price": "30000"       # Well below market — adjust if needed
})
print(order)
orderId = order.get("orderId")
print(f"Order ID: {orderId}")

Expected response:

{
  "orderId": 12345678,
  "clientOrderId": "",
  "market": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "timestamp": 1700000000.000,
  "amount": "0.0001",
  "price": "30000",
  "...": "..."
}

Request fields: market (trading pair), side (“buy” or “sell”), amount (quantity in the base asset), price (limit price in the quote asset). Optional: clientOrderId (custom identifier), stp (self-trade prevention mode).

Check active orders

Verify the newly placed order appears in the active orders list.

cURL
Python

curl -X POST https://whitebit.com/api/v4/orders \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -d '{"market":"BTC_USDT","request":"/api/v4/orders","nonce":"1700000000000"}'

active_orders = send_request("/api/v4/orders", {"market": "BTC_USDT"})
print(f"Active orders: {len(active_orders)}")
for o in active_orders:
    print(f"  Order {o['orderId']}: {o['side']} {o['amount']} @ {o['price']}")

Expected response (trimmed):

[
  {
    "orderId": 12345678,
    "market": "BTC_USDT",
    "side": "buy",
    "amount": "0.0001",
    "price": "30000",
    "...": "..."
  }
]

Cancel the order

Cancel the limit order using the orderId returned in Step 2.

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: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_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)

Expected response:

{
  "orderId": 12345678,
  "market": "BTC_USDT",
  "side": "buy",
  "amount": "0.0001",
  "price": "30000",
  "...": "..."
}

The response confirms the canceled order details. The previously frozen funds return to the available Trade balance.

To verify canceled orders later, query the order history endpoint.

The Trade balance now reflects the returned funds.

Trade balance vs Main balance — WhiteBIT separates funds into Main balance (deposits, withdrawals) and Trade balance (order placement). An explicit transfer moves funds between balances; the API never draws from Main balance automatically. When a limit order is accepted, the required funds move from available to freeze in the Trade balance — after cancellation, freeze returns to zero and available is restored. Details: Balances & Transfers.

What’s next

Margin & Futures Quickstart

Open a first leveraged position with up to 100x leverage.

Order Types

Explore all 6 order types including Stop-Limit and Bulk-Limit.

Trading Bot Guide

REST and WebSocket together — order placement, kill-switch heartbeat, fill monitoring, reconnect logic, and a grid-bot worked example.

​Prerequisites

​What’s next

Margin & Futures Quickstart

Order Types

Trading Bot Guide

Prerequisites

What’s next