Account Monitoring

Monitor balances, deposits, withdrawals, and order activity across Main, Trade, and Collateral accounts using REST polling and WebSocket streams.

Monitor account state across Main, Trade, and Collateral balances using REST endpoints and WebSocket streams. This guide covers balance queries, deposit/withdrawal tracking, order activity monitoring, and the decision framework for choosing between REST polling and WebSocket subscriptions. Applicable to any integration that needs real-time or periodic account state awareness.

Payment processing integrations (deposit/withdrawal monitoring): focus on the balance monitoring and deposit/withdrawal tracking sections — Main balance does not support WebSocket streaming, so webhooks and REST polling are the primary mechanisms. Trading integrations (bots, dashboards): focus on balance monitoring and order activity monitoring via WebSocket for real-time state.

Balance monitoring

WhiteBIT separates funds into three account types. Each has a dedicated balance endpoint:

Account type	Endpoint	Doc page
Main	POST /api/v4/main-account/balance	Main Balance
Trade (Spot)	POST /api/v4/trade-account/balance	Trading Balance
Collateral	POST /api/v4/collateral-account/balance	Collateral Balance

For an explanation of account types and how funds move between them, see Balances & Transfers.

Fetch Trade balance

cURL

# 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: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"request":"/api/v4/trade-account/balance","nonce":"1700000000000"}'

Python

import base64, hashlib, hmac, json, time, requests

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_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()

balance = send_request("/api/v4/trade-account/balance")
for asset, info in balance.items():
    if float(info["available"]) > 0 or float(info["freeze"]) > 0:
        print(f"{asset}: available={info['available']}, freeze={info['freeze']}")

For Go and PHP examples, see SDKs.

Response fields:

• available — funds ready for trading or withdrawal
• freeze — funds locked in open orders or pending operations

Real-time balance via WebSocket

REST polling provides point-in-time snapshots. For instant balance change notifications, subscribe to WebSocket account streams:

Channel	Subscribe method	Use case
Balance Spot	balanceSpot_subscribe	Spot (Trade) balance changes
Balance Margin	balanceMargin_subscribe	Collateral balance changes (Margin + Futures)

Main balance does not have a WebSocket subscription channel. Monitor Main balance changes — including deposit arrivals — via webhooks for real-time notifications or REST polling of POST /api/v4/main-account/history as a fallback.

Subscribe to balance updates

The following example assumes an authenticated WebSocket session. See WebSocket Quickstart — Authenticate for private channels for the full authentication flow. Without authentication, the subscription request is rejected.

import json, websockets, asyncio

async def monitor_balance():
    async with websockets.connect("wss://api.whitebit.com/ws") as ws:
        # Authenticate first — see WebSocket Quickstart Step 4 for the full flow.
        # Without auth, balanceSpot_subscribe silently fails.

        # Subscribe to spot balance changes.
        # params: [] subscribes to all assets.
        # Pass specific tickers (e.g., ["USDT", "BTC"]) to filter updates.
        await ws.send(json.dumps({
            "id": 1,
            "method": "balanceSpot_subscribe",
            "params": []
        }))

        async for message in ws:
            data = json.loads(message)
            # Subscription confirmation has a "result" key.
            # Balance updates have a "method" key set to "balanceSpot_update".
            if "method" in data and data["method"] == "balanceSpot_update":
                for asset, info in data["params"].items():
                    print(f"Balance change: {asset} available={info['available']} freeze={info['freeze']}")

asyncio.run(monitor_balance())

Deposit and withdrawal tracking

REST polling

Query deposit and withdrawal history using the main account history endpoint:

Endpoint: POST /api/v4/main-account/history

cURL

curl -X POST https://whitebit.com/api/v4/main-account/history \
  -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 '{"transactionMethod":1,"request":"/api/v4/main-account/history","nonce":"1700000000000"}'

Python

# Fetch recent deposits (transactionMethod: 1 = deposits, 2 = withdrawals)
deposits = send_request("/api/v4/main-account/history", {
    "transactionMethod": 1,
    "limit": 50
})
for record in deposits.get("records", []):
    print(f"{record['ticker']}: {record['amount']} — status {record['status']}")

