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

{
  "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

{
  "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

Example (Base64 Encoded, Gzipped):

H4sIAAAAA... (truncated)

Decompressed Message (Example):

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

---

Event Types

1. Account Update: outboundAccountPosition

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

2. Order Status Update: executionReport

{
  "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

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

V. Heartbeat Mechanism

• Client must send a ping every 30 seconds:

{ "ping": 1713338308232 }

• Server responds with pong:

{ "pong": 1713338308233 }

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