WebSocket API

Connection endpoint

wss://cryptolisting.ws

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

Query parameters

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)
  |                                   |
  |--- {"type":"test"} -------------→ |  (optional)
  |←---- Test Announcement -----------|  (only to you)
  |                                   |
  |←---- 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):

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.

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

Client messages are subject to rate limiting (3 messages/minute) and frame size limits (1 KB max). The only supported client message is the test request:

{"type":"test"}

This returns a fake announcement to verify your integration is working. See Message Reference — Test Announcement for details.