Authentication
- API key created with the minimum required permission level.
- API secret stored in environment variables or a secrets manager — not in source code.
- HMAC-SHA512 signing implemented and verified against a known-good response.
- IP whitelist configured with production server IPs (up to 50 per key).
- 2FA enabled on the WhiteBIT account.
- Nonce implementation generates strictly increasing values (Unix timestamp in milliseconds recommended).
Error handling
- HTTP status codes handled:
200(success),400(validation),401(auth),403(forbidden),422(unprocessable),429(rate limit),500/503(server error). - Rate limit responses (
429) handled with exponential backoff and retry. - Authentication errors (
401) do NOT trigger automatic retry — investigate the cause. - Validation errors (
400,422) logged with the full response body for debugging. - Server errors (
500,503) handled with retry and exponential backoff. - A timeout or a
5xxon a transfer between balances or with a sub-account does not trigger an automatic retry, because the transfer requests take no idempotency key and a transfer can still complete after the failure. Between balances: a matching record in the transfer history means the transfer completed, and no record can also mean the transfer is still queued, so repeat the check instead of resending. Sub-account transfer: the sub-account’smainbalance fromPOST /api/v4/sub-account/balancesconfirms the transfer, after a200as well, because the transfer can still fail after the response. The integration stores a record of each transfer before the call and reads the balance until it shows the transfer. A transfer that never shows is a manual check. - Error response JSON parsed for
code,message, anderrorsfields.
Rate limits
- Per-endpoint rate limits documented and enforced in the application.
- Request queuing implemented to stay within rate limits.
- Bulk endpoints used where available (e.g.,
/order/bulkfor up to 20 orders per call). - WebSocket used for real-time data instead of REST polling where possible.
- Public endpoint caching implemented for data that changes infrequently (market list, asset status).
Regional compliance (EEA)
- Travel Rule:
travelRuleobject included in all EEA crypto withdrawal requests. - MiCA: USDT deposit/withdrawal/code operations NOT attempted for EEA accounts (blocked since December 30, 2024).
- USDT alternatives: USDC and EURI used for EEA users instead of USDT.
- Asset Status endpoint (
GET /api/v4/public/assets) checked dynamically for currency availability. - Travel Rule deposit freezes (status 27, 28) handled in the deposit reconciliation flow.
WebSocket
- Automatic reconnection implemented with exponential backoff.
- Channel re-subscription occurs after every reconnection.
- Ping/pong heartbeat mechanism implemented to detect stale connections.
- WebSocket authentication token refreshed before expiry (if using private channels).
- Message ordering verified — check sequence numbers where available.
Webhooks
- Webhook URL configured (see Webhooks).
- Domain verification completed (DNS TXT, file, or endpoint method).
- HMAC-SHA512 signature verification implemented on every incoming webhook.
- Webhook nonce tracked — each nonce is strictly greater than the previous.
- Idempotency implemented using
uniqueIdto prevent double-processing. - Fallback polling implemented for reconciliation. Webhook delivery is best-effort — a small number of retries spaced roughly hourly over a ~1-day window — so polling must close the gap for extended consumer outages.
- Deposits polled without a
statusfilter; deposits in non-final statuses (5, 21, 22, 23, 27, 28, 29) stay open until a final status (3, 7, 4, 9). - Webhook source IP range obtained from the account manager, if the firewall allowlists inbound traffic.
- Server responds with HTTP
200for successfully processed webhooks.
Monitoring
- Balance monitoring active — alerts on unexpected balance changes.
- Order status monitoring — track open orders and detect stuck states.
- Kill-switch configured for trading applications — one timer per traded market; cancels that market’s open orders after a timeout if the system becomes unresponsive.
- API response time monitoring — detect latency degradation.
- Error rate monitoring — alert on elevated error rates (especially
429and500).
Testing
WhiteBIT does not offer a public testnet. The following approach validates an integration on the live API with minimal risk.-
Start with Demo Tokens (risk-free): Activate free Demo Tokens (0.5 DBTC + 1,000 DUSDT) via the WhiteBIT Codes page — no KYC required. Trade the
DBTC_DUSDTspot pair viaPOST /api/v4/order/newto validate the full order lifecycle (place, query, cancel, fill) without risking real funds. Demo tokens support Spot trading only — Margin and Futures testing requires real assets at minimum sizes. -
Start with public endpoints: Verify connectivity and parsing by calling read-only public endpoints (
GET /api/v4/public/time,GET /api/v4/public/markets). No authentication required. -
Verify authentication: Make an authenticated call to
POST /api/v4/trade-account/balance. If the response is401, debug the HMAC signing implementation before proceeding. -
Use minimum order sizes: Query
GET /api/v4/public/marketsto find pairs with the lowestminAmount. Place test orders at minimum sizes to verify the full order lifecycle. - Verify error handling: Send intentionally malformed requests (invalid ticker, zero amount, duplicate nonce) and verify the application handles error responses correctly.
- Test webhook delivery: Trigger a real (small) deposit at or above the network deposit minimum, or a withdrawal, and verify the webhook is received, the signature validates, and the application processes the event correctly.
-
Confirm Travel Rule compliance: For EEA accounts, submit a test crypto withdrawal with the
travelRuleobject and verify acceptance before processing customer funds. - Verify reconciliation: Confirm that the polling fallback detects events missed by webhooks. Temporarily disable webhook processing and verify that polling catches up.