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
}

Field	Type	Description
type	string	Always "welcome"
tier	string	Your subscription tier: basic, premium, or enterprise
maxConnections	integer	Maximum simultaneous connections allowed with your key
allowedCex	string	Exchanges you will receive announcements from (effective filter after applying key restrictions and your cex preference). "*" means all exchanges
expiresInSecs	integer|null	Seconds until your key expires, or null if no expiration

---

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
}

Field	Type	Description
type	string	Always "announcement"
title	string	Original announcement title from the exchange
ticker	string	Asset symbol(s). Comma-separated when multiple tickers are listed in the same announcement (e.g. "BTC" or "ABC,DEF,GHI")
publisher	string	Exchange name in lowercase (e.g. "binance", "upbit")
listingType	string	One of the listing types below
publishTimestampUs	integer	When the exchange published the announcement (microseconds since UNIX epoch)
detectedTimestampUs	integer	When our detection engine captured it (microseconds since UNIX epoch)
dispatchTimestampUs	integer	When the dispatch server broadcasted it (microseconds since UNIX epoch)

Always handle ticker as a potentially comma-separated list. Some exchange announcements list multiple assets at once. Split on , to get individual tickers:

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

Listing types

Value	Meaning
spot_listing	New spot market listing
futures_listing	New futures/perpetual listing
spot_delisting	Spot market delisting (coming soon)
futures_delisting	Futures/perpetual delisting (coming soon)
not_listing	Other exchange announcement (maintenance, airdrop, token swap, etc.)

Delistings coming soon. The spot_delisting and futures_delisting types are reserved for future use. Currently, announcements that are not listings are sent with listingType: "not_listing".

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

---

Heartbeat

Sent every 30 seconds to indicate the server is alive.

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

Field	Type	Description
type	string	Always "heartbeat"
timestampNs	integer	Current server time in nanoseconds since UNIX epoch
timeUtc	string	Current server time in ISO 8601 UTC format

If you do not receive a heartbeat within 35 seconds, your connection is likely dead. Initiate a reconnection.