# Websocket API

### Connection endpoint

```
wss://cryptolisting.ws
```

The server uses **binary WebSocket frames** containing UTF-8 JSON.

### Query parameters

| Parameter | Required | Description                                       | Example         |
| --------- | -------- | ------------------------------------------------- | --------------- |
| `cex`     | No       | Comma-separated list of exchanges to subscribe to | `binance,upbit` |

### Connection lifecycle

```
Client                              Server
  |                                    |
  |--- WSS handshake + API key ------→ |
  |                                    |-- Validate key
  |                                    |-- Check rate limits
  |                                    |-- Check connection limits
  |←---- 101 Switching Protocols ------|
  |                                    |
  |←---- Welcome message --------------|  (immediate)
  |                                    |
  |←---- Heartbeat --------------------|  (every 30s)
  |←---- Heartbeat --------------------|
  |                                    |
  |←---- Announcement -----------------|  (when detected)
  |                                    |
  |←---- PING ------------------------ |  (every 15s)
  |--- PONG -------------------------→ |
  |                                    |
  |←---- Close (1000, key_expired) ----|  (if key expires)
  |                                    |
```

#### 1. Handshake

The server validates your API key during the HTTP upgrade handshake. If validation fails, you receive an HTTP error response (not a WebSocket frame):

| HTTP Code | Reason                                  |
| --------- | --------------------------------------- |
| `400`     | Malformed WebSocket upgrade request     |
| `401`     | Missing API key                         |
| `403`     | Invalid, revoked, or expired API key    |
| `429`     | Rate limit or connection limit exceeded |

#### 2. Welcome message

Immediately after a successful handshake, the server sends a `welcome` message confirming your subscription parameters. See Message Reference.

#### 3. Heartbeats

The server sends a JSON heartbeat message every **30 seconds**. If you do not receive a heartbeat within \~35 seconds, your connection may be dead.

#### 4. Ping/Pong

In addition to JSON heartbeats, the server sends WebSocket **PING frames** every **15 seconds**. Your WebSocket library handles PONG responses automatically. If the server receives no PONG within 30 seconds, it closes your connection.

{% hint style="info" %}
Most WebSocket libraries (Python `websockets`, Node.js `ws`, Go `gorilla/websocket`) handle PING/PONG automatically. You do not need to implement this yourself.
{% endhint %}

#### 5. Announcements

When a listing or other exchange announcement is detected, the server sends an `announcement` message to all subscribers whose exchange filter matches. See Message Reference.

#### 6. Disconnection

The server may close your connection with a WebSocket close frame. The close code and reason indicate why. See Error Handling.

### Client-to-server messages

The server does **not** expect any messages from clients. Client-sent messages are silently ignored, but are subject to rate limiting (30 messages/minute) and frame size limits (1 KB max).

{% hint style="warning" %}
Do not send messages to the server. Exceeding the client message rate limit (30/min) will result in disconnection.
{% endhint %}