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.

Most WebSocket libraries (Python websockets, Node.js ws, Go gorilla/websocket) handle PING/PONG automatically. You do not need to implement this yourself.

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

Do not send messages to the server. Exceeding the client message rate limit (30/min) will result in disconnection.