Introduction

Real-time WebSocket feed for crypto exchange listing announcements. Connect over WSS, receive structured JSON the moment a listing, delisting, or risk event is detected.

For LLMs, full documentation in a single txt file here.

Supported exchanges

Announcement types

See Message Reference for full payload schemas.

Features

• Microsecond timestamps at every stage (detect, dispatch).
• Pre-parsed ticker and listingType on every message; original title kept for cross-checking.
• Per-exchange filtering via ?cex=.
• WebSocket PING every 15 s; libraries handle PONG automatically.

Next steps

Quick Start

Connect, authenticate, and receive announcements in five minutes.

1. Get an API key

Request a key on Telegram. Format: dsk_ + 64 hex characters.

dsk_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890ab

2. Connect

Pick one endpoint per bot — the closest to your trading region. Same key works on both.

Pass the key as the X-API-Key header:

pip install websocket-client

import json, websocket

URL    = "wss://cryptolisting.ws"
HEADER = ["X-API-Key: dsk_your_key_here"]

def on_message(ws, message):
    data = json.loads(message)
    if data["type"] == "announcement":
        print(f"{data['listingType']} | {data['ticker']} | {data['publisher']}")
        print(f"  {data['title']}")

websocket.WebSocketApp(URL, header=HEADER, on_message=on_message).run_forever()

npm install ws

const WebSocket = require("ws");

const ws = new WebSocket("wss://cryptolisting.ws", {
  headers: { "X-API-Key": "dsk_your_key_here" },
});

ws.on("message", (raw) => {
  const data = JSON.parse(raw);
  if (data.type === "announcement") {
    console.log(`${data.listingType} | ${data.ticker} | ${data.publisher}`);
    console.log(`  ${data.title}`);
  }
});

3. Receive messages

On connect, the server sends a welcome message with your tier and limits. Then a stream of announcement and heartbeat (every 30 s) messages.

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

4. Filter by exchange (optional)

Add the cex query parameter to scope the stream:

wss://cryptolisting.ws?cex=binance
wss://cryptolisting.ws?cex=binance,upbit

Omit it to receive every supported exchange.

Next

• Message Reference — every field, every event type
• Error Handling — close codes and reconnection
• Code Examples — production-ready clients

Authentication

Every connection requires an API key in the X-API-Key header.

Key format

dsk_<64 hex characters>

• Prefix: dsk_
• Body: 64 hex characters (32 random bytes)

Passing the key

Set X-API-Key on the WebSocket upgrade request:

X-API-Key: dsk_your_key_here

Query-parameter authentication (?api_key=…) is not supported and the handshake returns 401. This keeps keys out of URLs, browser history, and proxy logs.

Key properties

Set by the administrator at creation:

Per-IP and absolute connection caps are fixed (5 / 20). See Rate Limits.

Lifecycle

Security

• All connections use TLS (WSS).
• Treat the key like a password. Lost or leaked? Contact the administrator to rotate it.

WebSocket API

Two endpoints share the same API-key namespace.

Endpoints

Pick one per bot — the closest to your trading region. The Seoul endpoint removes the Seoul → Tokyo network hop on Upbit detection. Bithumb is dispatched only from Tokyo. Same key authenticates on both, but rate limits and connection caps are tracked independently.

Frames are binary; payloads are UTF-8 JSON.

Query parameters

See Exchange Filtering.

Lifecycle

Client                              Server
  |                                   |
  |--- WSS handshake + API key -----→ |
  |←---- 101 Switching Protocols -----|
  |                                   |
  |←---- welcome --------------------|  (immediate)
  |←---- PING (control frame) -------|  (every 15 s)
  |--- PONG ------------------------→ |  (handled by your WS lib)
  |←---- heartbeat (JSON) -----------|  (every 30 s)
  |←---- announcement ---------------|  (when detected)
  |--- {"type":"test"} -------------→ |  (optional)
  |←---- test_announcement ---------|  (only to you)
  |←---- close (1000, key_expired) -|  (if key expires)

Handshake

If the key fails validation, the server rejects the upgrade with an HTTP error:

See Error Handling for retry strategy.

Welcome

Sent once after a successful handshake. Confirms tier and limits. See welcome.

Keep-alive

The server sends a WebSocket PING control frame every 15 s (with 0–5 s jitter on the first). Your library responds with PONG automatically — Python websockets, Node.js ws, Go gorilla/websocket, Rust tokio-tungstenite all handle it without configuration.

