FAQ

Find answers to common questions about the WhiteBIT API, trading, deposits and withdrawals, webhooks, institutional onboarding, compliance, and integration.

Rate limits and errors

Rate limit 429 errors

Rate limit 429 errors occur when an endpoint exceeds the rate limit. To resolve:

• Wait for the rate limit window to reset
• Check the specific rate limit value in the endpoint documentation
• Implement rate limiting in code

For more details, see the API v4 overview. For a dettrategies

CORS errors on ticker endpoint

CORS requests to the ticker endpoint are forbidden for security reasons. Make the request from a backend server instead of client-side code. For endpoint details, see the Market activity endpoint.

Nonce error troubleshooting

Nonce errors occur when timestamps or request ordering are invalid. To resolve:

1. Debug the code implementation
2. Recreate API keys
3. Ensure system time is properly synchronized

For details on nonce requirements, see the Authentication guide. For full details on HMAC-SHA512 signing and nonce requirements, see Authentication.

Smartplan endpoint 403 access errors

Smartplan endpoints are restricted to B2B partner services only. To gain access:

• Contact [e-mail]
• Request permissions for Smartplan endpoints
• Provide use case details

For endpoint details, see the Crypto Lending documentation.

Common API error codes quick reference

The most frequent API errors and corresponding causes: 422 — validation failed (check required parameters); 429 — rate limit exceeded (wait for window reset); 401 — authentication failed (check API key and HMAC signature); 403 — insufficient permissions (verify API key permissions). See Errors and Error Handling for the complete error code reference.

WebSocket

Multiple time periods in WebSocket Kline

Multiple time periods for pairs are available through multiple WebSocket connections or the HTTP method. Two solutions:

1. Open multiple WebSocket connections
2. Use the equivalent HTTP method instead

For more details, see the Kline documentation.

Trade history limitations (24-hour window)

The system shows only the last 100 deals by default. To access more:

• Subscribe to the WebSocket feed
• Accumulate and store the data
• Process the data as needed

For more details, see the Trades channel documentation.

Server locations and colocation regions

WhiteBIT offers colocation in two regions: Europe (Frankfurt) and Asia (Tokyo), with 3-5 millisecond latency. Colocation provides access to a subset of 34 trading endpoints. See Colocation for infrastructure details and the Market Maker Guide for the full endpoint list.

Transfers and withdrawals

Transfer delays between balances

Transfers may take up to 2 seconds to complete. When making transfers and withdrawals:

• Wait for transfers to complete (approximately 2 seconds)
• Avoid initiating withdrawals before transfer completion
• Implement proper error handling for transfer states

For endpoint details, see the Transfer between balances documentation. For details on account types (Main, Trade, Collateral), see Balances & Transfers.

Insufficient funds errors despite available balance

Withdrawal amount plus fee must not exceed the available balance. Calculate the total required using the fee endpoint. Check the withdrawable amount before initiating a withdrawal. If the issue persists, review open orders possibly reserving funds. See Balances & Transfers for explanation of available vs. frozen balances.

Network confirmation requirements for deposits

Each cryptocurrency network requires a specific number of block confirmations before a deposit is credited. The webhook payload includes confirmations.actual and confirmations.required fields. Check the Asset Status endpoint for per-currency confirmation requirements.

USDT alternatives for EEA users (MiCA compliance)

Since December 30, 2024, EEA users cannot deposit, withdraw, or create WhiteBIT Codes in USDT. Use USDC (Circle holds an EU e-money license) or EURI (euro-pegged, MiCA-compliant) as alternatives. See Regulatory Compliance for details.

Below-minimum deposit handling

Deposits below the minimum amount for a currency are not credited to the account balance. Check the minimum deposit amount via the Asset Status endpoint before generating deposit addresses. No mechanism exists to recover below-minimum deposits.

Webhooks

Webhook HTTPS requirements and port

HTTPS is required for Webhook API communication:

• Communication occurs over port 443
• SSL/TLS encryption is mandatory
• HTTP connections are not supported

For more details, see the Webhook documentation.

Webhook signature verification

Each webhook request includes an X-TXC-APIKEY header and an X-TXC-PAYLOAD + X-TXC-SIGNATURE for verification. Verify the HMAC-SHA512 signature using the webhook secret key to confirm the request originates from WhiteBIT. See the Webhook reference for the full verification flow.

