OKX API Integration in Mobile Crypto Applications
OKX is one of the few exchanges where REST and WebSocket live in separate URL spaces with different authentication logic. REST goes to https://www.okx.com/api/v5/, WebSocket—to wss://ws.okx.com:8443/ws/v5/public and /private. If your team previously worked with Binance and ports the architecture as-is, surprises will come.
Signature: Three Header Fields, Not Parameters
OKX authenticates requests via HTTP headers, not query string or body:
-
OK-ACCESS-KEY— API key -
OK-ACCESS-SIGN— Base64(HMAC-SHA256(timestamp + method + requestPath + body)) -
OK-ACCESS-TIMESTAMP— ISO 8601 (e.g.,2024-01-15T10:30:00.123Z) -
OK-ACCESS-PASSPHRASE— third secret, set during key creation
requestPath includes query string: for GET /api/v5/account/balance?ccy=BTC, sign /api/v5/account/balance?ccy=BTC. GET request body is an empty string "". The error {"code":"50113","msg":"Invalid Sign"} almost always means requestPath problem—either forgot query string or added an extra slash.
ISO 8601 timestamp with milliseconds is rare for exchanges. On Android, Instant.now().toString() gives the right format starting with API 26. For older versions, use SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US) with UTC timezone.
WebSocket Private: Session Authentication
{
"op": "login",
"args": [{
"apiKey": "...",
"passphrase": "...",
"timestamp": "1705312200",
"sign": "..."
}]
}
WebSocket signature differs from REST: HMAC-SHA256(timestamp + "GET" + "/users/self/verify"), where timestamp is Unix seconds (not milliseconds, not ISO). This difference is a frequent source of errors when refactoring shared auth modules.
OKX disconnects WebSocket sessions after 30 seconds without activity. Ping/pong is non-standard: send the string "ping", receive "pong". Not a JSON object, exactly raw string. Libraries working only with text-frame JSON break here.
Product Logic Nuances
OKX supports instType (instrument type): SPOT, MARGIN, SWAP, FUTURES, OPTION. The same ticker, e.g., BTC-USDT, exists in multiple instType with different trading rules. When implementing an order form, explicitly pass instType—otherwise the exchange returns {"code":"51001","msg":"Instrument ID does not exist"} for instruments existing in another type.
Another feature—tdMode (trade mode): cash for Spot, cross or isolated for margin. Mobile UIs often hide this choice "for simplicity," leading to accidental margin position opens. Recommend explicit UI choice with warning.
Working with Historical Data
OKX limits candles: GET /api/v5/market/candles returns max 300 records. For loading history when scrolling backward, use pagination with before parameter (candle ID). Standard error—using after instead of before and getting data in reverse order, then inverting the array in UI with visual glitch.
Stack and Approach
For React Native: axios with request interceptor for signing + reconnecting-websocket with custom pingInterval. Market state—in Redux Toolkit with RTK Query for REST and custom middleware for WebSocket events.
For Flutter: dio + web_socket_channel, BLoC for trading screen state. Separate PublicStreamBloc and PrivateStreamBloc—different lifecycles (public streams live all the time, private only during authorized session).
Testing: OKX Demo Trading (www.okx.com/demo-trading)—full environment with real order books and order placement without real funds. Significantly better than some competitors.
Timeline: basic integration (market data + spot trading)—2–4 weeks. Derivatives + margin—add another 3–4 weeks for business logic and edge case testing.