If the server does not receive a PONG within 30 s of the last ping, it closes the connection.

Heartbeat

A JSON heartbeat message every 30 s, every tier. Lets your client confirm the connection is alive without waiting for a rare announcement. See heartbeat.

Announcements

When an event is detected, every subscriber whose filter matches receives an announcement. See announcement.

Disconnection

The server may close the connection with a close frame. The reason field tells you why — see Error Handling.

Client-to-server messages

The only supported client message is the test request:

{"type":"test"}

Returns a fake test_announcement. Limits:

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.

Exchange Filtering

Two filter layers narrow the stream you receive. The effective scope is their intersection.

1. Key restriction

Set by the administrator at key creation. Your effective allow-list appears in the welcome message:

{ "type": "welcome", "allowedCex": "binance,upbit", ... }

"*" means all exchanges.

2. ?cex= query parameter

Pass on the WebSocket URL:

Effective filter

Filtering by event type

?cex= narrows by exchange. To narrow by event class, branch on listingType in your handler:

def on_message(ws, raw):
    msg = json.loads(raw)
    if msg["type"] != "announcement":
        return

    lt = msg["listingType"]

    if lt == "spot_listing":
        snipe(msg["publisher"], msg["ticker"])

    elif lt in ("spot_delisting", "futures_delisting"):
        unwind(msg["publisher"], msg["ticker"])

    elif lt in ("monitoring_tag_extend", "monitoring_tag_remove", "caution_released"):
        log_risk_signal(msg["publisher"], msg["ticker"], lt)

The schema is identical across exchanges, so a single match / switch / if-elif chain covers every type. See Listing types for the full list.

Rate Limits & Security

Connection limits

Per IP (any key)

Per API key

Distinct IPs is set by the administrator at key creation.

429 error codes (handshake)

The server returns HTTP 429 with a JSON body whose error field tells you which limit you tripped:

Client message limits

The test rate is shared across all connections sharing a key. Excess returns an error message, not a disconnect — see Test Announcement.

Security

• All connections use TLS (WSS).
• Keys can be revoked instantly. Active sessions close with 1000 key_invalidated.
• Keys with an expiration date are rejected after expiry. Active sessions close with 1000 key_expired.

Error Handling & Reconnection

Handshake errors

Close codes

Reconnection strategy

Exponential backoff, capped at 5 minutes:

attempt 1 → 1 s
attempt 2 → 2 s
attempt 3 → 4 s
attempt 4 → 8 s
…           cap at 300 s

Reset the counter after a successful connection.

Decision logic:

Detecting dead connections

The server sends a WebSocket PING every 15 s and closes the connection if no PONG arrives within 30 s. Your library handles PONG automatically and surfaces the disconnect as a close event.

import asyncio, json, websockets

async def stream(ws):
    try:
        async for raw in ws:
            data = json.loads(raw)
            if data["type"] == "announcement":
                handle(data)
    except websockets.ConnectionClosed as e:
        print(f"closed code={e.code} reason={e.reason!r}")

Code Examples

Production-ready clients with reconnection, latency tracking, and a test-announcement smoke check on connect.

Keep-alive (PING/PONG) is handled by each WebSocket library — no application-level watchdog needed.

pip install websockets

import asyncio
import json
import time
import websockets

API_KEY = "dsk_your_key_here"
WS_URL  = "wss://cryptolisting.ws"
# Filter exchanges (optional):
# WS_URL = "wss://cryptolisting.ws?cex=binance,upbit"

MAX_RETRIES = 20


def on_announcement(msg: dict):
    now_us = int(time.time() * 1_000_000)
    network_ms = (now_us - msg["dispatchTimestampUs"]) / 1000
    print(f"[{msg['listingType']}] {msg['ticker']} on {msg['publisher']}")
    print(f"  {msg['title']}")
    print(f"  network={network_ms:.2f}ms")


