# 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
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coinlocally.com/websocket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.