OKEx API Websocket: A Comprehensive Guide for Spot Trading

Introduction to OKEx WebSocket API

The OKEx WebSocket API provides real-time market data and trading capabilities for spot trading. This protocol enables bidirectional communication between clients and servers, allowing rapid data transmission with minimal overhead.

Key Advantages of WebSocket Technology

• Efficient Communication: Small header size (~2 bytes) reduces bandwidth usage
• Full Duplex: Both client and server can initiate data transmission
• Resource Optimization: Eliminates need for repeated TCP connection setup/teardown

Getting Started with Spot WebSocket API

Connection Details

Spot Trading WebSocket Endpoint:
wss://real.okex.com:10440/ws/v1

Request-Response Workflow

Sending Requests

Request format:

{
  "event": "addChannel",
  "channel": "channelValue",
  "parameters": {
    "api_key": "value1",
    "sign": "value2"
  }
}

Key parameters:

• event: "addChannel" (subscribe) or "removeChannel" (unsubscribe)
• channel: OKEx-provided data channel
• parameters: Optional authentication fields

Example subscription:

websocket.send('{"event":"addChannel","channel":"ok_sub_spot_bch_btc_ticker"}')

👉 Discover more about WebSocket connections

Server Response Format

Standard response structure:

[
  {
    "channel": "channelName",
    "success": true/false,
    "errorcode": "",
    "data": {}
  }
]

Connection Maintenance

Heartbeat Mechanism:

• Client sends ping every 30 seconds: {"event":"ping"}
• Server responds with pong: {"event":"pong"}
• Missing responses indicate connection issues requiring reconnection

Market Data API Reference

1. Ticker Data Subscription

Endpoint: ok_sub_spot_X_ticker
(X = trading pair, e.g., ltc_btc)

Example:

{
  "event": "addChannel",
  "channel": "ok_sub_spot_bch_btc_ticker"
}

Response Fields:

2. Market Depth (200 Levels)

Endpoint: ok_sub_spot_X_depth

Response Structure:

{
  "asks": [["price", "quantity"], ...],
  "bids": [["price", "quantity"], ...],
  "timestamp": 1504529236946
}

3. Custom Market Depth

Endpoint: ok_sub_spot_X_depth_Y
(Y = depth levels: 5, 10, 20)

4. Trade History

Endpoint: ok_sub_spot_X_deals

Response Format:

[
  ["trade_id", "price", "amount", "time", "side"],
  ...
]

5. K-Line Data

Endpoint: ok_sub_spot_X_kline_Y
(Y = time frame: 1min, 5min, 1hour, etc.)

Data Format:

[
  ["timestamp", "open", "high", "low", "close", "volume"],
  ...
]

Trading API Reference

1. Login Authentication

Request:

{
  "event": "login",
  "parameters": {
    "api_key": "your_api_key",
    "sign": "generated_signature"
  }
}

👉 Learn about API security best practices

2. Order Updates

Endpoint: ok_sub_spot_X_order

Response Fields:

3. Account Balance Updates

Endpoint: ok_sub_spot_X_balance

Response Structure:

{
  "free": {
    "btc": 5814.850605790395
  },
  "freezed": {
    "btc": 7341
  }
}

FAQ Section

Q1: How often should I send heartbeat messages?

A: The recommended interval is every 30 seconds ({"event":"ping"}) to maintain connection.

Q2: What happens if my connection drops?

A: Implement reconnection logic when pong responses stop. OKEx doesn't guarantee message delivery during outages.

Q3: Can I batch subscribe to multiple channels?

A: Yes, you can send an array of subscription requests in a single message.

Q4: How are depth updates handled?

A: First response contains full snapshot; subsequent updates contain changes (add/modify/delete).

Q5: Is there rate limiting on the WebSocket API?

A: OKEx may throttle excessive messages. Maintain reasonable request rates and handle 10053 error codes appropriately.

Q6: How do I authenticate trading requests?

A: Include your API key and properly signed parameters in the login request.