async def run():
    headers = {"X-API-Key": API_KEY}

    for attempt in range(MAX_RETRIES):
        try:
            async with websockets.connect(WS_URL, extra_headers=headers) as ws:
                print("connected")

                async for raw in ws:
                    msg = json.loads(raw)

                    if msg["type"] == "welcome":
                        print(f"welcome: tier={msg['tier']} cex={msg['allowedCex']}")
                        await asyncio.sleep(15)
                        await ws.send(json.dumps({"type": "test"}))

                    elif msg["type"] in ("announcement", "test_announcement"):
                        if msg["type"] == "test_announcement":
                            print("[TEST] ", end="")
                        on_announcement(msg)

        except websockets.ConnectionClosed as e:
            reason = e.rcvd.reason if e.rcvd else ""
            if reason in ("key_expired", "key_invalidated"):
                print(f"key invalid: {reason}"); return
            print(f"closed: {reason}")

        except Exception as e:
            print(f"error: {e}")

        backoff = min(2 ** attempt, 300)
        print(f"reconnecting in {backoff}s")
        await asyncio.sleep(backoff)


if __name__ == "__main__":
    asyncio.run(run())

npm install ws

const WebSocket = require("ws");

const API_KEY = "dsk_your_key_here";
const WS_URL = "wss://cryptolisting.ws";
// Filter exchanges (optional):
// const WS_URL = "wss://cryptolisting.ws?cex=binance,upbit";

const MAX_RETRIES = 20;

function onAnnouncement(msg) {
  const nowUs = Date.now() * 1000;
  const networkMs = (nowUs - msg.dispatchTimestampUs) / 1000;
  console.log(`[${msg.listingType}] ${msg.ticker} on ${msg.publisher}`);
  console.log(`  ${msg.title}`);
  console.log(`  network=${networkMs.toFixed(2)}ms`);
}

function connect(attempt = 0) {
  if (attempt >= MAX_RETRIES) return console.log("max retries");

  const ws = new WebSocket(WS_URL, { headers: { "X-API-Key": API_KEY } });

  ws.on("open", () => console.log("connected"));

  ws.on("message", (data) => {
    const msg = JSON.parse(data);

    if (msg.type === "welcome") {
      console.log(`welcome: tier=${msg.tier} cex=${msg.allowedCex}`);
      setTimeout(() => ws.send(JSON.stringify({ type: "test" })), 15_000);
    } else if (msg.type === "announcement" || msg.type === "test_announcement") {
      if (msg.type === "test_announcement") process.stdout.write("[TEST] ");
      onAnnouncement(msg);
    }
  });

  ws.on("close", (code, reason) => {
    const r = reason.toString();
    if (r === "key_expired" || r === "key_invalidated") {
      return console.log(`key invalid: ${r}`);
    }
    const backoff = Math.min(2 ** attempt, 300);
    console.log(`closed (${code}); reconnecting in ${backoff}s`);
    setTimeout(() => connect(attempt + 1), backoff * 1000);
  });

  ws.on("error", (err) => console.error("error:", err.message));
}

connect();

go get github.com/gorilla/websocket

package main

import (
	"encoding/json"
	"log"
	"math"
	"net/http"
	"time"

	"github.com/gorilla/websocket"
)

const (
	apiKey     = "dsk_your_key_here"
	wsURL      = "wss://cryptolisting.ws"
	maxRetries = 20
)

type Msg struct {
	Type                     string `json:"type"`
	Title                    string `json:"title,omitempty"`
	Ticker                   string `json:"ticker,omitempty"`
	Publisher                string `json:"publisher,omitempty"`
	ListingType              string `json:"listingType,omitempty"`
	DetectedTimestampUs      uint64 `json:"detectedTimestampUs,omitempty"`
	DispatchTimestampUs      uint64 `json:"dispatchTimestampUs,omitempty"`
	AbnormalDetectionLatency bool   `json:"abnormalDetectionLatency,omitempty"`
	Tier                     string `json:"tier,omitempty"`
	AllowedCex               string `json:"allowedCex,omitempty"`
}

func onAnnouncement(m Msg) {
	nowUs := uint64(time.Now().UnixMicro())
	networkMs := float64(nowUs-m.DispatchTimestampUs) / 1000
	log.Printf("[%s] %s on %s | %s | network=%.2fms",
		m.ListingType, m.Ticker, m.Publisher, m.Title, networkMs)
}

