> ## Documentation Index > Fetch the complete documentation index at: https://whitebit-mintlify-fix-broken-links-1777248521.mintlify.site/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. export const RegionBaseUrl = ({className = "", showBaseUrl = true}) => { const [region, setRegionState] = useState(() => { if (typeof window !== 'undefined') { return localStorage.getItem("api-region-preference") || "com"; } return "com"; }); const [mounted, setMounted] = useState(false); const observerRef = useRef(null); const isSyncingRef = useRef(false); const updateAllContentOnPage = targetRegion => { try { const domainFrom = targetRegion === "eu" ? "whitebit.com" : "whitebit.eu"; const domainTo = targetRegion === "eu" ? "whitebit.eu" : "whitebit.com"; const links = document.querySelectorAll('a'); links.forEach(link => { let href = link.getAttribute('href'); if (href && href.includes(domainFrom)) { link.setAttribute('href', href.replace(domainFrom, domainTo)); } }); const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, { acceptNode: node => { if (node.parentElement?.closest('.region-toggle-component')) { return NodeFilter.FILTER_REJECT; } return node.textContent.includes(domainFrom) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT; } }); let currentNode; while (currentNode = walker.nextNode()) { currentNode.textContent = currentNode.textContent.replace(new RegExp(domainFrom, 'g'), domainTo); } console.log(`[RegionSync] Global content updated to ${domainTo}`); } catch (e) { console.error("[RegionSync] Error updating content:", e); } }; const updateRegion = (newRegion, source) => { if (region === newRegion) return; console.log(`[RegionBaseUrl] Updating to "${newRegion}" (Source: ${source})`); if (source === 'observer') { isSyncingRef.current = true; setTimeout(() => isSyncingRef.current = false, 1000); } setRegionState(newRegion); localStorage.setItem("api-region-preference", newRegion); updateAllContentOnPage(newRegion); if (source === 'user-click') { window.dispatchEvent(new CustomEvent("regionChange", { detail: newRegion })); attemptToUpdateNativeDropdown(newRegion, 0); setTimeout(() => attemptToUpdateNativeDropdown(newRegion, 1), 500); setTimeout(() => attemptToUpdateNativeDropdown(newRegion, 2), 1500); } }; const attemptToUpdateNativeDropdown = (targetRegion, attempt) => { if (isSyncingRef.current) return; try { const targetUrl = targetRegion === "eu" ? "https://whitebit.eu" : "https://whitebit.com"; const targetDesc = targetRegion === "eu" ? "EU Server" : "Production Server"; const selects = document.querySelectorAll('select'); for (const select of selects) { if (select.innerHTML.includes('whitebit.com') || select.innerHTML.includes('whitebit.eu')) { select.value = targetUrl; select.dispatchEvent(new Event('change', { bubbles: true })); return; } } const buttons = Array.from(document.querySelectorAll('button, [role="combobox"]')); const serverSelector = buttons.find(btn => { if (btn.closest('a') || btn.closest('[class*="card"]') || btn.closest('nav')) { return false; } const txt = btn.textContent || ""; const isServerDropdown = (txt.includes('Production Server') || txt.includes('EU Server') || txt.includes('WhiteBIT Global Server') || txt.includes('WhiteBIT EU Server')) && !txt.includes('Run') && !txt.includes('Send') || btn.getAttribute('role') === 'combobox'; return isServerDropdown; }); if (serverSelector) { const currentText = serverSelector.textContent || ""; if (currentText.includes(targetDesc)) return; serverSelector.click(); setTimeout(() => { const options = document.querySelectorAll('[role="option"], li, button'); for (const opt of options) { const optText = opt.textContent || ""; if (optText.includes(targetDesc) || optText.includes(targetUrl)) { opt.click(); return; } } }, 100); } } catch (e) { console.error("[Sync] Error:", e); } }; useEffect(() => { setMounted(true); updateAllContentOnPage(region); const handleStorageChange = e => { if (e.key === "api-region-preference" && e.newValue) { updateRegion(e.newValue, 'storage'); } }; const handleRegionChange = e => { if (e.detail !== region) { updateRegion(e.detail, 'event'); } }; window.addEventListener("storage", handleStorageChange); window.addEventListener("regionChange", handleRegionChange); observerRef.current = new MutationObserver(mutations => { if (isSyncingRef.current) return; updateAllContentOnPage(region); for (const mutation of mutations) { if (mutation.type !== 'childList' && mutation.type !== 'characterData') continue; const target = mutation.target; const el = target.nodeType === Node.TEXT_NODE ? target.parentElement : target; if (el && (el.getAttribute('role') === 'option' || el.closest('[role="listbox"]'))) continue; const text = target.textContent || ""; if (text.includes('WhiteBIT EU Server') || text.includes('https://whitebit.eu') && text.includes('Server')) { if (el && el.tagName !== 'A' && !el.closest('.region-toggle-component')) { if (region !== 'eu') updateRegion('eu', 'observer'); } } else if (text.includes('WhiteBIT Global Server') || text.includes('https://whitebit.com') && text.includes('Server')) { if (el && el.tagName !== 'A' && !el.closest('.region-toggle-component')) { if (region !== 'com') updateRegion('com', 'observer'); } } } }); observerRef.current.observe(document.body, { childList: true, subtree: true, characterData: true }); if (typeof window !== 'undefined') { const current = localStorage.getItem("api-region-preference"); if (current) attemptToUpdateNativeDropdown(current, 'init'); } return () => { window.removeEventListener("storage", handleStorageChange); window.removeEventListener("regionChange", handleRegionChange); if (observerRef.current) observerRef.current.disconnect(); }; }, [region]); const apiBaseUrl = region === "eu" ? "https://whitebit.eu" : "https://whitebit.com"; if (!mounted) return null; return
Base URL (
) {showBaseUrl && <> : {apiBaseUrl} }
; }; 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 ```bash theme={null} # 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 theme={null} 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](/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) | 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. ### 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={null} 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) ```bash theme={null} 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 theme={null} # 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](/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) ```bash theme={null} 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 theme={null} # 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`](/api-reference/spot-trading/query-executed-orders) ```bash theme={null} 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 theme={null} # 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](/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). ```python theme={null} # 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"]] })) ``` ```bash theme={null} > {"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](/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 Full deposit/withdrawal lifecycle, fee calculation, and reconciliation. Connection setup, authentication, and real-time data streaming. End-to-end automated trading with order management and error handling.