Webhook-based monitoring

For real-time deposit and withdrawal notifications, configure webhooks. Webhook delivery includes up to 5 retries at 10-minute intervals (50-minute coverage window).

Recommended reconciliation approach:

• Primary: Webhooks — process events as they arrive for near-instant updates
• Fallback: REST polling — periodically query the history endpoint to catch any events missed during webhook downtime or after the 50-minute retry window expires

See Webhooks for setup, signature verification, and event types. For the full deposit/withdrawal lifecycle including status state machines and fee calculation, see Payment Integration.

Order activity monitoring

Open orders

Query active orders across all markets or filter by a specific market:

Endpoint: POST /api/v4/orders

cURL

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: BASE64_PAYLOAD" \
  -H "X-TXC-SIGNATURE: HMAC_SIGNATURE" \
  -d '{"market":"BTC_USDT","request":"/api/v4/orders","nonce":"1700000000000"}'

Python

# Fetch all open orders for BTC_USDT
open_orders = send_request("/api/v4/orders", {"market": "BTC_USDT"})
print(f"Open orders: {len(open_orders)}")
for order in open_orders:
    print(f"  {order['side']} {order['amount']} @ {order['price']} (ID: {order['order_id']})")

Executed orders

Query trade history for filled and canceled orders:

Endpoint: POST /api/v4/trade-account/order/history

cURL

curl -X POST https://whitebit.com/api/v4/trade-account/order/history \
  -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/trade-account/order/history","nonce":"1700000000000"}'

Python

# Fetch order history for BTC_USDT
history = send_request("/api/v4/trade-account/order/history", {"market": "BTC_USDT"})
for market, orders in history.items():
    for order in orders[:5]:
        print(f"  {order['side']} {order['amount']} @ {order['price']} — {order.get('type', 'unknown')}")

Real-time order updates via WebSocket

For instant order state change notifications, subscribe to account streams:

Channel	Subscribe method	Events
Orders Pending	ordersPending_subscribe	Order placed, partially filled, canceled
Deals	deals_subscribe	Trade executions (fills)

For final order state with aggregate data (fully filled or canceled), see also Orders Executed.

Python

# Subscribe to order updates and trade fills
await ws.send(json.dumps({
    "id": 2,
    "method": "ordersPending_subscribe",
    "params": ["BTC_USDT"]
}))
await ws.send(json.dumps({
    "id": 3,
    "method": "deals_subscribe",
    "params": [["BTC_USDT"]]
}))

wscat

> {"id": 2, "method": "ordersPending_subscribe", "params": ["BTC_USDT"]}
> {"id": 3, "method": "deals_subscribe", "params": [["BTC_USDT"]]}

Polling vs WebSocket decision matrix

Use case	Recommended approach	Reason
Balance snapshot	REST	One-time check, no persistent connection needed
Live balance changes	WebSocket	Instant notification on every change
Deposit/withdrawal status	Webhook + REST fallback	Reliability — webhooks for speed, REST for reconciliation
Open order monitoring	WebSocket	Real-time state changes (fills, cancellations)
Historical trades	REST	Paginated query over a time range

General guidance: Use REST for on-demand queries and historical data. Use WebSocket for any data that changes frequently and requires immediate reaction. Combine both: WebSocket for primary real-time flow, REST for startup state hydration and periodic reconciliation.

Recommended polling intervals

When using REST polling, align the interval with the use case and the endpoint rate budget. See Rate Limits & Error Codes for per-scope request limits.

Use case	Endpoint	Suggested interval
Balance dashboard	POST /api/v4/trade-account/balance	5–30 seconds
Deposit detection (fallback)	POST /api/v4/main-account/history	5 minutes
Order history reconciliation	POST /api/v4/trade-account/order/history	30–60 seconds

What’s Next

Payment Integration

Full deposit/withdrawal lifecycle, fee calculation, and reconciliation.

WebSocket Quickstart

Connection setup, authentication, and real-time data streaming.

Trading Bot

End-to-end automated trading with order management and error handling.