API объявлений о листингах

WebSocket API объявлений и уведомлений о листингах на криптобиржах в реальном времени. Подключитесь и получайте структурированные JSON-оповещения о листингах Binance, Upbit, Bithumb.

Обзор API

CryptoListing.ws предоставляет два WebSocket-эндпоинта рассылки, которые стримят объявления и уведомления о листингах с нескольких криптобирж в реальном времени. API создан для автоматических торговых систем, которым нужно максимально быстрое уведомление о новых объявлениях о листингах. Один и тот же API-ключ аутентифицирует на обоих эндпоинтах — выбирайте по местоположению вашего бота.

Формат сообщения

Каждое сообщение об объявлении содержит тикер, биржу, тип листинга и три отметки времени с микросекундной точностью:

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

Полный актуальный список значений listingType приведён в справочнике сообщений.

Фильтрация по биржам

Используйте query-параметр ?cex= на токийском эндпоинте, чтобы подписаться только на конкретные биржи. Сеульский эндпоинт уже стримит исключительно объявления Upbit, поэтому там фильтр необязателен.

wss://cryptolisting.ws                       // Токио: все биржи (Binance, Upbit, Bithumb)
wss://cryptolisting.ws?cex=binance             // Токио: только binance
wss://cryptolisting.ws?cex=binance,upbit       // Токио: binance + upbit
wss://kr.cryptolisting.ws                    // Сеул: только Upbit (ультра-быстро из Кореи)

Измерение задержки

Каждое объявление содержит две отметки времени в микросекундах от эпохи UNIX. Вычислите свою задержку:

dispatch_delay  = dispatchTimestampUs - detectedTimestampUs
network_delay   = your_receive_time  - dispatchTimestampUs
total_latency   = your_receive_time  - detectedTimestampUs

Почему стоит выбрать этот API объявлений о листингах?

В отличие от REST-API с опросом или Telegram-ботов, наш WebSocket API доставляет уведомления о листингах в тот же миг, как они обнаружены. Zero-copy рассылка означает, что сообщение об объявлении сериализуется один раз и передаётся всем подписчикам — без накладных расходов на сериализацию для каждого клиента. Такая архитектура обеспечивает стабильно ультра-быструю задержку рассылки независимо от числа подписчиков. Подробнее по отдельным биржам: уведомления о листингах Binance, объявления о листингах Upbit, уведомления о листингах Bithumb.

Частые вопросы

Какой протокол использует API?

WebSocket (RFC 6455) поверх TLS 1.2+. Аутентификация выполняется через HTTP-заголовок X-API-Key в запросе апгрейда. Сообщения — UTF-8 JSON в бинарных фреймах. Один и тот же API-ключ аутентифицирует на обоих эндпоинтах — выбирайте по местоположению бота, а не по бирже, на которой торгуете.

Какие биржи поддерживаются?

Binance (спот-листинги, фьючерсные листинги, делистинги, HODLer-эйрдропы, Monitoring Tag extend / remove), Upbit и Bithumb (спот-листинги на рынке KRW, снятие caution и спот-делистинги — торгуемые стадии корейского лайфцикла caution). Новые биржи добавляются по запросам подписчиков. Используйте query-параметр ?cex= на токийском эндпоинте для фильтрации.

Как пройти аутентификацию?

Добавьте заголовок X-API-Key в запрос апгрейда WebSocket. Получите ключ, написав нам в Telegram на @CLWfeed. Один и тот же ключ работает на обоих эндпоинтах. Примеры кода — в документации по аутентификации.

Какая задержка сообщений?

Задержка рассылки ультра-быстрая. Каждое объявление несёт поля detectedTimestampUs и dispatchTimestampUs с микросекундной точностью, чтобы вы могли самостоятельно измерить производительность от начала до конца. Сетевая задержка зависит от местоположения бота: хосты в AWS Tokyo (ap-northeast-1a - apne1-az4) получают наименьший end-to-end до токийского эндпоинта, а хосты в AWS Seoul (ap-northeast-2c - apne2-az3) — до сеульского эндпоинта Upbit.

Чем различаются два эндпоинта?

wss://cryptolisting.ws (Токио) стримит полный фид и является глобальным эндпоинтом по умолчанию. wss://kr.cryptolisting.ws (Сеул) стримит только Upbit и оптимизирован для торговых ботов, размещённых в Корее — он устраняет сетевой переход Сеул → Токио на стороне обнаружения. Лимиты подключений и запросов учитываются независимо на каждом эндпоинте.

Что происходит при разрыве соединения?

Сервер отправляет heartbeat каждые 30 секунд; клиентам следует отправлять WebSocket-пинги с той же частотой. При разрыве переподключайтесь с экспоненциальной задержкой (обычно начиная с 1 с, удваивая до 30 с). Листинги, отправленные, пока вы были отключены, НЕ воспроизводятся повторно — для журнала прошлых обнаружений см. последние обнаружения.