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


---

# 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/spot.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.