WebSocket

📘 General Overview

WebSocket is a modern HTML5 protocol that supports full-duplex communication between the client and the server. Unlike traditional polling or HTTP requests, WebSocket only requires a single handshake to establish a persistent connection, enabling efficient real-time data transfer.

✅ Advantages

• Extremely lightweight headers (~2 bytes)

• Bi-directional communication: server and client can both initiate messages

• No repeated TCP connections—saves server resources and bandwidth

• Highly recommended for real-time market data and order book depth

🌐 Connection Info

• WebSocket URL: wss://ws.coinlocally.com/kline-api/ws

• Compression: Binary data is compressed using Gzip — clients must decompress accordingly.

🫀 Heartbeat (Ping/Pong)

To maintain connection stability:

• The server sends a ping message every 10 seconds.

• The client should immediately respond with a pong message.

• The server does not enforce one-to-one verification, but may close the connection if no pong is received.

Ping Message (Server → Client)

jsonCopyEdit{ "ping": 1694416595 }

Pong Message (Client → Server)

jsonCopyEdit{ "pong": 1694416595 }

---

📡 Command Format

🔄 Subscribe & Unsubscribe

Command	Channel	Description
sub	market_$symbol_depth_step0	Subscribe to order book depth
unsub	market_$symbol_depth_step0	Unsubscribe from order book depth
sub	market_$symbol_trade_ticker	Subscribe to real-time trades
unsub	market_$symbol_trade_ticker	Unsubscribe from real-time trades
sub	market_$symbol_ticker	Subscribe to 24h market ticker
unsub	market_$symbol_ticker	Unsubscribe from 24h market ticker
sub	market_$symbol_kline_1min	Subscribe to 1-minute kline
req	market_$symbol_kline_1month	Request 1-month historical kline

---

📥 Subscription Examples

📊 Depth (Order Book)

Subscribe Message

jsonCopyEdit{
  "event": "sub",
  "params": {
    "channel": "market_btcusdt_depth_step0",
    "cb_id": "1"
  }
}

Response Payload

jsonCopyEdit{
  "channel": "market_btcusdt_depth_step0",
  "ts": 1506584998239,
  "tick": {
    "asks": [[10000.19, 0.93], [10001.21, 0.2]],
    "buys": [[9999.53, 0.93], [9998.2, 0.2]]
  }
}

---

📈 Real-Time Trade

Subscribe Message

jsonCopyEdit{
  "event": "sub",
  "params": {
    "channel": "market_btcusdt_trade_ticker",
    "cb_id": "1"
  }
}

Response Payload

jsonCopyEdit{
  "channel": "market_btcusdt_trade_ticker",
  "ts": 1506584998239,
  "tick": {
    "data": [
      {
        "side": "buy",
        "price": 32.233,
        "vol": 232,
        "amount": 323,
        "ds": "2017-09-10 23:12:21"
      }
    ]
  }
}

---

📉 Kline (Candlestick Data)

Subscribe Message

jsonCopyEdit{
  "event": "sub",
  "params": {
    "channel": "market_btcusdt_kline_1min",
    "cb_id": "1"
  }
}

Response Payload

jsonCopyEdit{
  "channel": "market_btcusdt_kline_1min",
  "ts": 1506584998239,
  "tick": {
    "id": 1506602880,
    "vol": 1212.12211,
    "open": 2233.22,
    "close": 1221.11,
    "high": 22322.22,
    "low": 2321.22
  }
}

📊 Market Ticker (24h)

Subscribe Message

jsonCopyEdit{
  "event": "sub",
  "params": {
    "channel": "market_btcusdt_ticker",
    "cb_id": "1"
  }
}

Response Payload

jsonCopyEdit{
  "channel": "market_btcusdt_ticker",
  "ts": 1506584998239,
  "tick": {
    "amount": 123.1221,
    "vol": 1212.12211,
    "open": 2233.22,
    "close": 1221.11,
    "high": 22322.22,
    "low": 2321.22,
    "rose": -0.2922
  }
}

---

📤 Request Historical Data

🕰 Historical Kline

Request Message

jsonCopyEdit{
  "event": "req",
  "params": {
    "channel": "market_btcusdt_kline_1month",
    "cb_id": "1",
    "endIdx": "1506602880",
    "pageSize": 100
  }
}

Response Payload

jsonCopyEdit{
  "event_rep": "rep",
  "channel": "market_btcusdt_kline_5min",
  "ts": 1506584998239,
  "data": [
    {
      "id": 1506602880,
      "amount": 123.1221,
      "vol": 1212.12211,
      "open": 2233.22,
      "close": 1221.11,
      "high": 22322.22,
      "low": 2321.22
    }
  ]
}

---

🧾 Historical Trades

Request Message

jsonCopyEdit{
  "event": "req",
  "params": {
    "channel": "market_btcusdt_trade_ticker",
    "cb_id": "1"
  }
}

Response Payload

jsonCopyEdit{
  "event_rep": "rep",
  "channel": "market_btcusdt_trade_ticker",
  "ts": 1506584998239,
  "status": "ok",
  "data": [
    {
      "side": "buy",
      "price": 32.233,
      "vol": 232,
      "amount": 323
    }
  ]
}