Binance API Integration for Mobile Crypto Apps

Мы интегрируем Binance API в мобильные крипто-приложения, обеспечивая стабильную работу на iOS и Android. Error -1021 during signing is a typical headache when integrating Binance API into a mobile app. Your client complains that orders don't go through, and logs show Timestamp for this request is outside of the recvWindow. Our experience indicates the problem often stems from time desynchronization on budget Android devices. We solve this by syncing with /api/v3/time and implementing a custom signature manager, ensuring stable operation even under aggressive polling.

REST and WebSocket are not interchangeable. Binance provides both transports (Binance API Documentation), and most integration errors arise when a team tries to subscribe to market data via REST instead of WebSocket Streams, or conversely attempts to place an order through wss://stream.binance.com:9443. Let's examine both scenarios honestly.

Why REST and WebSocket Are Not Interchangeable

REST API has frequency limits — each endpoint carries a weight. For example, /api/v3/depth?limit=1000 costs 50 units, and the minute limit is 6000. A mobile app polling order books for 5 pairs hits the ban in 30 seconds. WebSocket Streams have no such limits: subscribing to btcusdt@depth1000 yields a constant data stream without restrictions.

«REST в 10–50 раз медленнее WebSocket» — это не преувеличение: разница в задержках составляет от 100 до 500 мс против 1–10 мс.

REST API: Limits, Signatures, and Common Mobile Crashes

Binance REST API v3 (/api/v3/) uses HMAC-SHA256 to sign private endpoints. The signature is formed from the queryString + body string, to which timestamp and an optional recvWindow are added. A typical error — {"code":-1021,"msg":"Timestamp for this request is outside of the recvWindow."} — occurs not because of a flawed signature, but because the system clock on an Android device drifts 2–3 seconds from server time. On iOS this is rare; on budget Android devices it's the norm.

The correct approach: do not hardcode recvWindow=5000. Instead, sync local time with /api/v3/time on every cold start and store serverTimeOffset in memory.

Weight limits are per-weight, not per-request. Each endpoint has a weight — /api/v3/depth?limit=1000 costs 50 units, while /api/v3/ticker/price costs 1. The minute limit is 6000 units. A mobile app with aggressive polling of order books for 5 pairs gets banned (HTTP 429) in 30 seconds. You need a WeightBudget manager: a request queue with priorities, debounce on manual updates, and instant fallback to WebSocket when 80% of the quota is exceeded.

WebSocket Streams: Connection Lifecycle on Mobile

wss://stream.binance.com:9443/ws/<streamName> is a separate host, with no authentication for public streams. For private streams (orders, balance), you need a listenKey, obtained via POST /api/v3/userDataStream and renewed every 30 minutes via PUT /api/v3/userDataStream.

The mobile challenge: background mode. On iOS, when the app goes to the background, the socket closes with code 1001 (going away). On return to foreground, you must:

1. Check if the listenKey has expired (TTL is 60 minutes since the last PUT).
2. If expired, get a new one and resubscribe.
3. Reconnect all public streams from scratch.

On Android, the situation differs: aggressive Doze Mode tears down the TCP socket before WebSocket can send a ping. The OkHttp library with pingInterval(20, TimeUnit.SECONDS) works, but only if a WakeLock is held at the WorkManager level.

For Flutter, we use web_socket_channel with a custom ReconnectingWebSocketChannel — a wrapper with exponential backoff (start 1 s, max 30 s) and a log of missed events for reconciliation during reconnection.

Как правильно подписывать ордера на мобильных устройствах

A critical detail: parameters in the query string and in the body are combined. If you POST to /api/v3/order with body symbol=BTCUSDT&side=BUY&...&timestamp=..., the signature is formed from the entire string — without the ? sign. A common mistake is signing only the body or only the query, receiving {"code":-1022,"msg":"Signature for this request is not valid."} and hunting for a bug in the hashing algorithm.

Binance API docs (Binance REST API): "The signature is case-sensitive and must be HMAC-SHA256 encoded."

Another nuance: parameter order matters only for the signature, not for execution — Binance accepts them in any order, but HMAC is sensitive to concatenation order.

Here's an example of signature generation in Kotlin for Android:

import javax.crypto.Mac import javax.crypto.spec.SecretKeySpec fun sign(queryString: String, secretKey: String): String { val mac = Mac.getInstance("HmacSHA256") val keySpec = SecretKeySpec(secretKey.toByteArray(), "HmacSHA256") mac.init(keySpec) val rawHmac = mac.doFinal(queryString.toByteArray()) return rawHmac.joinToString("") { "%02x".format(it) } } 

Наша архитектура интеграции: проверенный стек

Our experience includes 5+ years working with mobile crypto apps. We have completed integrations for 20+ projects, cutting signature debugging time by 30% using a custom interceptor. Экономия на отладке составляет до $5000 за проект.

Architecture: Clean Architecture with a separate BinanceDataSource (network layer), TradeRepository (business logic), and ViewModel layer.

For REST: Retrofit 2 + OkHttpClient with a signing interceptor and a time sync interceptor. We intercept 429 and 418 (IP ban) — on 418 we show the user a timer until unban (header Retry-After).

For WebSocket: a dedicated BinanceStreamManager — a Singleton in a DI container (Hilt), managing the pool of streams and deduplicating subscriptions (if two screens want btcusdt@trade — one socket, two observers via SharedFlow).

Testing: Binance Testnet (testnet.binance.vision) with a separate key. MockWebServer in unit tests for signature verification without network.

What the Integration Includes

Assessment and Timelines

Basic integration (market data + one order type) — from 2 to 4 weeks. Full trading terminal with multiple order types, order book, history, and analytics — from 6 to 12 weeks depending on the platform (native iOS/Android vs Flutter). Cost is calculated individually: базовая интеграция от $2000, полный терминал от $8000. Contact us for a consultation to pinpoint your case.

For details, get a consultation — we'll help you choose the optimal stack and avoid typical mistakes.