Binance API Integration in a Mobile Crypto App
The -1021 error during signing is a typical headache when integrating Binance API into a mobile app. The client complains that orders do not go through, and the logs show Timestamp for this request is outside of the recvWindow.
Our experience shows: the problem is most often time desynchronization on budget Android devices. We solve this with synchronization against /api/v3/time and a custom signature manager, which guarantees stable operation even under aggressive polling.
REST + WebSocket are not interchangeable.
Binance provides both transports, and most integration errors arise precisely because a team tries to subscribe to market data via REST instead of WebSocket Streams, or vice versa — tries to place an order via wss://stream.binance.com:9443. Let's examine both scenarios honestly.
Why REST and WebSocket Cannot Be Used Interchangeably?
REST API is rate-limited — each endpoint has a weight. For example, /api/v3/depth?limit=1000 costs 50 units, while the per-minute limit is 6000. A mobile app polling order books for 5 pairs gets banned in 30 seconds.
WebSocket Streams have no such limits: a subscription to btcusdt@depth1000 provides a continuous data stream without restrictions.
Comparison of transports:
| Characteristic | REST API | WebSocket Streams |
|---|---|---|
| Request type | Request-response | Continuous stream |
| Authentication | HMAC-SHA256 | ListenKey (private streams) |
| Latency | ~100-500 ms | ~1-10 ms |
| Load | Weight limits (6000/min) | Unlimited |
| Typical use | Orders, balance, history | Market data, trades |
REST API: Limits, Signing, and Typical Mobile Crashes
Binance REST API version 3 (/api/v3/) uses HMAC-SHA256 to sign private endpoints. The signature is formed from the string queryString + body, 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 broken signature, but because the system clock on an Android device has drifted from server time by 2–3 seconds. On iOS this is rare; on budget Android devices it is the norm.
The right solution: do not hardcode recvWindow=5000, but synchronize local time with /api/v3/time on every cold start of the app and store serverTimeOffset in memory.
The limits are weight-based, not request-based. Each endpoint has a weight — /api/v3/depth?limit=1000 costs 50 units, whereas /api/v3/ticker/price costs 1. The per-minute limit is 6000 units.
A mobile app with aggressive polling of order books for 5 pairs gets banned (HTTP 429) in 30 seconds. A WeightBudget manager is needed: a priority request queue, debounce for manual refresh, and an instant switch to WebSocket when exceeding 80% of the quota.
WebSocket Streams: Connection Lifecycle on Mobile
wss://stream.binance.com:9443/ws/<streamName> is a separate host, with no authorization for public streams.
For private ones (orders, balance), a listenKey is needed, which is obtained via POST /api/v3/userDataStream and renewed every 30 minutes via PUT /api/v3/userDataStream.
The mobile problem: background mode. On iOS, when the app goes to the background, the socket closes with code 1001 (going away). When returning to the foreground, you need to:
- Check whether the
listenKeyhas expired (TTL — 60 minutes from the lastPUT). - If it has expired — get a new one and resubscribe.
- Restore all public streams again.
On Android the situation is different: aggressive Doze Mode drops the TCP socket before WebSocket can send a ping. The OkHttp library with pingInterval(20, TimeUnit.SECONDS) handles it, but only if the WakeLock is held at the WorkManager level.
For Flutter we use web_socket_channel with a custom ReconnectingWebSocketChannel — a wrapper with exponential backoff (starting at 1 s, maximum 30 s) and a log of missed events for reconciliation on reconnect.
How to Properly Sign Orders on a Mobile Device?
A critical detail: parameters in the query string and in the body are counted together. If POST /api/v3/order is sent with the body symbol=BTCUSDT&side=BUY&...×tamp=..., then the signature is formed from this entire string as a whole — without the ? sign.
A typical mistake is to sign only the body or only the query, get {"code":-1022,"msg":"Signature for this request is not valid."}, and look for a bug in the hashing algorithm.
Binance API docs: "The signature is case-sensitive and must be HMAC-SHA256 encoded."
Another nuance: parameter order matters only for the signature, but not for execution — Binance accepts them in any order, but HMAC is sensitive to concatenation order.
How We Build the Integration: Architecture and a Proven Stack
Our experience includes 5+ years of working with mobile crypto applications. We have completed integrations for 20+ projects, reducing signature debugging time by 30% with a custom interceptor.
Architecture: Clean Architecture with a separate BinanceDataSource (network layer), TradeRepository (business logic), and a ViewModel layer for UI.
For REST: Retrofit 2 + OkHttpClient with a signature interceptor and a time synchronization interceptor. We intercept 429 and 418 (IP ban) — on 418, we show the user a countdown until unban (the Retry-After header).
For WebSocket: a separate BinanceStreamManager — a Singleton in the DI container (Hilt), manages a pool of streams, deduplicates 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 to verify the signature without the network.
What Is Included in the Integration
- Architectural documentation and data flow diagram
- Source code with comments and signing examples
- Access to the test environment (Testnet)
- Team training on maintenance and troubleshooting
- Guarantee of stable operation for 3 months
Estimate and Timelines
Basic integration (market data + one trading type) — from 2 to 4 weeks. A 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; contact us for a consultation on your project.
To clarify the details, get a consultation — we will help you choose the optimal stack and avoid typical mistakes.