Message Reference

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

Welcome

{
  "type": "welcome",
  "tier": "premium",
  "maxDistinctIps": 2,
  "maxConnectionsPerIp": 5,
  "absoluteMaxConnections": 20,
  "allowedCex": "*",
  "expiresInSecs": 2592000
}

Announcement

Sent when the detection engine captures a new event.

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

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

Publishers

Listing types

Monitoring Tag — edge cases

• Mixed Seed Tag bundles. A monitoring_tag_* event lists Monitoring Tag tickers only. Tickers in the same announcement that belong to the Seed Tag program are excluded. Seed-Tag-only announcements arrive as not_listing.
• Mixed extend + remove. When a single Binance announcement both adds and removes tickers, the dispatch emits two separate events with the same title and disjoint ticker lists.

Caution lifecycle (Bithumb / Upbit)

Korean exchanges run a multi-stage risk track on tokens already trading (pre-warning, formal designation, extension, release, delisting). We narrow the broadcast to the two stages that drive trading decisions:

• caution_released — the caution designation is lifted (유의 종목 지정 해제). Often a positive technical signal.
• spot_delisting — final removal (거래지원 종료).

The intermediate stages (유의촉구 / 거래유의·투자유의종목 지정 / 지정 연장) and risk-context deposit halts are detected but intentionally not forwarded — they generate noise without clear actionable signal on the trading side.

Composite announcements. A single title that pairs a release with a delisting (e.g. 신세틱스(SNX) 거래유의종목 지정 해제 및 (BCD, WTC) 거래지원 종료) is split into one event per (listingType, ticker-group). Multi-ticker, single-stage titles (e.g. (BCD, WTC) 거래지원 종료) are joined comma-separated like listings.

Example: caution_released

{
  "type": "announcement",
  "title": "신세틱스(SNX) 거래유의종목 지정 해제",
  "ticker": "SNX",
  "publisher": "bithumb",
  "listingType": "caution_released",
  "detectedTimestampUs": 1745971200834000,
  "dispatchTimestampUs": 1745971200842117,
  "abnormalDetectionLatency": false
}

Example: spot_delisting

{
  "type": "announcement",
  "title": "고트세우스 막시무스(GOAT) 거래지원 종료",
  "ticker": "GOAT",
  "publisher": "bithumb",
  "listingType": "spot_delisting",
  "detectedTimestampUs": 1745971200834000,
  "dispatchTimestampUs": 1745971200842117,
  "abnormalDetectionLatency": false
}

Tier behavior

Tier is returned in welcome.tier. Pricing details on the pricing page.

The free tier is default-deny: any new event type is automatically redacted on free without a schema migration. Free clients must accept ticker = "" and the upgrade-notice title gracefully.

Test announcements always carry the full payload regardless of tier.

Measuring latency

All timestamps are microseconds since Unix epoch.

Dispatch delay  = dispatchTimestampUs − detectedTimestampUs
Network delay   = your_receive_us − dispatchTimestampUs
Total           = your_receive_us − detectedTimestampUs

import time

def on_announcement(msg):
    now_us = int(time.time() * 1_000_000)
    dispatch_ms = (msg["dispatchTimestampUs"] - msg["detectedTimestampUs"]) / 1000
    network_ms  = (now_us - msg["dispatchTimestampUs"]) / 1000
    total_ms    = (now_us - msg["detectedTimestampUs"]) / 1000
    print(f"dispatch={dispatch_ms:.2f}ms network={network_ms:.2f}ms total={total_ms:.2f}ms")

Test Announcement

Send {"type":"test"}. The server replies with a fake announcement, identical in shape to a real one but with type = "test_announcement" and ticker = "DUMMYTOKEN".

{
  "type": "test_announcement",
  "title": "Binance Will List DUMMYTOKEN (DUMMYTOKEN)",
  "ticker": "DUMMYTOKEN",
  "publisher": "binance",
  "listingType": "spot_listing",
  "detectedTimestampUs": 1743850001999800,
  "dispatchTimestampUs": 1743850002000000,
  "abnormalDetectionLatency": false
}

• Sent only to the requester, not broadcast.
• Always full payload, including on free.
• Rate limit: 1 per minute per API key, shared across connections.

On excess, the server returns an error instead:

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

Heartbeat

Sent every 30 s to every subscriber, every tier.

{
  "type": "heartbeat",
  "timestampNs": 1710345030123456789,
  "timeUtc": "2026-04-17T08:30:30.123456Z"
}

Keep-alive (PING/PONG)

Separate from the application-level heartbeat, the server sends a WebSocket PING control frame (opcode 0x9, empty payload) every 15 s (0–5 s jitter on the first). Your library responds with PONG automatically. If no PONG arrives within 30 s of the last ping, the server closes the TCP connection.