> For the complete documentation index, see [llms.txt](https://docs.coinlocally.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coinlocally.com/websocket.md).

# 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)

```json
jsonCopyEdit{ "ping": 1694416595 }
```

#### Pong Message (Client → Server)

```json
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**

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

**Response Payload**

```json
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**

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

**Response Payload**

```json
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**

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

**Response Payload**

```json
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**

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

**Response Payload**

```json
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**

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

**Response Payload**

```json
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**

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

**Response Payload**

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