Webhook retry behavior

WhiteBIT retries failed webhook deliveries 5 times at 10-minute intervals, providing up to 50 minutes of coverage. There is no replay mechanism after the retry window expires. Implement polling of the deposit and withdrawal history endpoints as a fallback for outages exceeding 50 minutes. See Webhook for details.

API and assets

Currency deposit and withdrawal availability

Check currency status through the assets endpoint:

• URL: https://whitebit.com/api/v4/public/assets
• The endpoint provides real-time status of all currencies
• Check the currency-specific enabled/disabled flags

For endpoint details and response schema, see the Asset status list documentation.

Trading

Collateral endpoint naming — Margin vs Futures

The API uses “collateral” as a shared prefix for both Margin Trading (up to 10x leverage on spot pairs like BTC_USDT) and Futures Trading (up to 100x leverage on perpetual pairs like BTC_PERP). The market pair determines the product — not the endpoint path. All endpoints under /api/v4/order/collateral/ and /api/v4/collateral-account/ serve both products. See Margin Trading and Futures Trading.

Minimum order sizes per market

Each market has a minimum order amount (minAmount) and minimum order value (minTotal). Retrieve these values from GET /api/v4/public/markets (spot) or GET /api/v4/public/futures (futures). Orders below the minimum are rejected. See Markets & Trading Pairs.

Kill-switch for emergency order cancellation

The kill-switch automatically cancels all active orders after a configurable timeout. Activate via POST /api/v4/order/kill-switch with a timeout parameter (in seconds). Use POST /api/v4/order/kill-switch/status to check the current state. Designed as a safety mechanism for automated trading strategies. See the Market Maker Guide for usage patterns.

Bulk order limits

The bulk order endpoint (POST /api/v4/order/bulk) accepts up to 20 limit orders in a single request. All orders in the batch must be for the same market pair. The collateral bulk endpoint (POST /api/v4/order/collateral/bulk) follows the same 20-order limit.

Market order price in API response

The price returned in a market order response may reflect an internal limit price, not the actual execution price. To obtain the true fill price, check the trade history via POST /api/v4/trade-account/executed-history or subscribe to the WebSocket deals channel. See Order Types for market order execution details.

Reduce-only order parameter

A reduce-only order guarantees that the order only decreases or closes an existing position — the order cannot increase the position or open a new one. Set reduceOnly: true on any collateral order creation endpoint. Available on margin and futures markets only.

If no open position exists or the order direction matches the position direction, the API returns error code 116. If the order amount exceeds the current position size, the system reduces the order to match automatically.

Pending reduce-only orders are auto-canceled with status AUTO_CANCELED_REDUCE_ONLY when the associated position closes.

See Order Types — Reduce-only orders for full details.

Security and API keys

API key security best practices

Store API keys securely using environment variables, restrict IP access, and use minimum required permissions. Never commit keys to version control.

For details, see the Authentication guide. For comprehensive security guidance, see Security Best Practices.

Compromised API key response

Immediately delete the compromised key, review account activity for unauthorized actions, and create new API keys. Contact support if unauthorized activity is detected.

For details, see the Authentication guide.

API key expiration and auto-deactivation

API keys without IP address binding are automatically deactivated after 14 days of inactivity. Bind keys to specific IP addresses to prevent unexpected deactivation. See Authentication for API key management details.

API usage

High-frequency trading API optimization

Use WebSocket for real-time data, batch requests when possible, implement proper rate limiting, and cache frequently accessed data.

For details, see the WebSocket API. For rate limit tiers and endpoint-specific limits, see Rate Limits. For colocation infrastructure, see the Market Maker Guide.

API disconnection handling

Implement automatic reconnection with exponential backoff. Maintain local order state and set up monitoring and alerts for connection issues.

For details, see the WebSocket API. For a pre-launch readiness checklist including reconnection testing, see the Go-Live Checklist.

Getting started with the WhiteBIT API

Start with the First API Call guide for an orientation. The recommended path: create an API key, make a public endpoint call (no auth required), then authenticate a private endpoint call.

Available SDKs and quickstart examples

Official SDKs exist for Go, Python, and PHP. A multi-language quickstart repository provides examples in additional languages including Node.js and Rust. See the SDKs page for installation instructions and GitHub links.

