> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/account-wallet/main-balance)                         |
| Trade (Spot) | `POST /api/v4/trade-account/balance`      | [Trading Balance](/api-reference/spot-trading/trading-balance)                     |
| Collateral   | `POST /api/v4/collateral-account/balance` | [Collateral Balance](/api-reference/collateral-trading/collateral-account-balance) |

For an explanation of account types and how funds move between them, see [Balances & Transfers](/concepts/balances).

### Fetch Trade balance

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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"] = 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']}")
    ```
  </Tab>
</Tabs>

For Go and PHP examples, see [SDKs](/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](/websocket/account-streams/balance-spot)     | `balanceSpot_subscribe`   | Spot (Trade) balance changes                  |
| [Balance Margin](/websocket/account-streams/balance-margin) | `balanceMargin_subscribe` | Collateral balance changes (Margin + Futures) |

<Note>
  Main balance does not have a WebSocket subscription channel. Monitor Main balance changes — including deposit arrivals — via [webhooks](/platform/webhook) for real-time notifications or REST polling of `POST /api/v4/main-account/history` as a fallback.
</Note>

### Subscribe to balance updates

The following example assumes an authenticated WebSocket session. See [WebSocket Quickstart — Authenticate for private channels](/guides/websocket-quickstart#authenticate-for-private-channels) for the full authentication flow. Without authentication, the subscription request is rejected.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`](/api-reference/account-wallet/get-deposit-withdraw-history)

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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']}")
    ```
  </Tab>
</Tabs>

### Webhook-based monitoring

For real-time deposit and withdrawal notifications, configure webhooks. Webhook delivery is best-effort — a small number of retries spaced roughly an hour apart over a window of about one day. Treat the exact cadence as not contractually guaranteed.

**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 retry window expires

See [Webhooks](/platform/webhook) for setup, signature verification, and event types. For the full deposit/withdrawal lifecycle including status state machines and fee calculation, see [Payment Integration](/guides/payment-integration).

## Order activity monitoring

### Open orders

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

**Endpoint:** [`POST /api/v4/orders`](/api-reference/spot-trading/query-unexecuted-orders)

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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['orderId']})")
    ```
  </Tab>
</Tabs>

### Executed orders

Query trade history for filled and canceled orders:

**Endpoint:** [`POST /api/v4/trade-account/order/history`](/api-reference/spot-trading/query-executed-orders)

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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')}")
    ```
  </Tab>
</Tabs>

### Real-time order updates via WebSocket

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

| Channel                                                     | Subscribe method          | Events                                   |
| ----------------------------------------------------------- | ------------------------- | ---------------------------------------- |
| [Orders Pending](/websocket/account-streams/orders-pending) | `ordersPending_subscribe` | Order placed, partially filled, canceled |
| [Deals](/websocket/account-streams/deals)                   | `deals_subscribe`         | Trade executions (fills)                 |

For final order state with aggregate data (fully filled or canceled), see also [Orders Executed](/websocket/account-streams/orders-executed).

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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"]]
    }))
    ```
  </Tab>

  <Tab title="wscat">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    > {"id": 2, "method": "ordersPending_subscribe", "params": ["BTC_USDT"]}
    > {"id": 3, "method": "deals_subscribe", "params": [["BTC_USDT"]]}
    ```
  </Tab>
</Tabs>

## 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](/api-reference/rate-limits) 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

<CardGroup cols={3}>
  <Card title="Payment Integration" icon="money-bill" href="/guides/payment-integration">
    Full deposit/withdrawal lifecycle, fee calculation, and reconciliation.
  </Card>

  <Card title="WebSocket Quickstart" icon="plug" href="/guides/websocket-quickstart">
    Connection setup, authentication, and real-time data streaming.
  </Card>

  <Card title="Trading Bot" icon="robot" href="/guides/building-a-trading-bot">
    End-to-end automated trading with order management and error handling.
  </Card>
</CardGroup>