Account Monitoring

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

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.

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
Python

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

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

# 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
Python

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

# 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
wscat

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

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

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

Account Monitoring

Balance monitoring

Fetch Trade balance

Real-time balance via WebSocket

Deposit and withdrawal tracking

REST polling

Webhook-based monitoring

Order activity monitoring

Open orders

Executed orders

Real-time order updates via WebSocket

Polling vs WebSocket decision matrix

Recommended polling intervals

What’s Next

Payment Integration

WebSocket Quickstart

Trading Bot

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

​Balance monitoring

​Fetch Trade balance

​Real-time balance via WebSocket

​Subscribe to balance updates

​Deposit and withdrawal tracking

​REST polling

​Webhook-based monitoring

​Order activity monitoring

​Open orders

​Executed orders

​Real-time order updates via WebSocket

​Polling vs WebSocket decision matrix

​Recommended polling intervals

​What’s Next

Payment Integration

WebSocket Quickstart

Trading Bot

Balance monitoring

Fetch Trade balance

Real-time balance via WebSocket

Subscribe to balance updates

Deposit and withdrawal tracking

REST polling

Webhook-based monitoring

Order activity monitoring

Open orders

Executed orders

Real-time order updates via WebSocket

Polling vs WebSocket decision matrix

Recommended polling intervals

What’s Next