Testing without a sandbox environment

WhiteBIT does not offer a public testnet or sandbox. For risk-free Spot testing, activate Demo Tokens (DBTC + DUSDT) from the WhiteBIT Codes page — no KYC required. Trade the DBTC_DUSDT pair via the standard API to validate the full order lifecycle without real funds. For Margin, Futures, and fund-movement testing, use minimum order sizes on the live API. See the Go-Live Checklist for the complete testing strategy.

REST API vs WebSocket — when to use each

Use the REST API for one-time requests: placing orders, checking balances, fetching trade history. Use the WebSocket API for real-time streaming data: live orderbook updates, trade feeds, account balance changes. REST polling at high frequency consumes rate limits — switch to WebSocket for data that updates continuously. See Rate Limits for REST constraints and WebSocket Quickstart for streaming setup.

Choosing the right SDK

Official SDKs are available for Go, Python, and PHP. Check the SDKs page for current version, maintenance status, and whether each SDK handles HMAC signing automatically. The api-quickstart repository provides additional examples in Node.js and Rust.

API access levels and prerequisites

Public endpoints (market data, tickers, orderbook) require no account or authentication. Private endpoints (trading, account management) require API keys — create them in account Settings. Institutional features (colocation, OTC, Broker Program) require institutional onboarding. See First API Call for the recommended integration path.

Institutional and partner onboarding

Available institutional products

WhiteBIT offers Market-Making Programs, Broker Program (40% fee share), Sub-Account management, OTC trading, Crypto Lending for business, colocation, and Liquidity Provision. See the Institutional Overview for the full catalog.

Institutional onboarding process

Onboarding has two phases: Phase 1 (crypto access) requires account registration, KYC for the director, and KYB verification. Phase 2 (fiat/SEPA access) requires additional documentation through the fiat processing partner. See Institutional Onboarding for the step-by-step process.

Fee structure for institutional clients

Base trading fees are 0.1% maker / 0.1% taker. The Market-Making Program offers rebates up to -0.012% maker. The Broker Program provides 40% fee share on referred user trading fees, with WBT holding boost tiers (200–2M WBT = 40–50% share). Contact [e-mail] for volume-based arrangements.

Sandbox or testnet availability

WhiteBIT does not offer a public testnet or sandbox. However, free Demo Tokens (0.5 DBTC + 1,000 DUSDT) are available for risk-free Spot trading via the WhiteBIT Codes page — no KYC required. The DBTC_DUSDT pair works with all standard Spot API endpoints. For Margin, Futures, and deposit/withdrawal testing, use minimum order sizes on the live API. See the Go-Live Checklist for the complete testing strategy.

Regulatory licenses and certifications

WhiteBIT holds licenses in multiple EU jurisdictions and is audited by Hacken for security (ISO 27001, PCI DSS, CCSS). GDPR compliance is maintained for data processing. For specific VASP authorization details and jurisdiction information, contact [e-mail]. See Regulatory Compliance.

Colocation for low-latency trading

Colocation is available in two regions: Europe (Frankfurt) and Asia (Tokyo), with 3-5 millisecond latency. Access is limited to a subset of 34 trading endpoints. See Colocation for setup details and the Market Maker Guide for the full endpoint list.

Compliance and regulatory

MiCA USDT restrictions for EEA users

Since December 30, 2024, EEA accounts cannot deposit, withdraw, or create WhiteBIT Codes in USDT under MiCA regulation. USDC and EURI are available as compliant alternatives. See Regulatory Compliance for the full list of affected operations and recommended alternatives.

Travel Rule requirements for EEA withdrawals

Since May 19, 2025, crypto withdrawals from EEA accounts require a travelRule object in the withdrawal request containing originator details (name, address, birth date, account number). The travelRule object is part of the withdrawal API request body. See Regulatory Compliance for the field reference and code examples.

Security certifications and audits

WhiteBIT is audited by Hacken. Certifications include ISO 27001, PCI DSS, and CCSS. GDPR is a regulation (not a certification) — WhiteBIT processes data in accordance with GDPR requirements. For audit reports or verification details, contact [e-mail].

What’s Next

First API Call

First steps for API integration — account setup, API keys, and the first authenticated call.

Integration Paths

Find the recommended integration path for market makers, brokers, payment providers, and algo traders.