> 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/spot.md).

# Spot

This document outlines how to establish and maintain a WebSocket connection for **Spot trading** via two supported authentication methods: Token and API Key.

### Token Connection

#### 1. Overview

* The client sends a WebSocket request with a `token` in the header.
* A subscription message must be sent to receive real-time data upon successful connection.

#### 2. Connection Details

* **Request Path:**

  ```
  wss://ws2.coinlocally.com/spotws_user/userData/ws
  ```

#### 3. Request Header

| Parameter Name | Type   | Required | Description                 |
| -------------- | ------ | -------- | --------------------------- |
| token          | string | Yes      | Token generated after login |

#### 4. Subscription Message Format

```json
{
  "event": "sub",
  "token": "<your_token>"
}
```

### API Key Connection

#### 1. Overview

* The client sends a WebSocket request with an `api-key` in the header.
* A subscription message must be followed to start receiving real-time messages.

#### 2. Connection Details

* **Request Path:**

  ```
  wss://ws2.coinlocally.com/spotws_user/userData/ws
  ```

#### 3. Request Header

| Parameter Name | Type   | Required | Description                       |
| -------------- | ------ | -------- | --------------------------------- |
| api-key        | string | Yes      | API key generated on the frontend |

#### 4. Subscription Message Format

```json
{
  "event": "sub",
  "token": "<your_apikey>"
}
```

### Receiving Messages

#### 1. Connection Responses

* **Connect Success:** `"connect success"`
* **Subscribe Success:** `"sub success"`

#### 2. Message Format

* Messages are compressed in binary format using GZIP.
* Decompress using your language's GZIP library.
* [Gzip Decompression Tool](https://www.bejson.com/encrypt/gzip/#google_vignette)

#### Example (Base64 Encoded, Gzipped):

```
H4sIAAAAA... (truncated)
```

#### Decompressed Message (Example):

```json
{
  "e": "outboundAccountPosition",
  "E": 1564034571105,
  "u": 1564034571073,
  "B": [
    {
      "a": "ETH",
      "f": "10000.000000",
      "l": "0.000000"
    }
  ]
}
```

***

### Event Types

#### 1. Account Update: `outboundAccountPosition`

```json
{
  "e": "outboundAccountPosition",
  "E": 1564034571105,
  "u": 1564034571073,
  "B": [
    {
      "a": "ETH",
      "f": "10000.000000",
      "l": "0.000000"
    }
  ]
}
```

#### 2. Order Status Update: `executionReport`

```json
{
  "e": "executionReport",
  "E": 1745389508472,
  "T": 1745389508418,
  "S": "SELL",
  "s": "BTCUSDT",
  "X": "PART_FILLED",
  "x": "STATUS",
  "i": "2690536306533246156",
  "l": "0.1000000000000000",
  "z": "0.17861112",
  "L": "13000.0000000000000000",
  "Z": "2321.94456",
  "n": "7.8000000000000000",
  "o": "LIMIT",
  "q": "1",
  "p": "13000",
  "Q": "0.17861112",
  "O": 1745389507000,
  "P": "0"
}
```

* **Order Status (X):**
  * `FILLED`: Fully filled
  * `PART_FILLED`: Partially filled
  * `CANCELED`: Cancelled successfully
  * `PENDING_CANCEL`: Cancellation in progress

#### 3. System Close Notification

```json
{
  "uid": 24005174,
  "channel": "SYSTEM",
  "et": "close"
}
```

### V. Heartbeat Mechanism

* **Client must send a ping every 30 seconds**:

```json
{ "ping": 1713338308232 }
```

* **Server responds with pong**:

```json
{ "pong": 1713338308233 }
```

* **The connection will be closed** if no ping is received in 40 seconds.