func main() {
	headers := http.Header{"X-API-Key": {apiKey}}

	for attempt := 0; attempt < maxRetries; attempt++ {
		conn, resp, err := websocket.DefaultDialer.Dial(wsURL, headers)
		if err != nil {
			if resp != nil && resp.StatusCode == 403 {
				log.Println("key invalid"); return
			}
			log.Printf("dial: %v", err)
			backoff := time.Duration(math.Min(math.Pow(2, float64(attempt)), 300)) * time.Second
			log.Printf("reconnect in %s", backoff)
			time.Sleep(backoff)
			continue
		}

		log.Println("connected")
		attempt = 0

		stop := false
		for {
			_, raw, err := conn.ReadMessage()
			if err != nil {
				if ce, ok := err.(*websocket.CloseError); ok {
					if ce.Text == "key_expired" || ce.Text == "key_invalidated" {
						log.Printf("key invalid: %s", ce.Text); stop = true
					} else {
						log.Printf("closed: %s", ce.Text)
					}
				} else {
					log.Printf("read: %v", err)
				}
				break
			}

			var m Msg
			json.Unmarshal(raw, &m)

			switch m.Type {
			case "welcome":
				log.Printf("welcome: tier=%s cex=%s", m.Tier, m.AllowedCex)
				time.Sleep(15 * time.Second)
				conn.WriteMessage(websocket.TextMessage, []byte(`{"type":"test"}`))
			case "announcement", "test_announcement":
				onAnnouncement(m)
			}
		}
		conn.Close()
		if stop { return }

		backoff := time.Duration(math.Min(math.Pow(2, float64(attempt)), 300)) * time.Second
		log.Printf("reconnect in %s", backoff)
		time.Sleep(backoff)
	}
}

[dependencies]
tokio = { version = "1", features = ["full"] }
tokio-tungstenite = { version = "0.21", features = ["native-tls"] }
futures-util = "0.3"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
http = "1"

use futures_util::StreamExt;
use serde::Deserialize;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use tokio_tungstenite::connect_async;
use tokio_tungstenite::tungstenite::protocol::CloseFrame;
use tokio_tungstenite::tungstenite::Message as Ws;

const API_KEY: &str = "dsk_your_key_here";
const WS_URL:  &str = "wss://cryptolisting.ws";
const MAX_RETRIES: u32 = 20;

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct Msg {
    #[serde(rename = "type")] msg_type: String,
    #[serde(default)] title: String,
    #[serde(default)] ticker: String,
    #[serde(default)] publisher: String,
    #[serde(default)] listing_type: String,
    #[serde(default)] dispatch_timestamp_us: u64,
    #[serde(default)] tier: String,
    #[serde(default)] allowed_cex: String,
}

fn on_announcement(m: &Msg) {
    let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_micros() as u64;
    let network_ms = (now - m.dispatch_timestamp_us) as f64 / 1000.0;
    println!("[{}] {} on {} | {} | network={:.2}ms",
        m.listing_type, m.ticker, m.publisher, m.title, network_ms);
}

#[tokio::main]
async fn main() {
    for attempt in 0..MAX_RETRIES {
        let req = http::Request::builder()
            .uri(WS_URL)
            .header("X-API-Key", API_KEY)
            .header("Connection", "Upgrade")
            .header("Upgrade", "websocket")
            .header("Sec-WebSocket-Version", "13")
            .header("Sec-WebSocket-Key",
                tokio_tungstenite::tungstenite::handshake::client::generate_key())
            .body(()).unwrap();

        let ws = match connect_async(req).await {
            Ok((ws, _)) => ws,
            Err(e) => {
                eprintln!("dial: {e}");
                let backoff = Duration::from_secs((2u64.pow(attempt)).min(300));
                tokio::time::sleep(backoff).await;
                continue;
            }
        };

        println!("connected");
        let (_, mut rx) = ws.split();
        let mut stop = false;

        while let Some(frame) = rx.next().await {
            match frame {
                Err(e) => { eprintln!("read: {e}"); break; }
                Ok(Ws::Close(Some(CloseFrame { reason, .. }))) => {
                    if reason == "key_expired" || reason == "key_invalidated" {
                        eprintln!("key invalid: {reason}"); stop = true;
                    } else { eprintln!("closed: {reason}"); }
                    break;
                }
                Ok(f) => {
                    if let Ok(text) = f.to_text() {
                        if let Ok(m) = serde_json::from_str::<Msg>(text) {
                            match m.msg_type.as_str() {
                                "welcome" => println!("welcome: tier={} cex={}", m.tier, m.allowed_cex),
                                "announcement" | "test_announcement" => on_announcement(&m),
                                _ => {}
                            }
                        }
                    }
                }
            }
        }

        if stop { return; }
        let backoff = Duration::from_secs((2u64.pow(attempt)).min(300));
        tokio::time::sleep(backoff).await;
    }
}