Message Reference

All messages are delivered as binary WebSocket frames containing UTF-8 JSON. Every message has a type field.

Welcome

Sent once, immediately after a successful connection.

{
  "type": "welcome",
  "tier": "premium",
  "maxConnections": 5,
  "allowedCex": "*",
  "expiresInSecs": 2592000
}

Announcement

Sent whenever a listing or other exchange announcement is detected on a monitored exchange.

Single ticker:

{
  "type": "announcement",
  "title": "Binance Will List TOKEN (TOKEN)",
  "ticker": "TOKEN",
  "publisher": "binance",
  "listingType": "spot_listing",
  "publishTimestampUs": 1710345000000000,
  "detectedTimestampUs": 1710345000005000,
  "dispatchTimestampUs": 1710345000006000
}

Multiple tickers (one announcement listing several assets at once):

{
  "type": "announcement",
  "title": "Binance Will List ABC, DEF and GHI",
  "ticker": "ABC,DEF,GHI",
  "publisher": "binance",
  "listingType": "spot_listing",
  "publishTimestampUs": 1710345000000000,
  "detectedTimestampUs": 1710345000005000,
  "dispatchTimestampUs": 1710345000006000
}

tickers = data["ticker"].split(",")  # ["ABC", "DEF", "GHI"]

Supported exchanges (publisher)

Listing types

Measuring your latency

All timestamps are in microseconds since UNIX epoch (not milliseconds, not nanoseconds).

Detection delay    = detectedTimestampUs - publishTimestampUs
Dispatch delay     = dispatchTimestampUs - detectedTimestampUs
Your network delay = your_receive_time_us - dispatchTimestampUs
Total end-to-end   = your_receive_time_us - publishTimestampUs

Python example:

import time

def on_announcement(msg):
    now_us = int(time.time() * 1_000_000)
    detection_ms = (msg["detectedTimestampUs"] - msg["publishTimestampUs"]) / 1000
    dispatch_ms  = (msg["dispatchTimestampUs"] - msg["detectedTimestampUs"]) / 1000
    network_ms   = (now_us - msg["dispatchTimestampUs"]) / 1000
    total_ms     = (now_us - msg["publishTimestampUs"]) / 1000

    print(f"Detection: {detection_ms:.2f}ms")
    print(f"Dispatch:  {dispatch_ms:.2f}ms")
    print(f"Network:   {network_ms:.2f}ms")
    print(f"Total:     {total_ms:.2f}ms")

Test Announcement

You can request a fake announcement to verify your integration. Send a JSON message to the server:

{"type":"test"}

The server replies with a test_announcement — identical to a real announcement except for the type field:

{
  "type": "test_announcement",
  "title": "Binance Will List MOCKX (MOCKX)",
  "ticker": "MOCKX",
  "publisher": "binance",
  "listingType": "spot_listing",
  "publishTimestampUs": 1743850000000000,
  "detectedTimestampUs": 1743850001999800,
  "dispatchTimestampUs": 1743850002000000
}

The fields are the same as a regular Announcement. The timestamps are simulated: publishTimestampUs is 1 second before dispatch, and detectedTimestampUs is 200µs before dispatch.

Test rate limit

Test requests are rate-limited to 1 per minute per API key (shared across all connections using the same key). If you exceed the limit, the server responds with an error instead of a test announcement:

{
  "type": "error",
  "code": "test_rate_limited",
  "retryAfterSecs": 42
}

Heartbeat

Sent every 30 seconds to indicate the server is alive.

{
  "type": "heartbeat",
  "timestampNs": 1710345030000000000,
  "timeUtc": "2024-03-13T10:30:30.000000Z"
}