Чем API Binance.US отличается от глобальной платформы

Краткое сравнение Binance.US и глобальной платформы

Базовый адрес и API-ключи

Первое отличие находится в конфигурации. REST-запросы отправляются на https://api.binance.us, вызовы request-response WebSocket API — на wss://ws-api.binance.us:443/ws-api/v3, а маркет-стримы и user-data streams используют wss://stream.binance.us:9443. Значительная часть спотовых маршрутов сохраняет знакомую структуру /api/v3/..., поэтому SDK часто поддерживают площадку через отдельный профиль или замену хоста. Например, в ccxt для неё предусмотрен отдельный идентификатор binanceus.

Аутентификация похожа лишь частично. В актуальной документации Binance.US подписанные запросы показаны через HMAC-SHA256, тогда как глобальный Spot API поддерживает ключи HMAC, RSA и Ed25519. Поэтому существующий HMAC-клиент обычно адаптировать проще, но переносить глобальные варианты подписи и набор эндпоинтов без проверки нельзя.

Ключ Binance.US принадлежит аккаунту Binance.US. Регистрация, проверка личности, балансы, разрешения и учётные данные отделены от глобальной платформы, поэтому ключи между ними не работают. Binance.US документирует три типа ключей: Exchange, Custodial Solution и Credit Line. Для обычной торговли и данных используется Exchange API key. До завершения KYC создать ключ нельзя.

Важно разделять три разных механизма. Вес запросов накапливается по исходящему IP и делится между всеми соединениями с этого адреса. Лимиты на ордера ведутся по аккаунту и являются общими для его API-ключей. Разрешения и необязательный IP whitelisting настраиваются для конкретного ключа: Binance.US рекомендует IP whitelisting ради безопасности, но не описывает его как обязательное условие работы.

Документация Binance.US находится на отдельном сайте, имеет собственный список изменений и зеркало репозитория — и это единственный источник, который соответствует поведению этой площадки. Чтение глобальной документации при запросах к американскому хосту порождает заметную долю багрепортов в духе «документация не совпадает с API».

Как набор эндпоинтов соотносится с глобальной платформой

Формулировка «сокращённый набор» в целом верна, но не описывает всю картину. У Binance.US нет аналогов глобальных фьючерсов и опционов, поэтому код, построенный на fapi или опционных хостах, нельзя перенести одной заменой домена. Спотовая торговля, маркет-данные, операции кошелька, WebSocket API, стримы и OTC-эндпоинты присутствуют, но список символов и детали методов развиваются по собственному графику площадки.

Этот график важен: эндпоинт может сначала появиться на одной платформе, а позже — на другой. Binance.US добавила GET /api/v3/myFilters, чтобы возвращать фильтры конкретного аккаунта, включая MAX_ASSET; теперь тот же маршрут есть и в глобальном Spot API. Поэтому корректнее считать API значительно пересекающимися, но независимо версионируемыми, а не закреплять за одним эндпоинтом постоянный статус «только для США».

Практическая отправная точка для американского Spot API — exchangeInfo. Запрашивайте его на том хосте, который реально использует приложение: ответ содержит актуальные лимиты, список символов, фильтры и статусы. Binance.US повысила потолок REQUEST_WEIGHT до 6 000 в минуту, хотя в старых примерах документации всё ещё встречается историческое значение 1 200. Клиент должен доверять живому ответу:

curl -s "https://api.binance.us/api/v3/exchangeInfo" | jq '.rateLimits'

В выводе найдите объект REQUEST_WEIGHT и прочитайте поля interval, intervalNum и limit. Вес отдельных эндпоинтов также отличается от глобальной платформы: changelog Binance.US указывает, например, вес 25 для trades и historicalTrades, 4 для aggTrades и 20 для myTrades при переданном символе. Поэтому троттлер, скопированный из глобального клиента, может ошибаться даже при совпадающем названии маршрута.

Общее количество символов даёт лишь грубое представление о размере площадки и не отвечает на вопрос, доступны ли нужные приложению пары. Сравнивайте сами наборы символов:

curl -s "https://api.binance.us/api/v3/exchangeInfo" \
  | jq -r '.symbols[].symbol' | sort -u > binance-us-symbols.txt

curl -s "https://api.binance.com/api/v3/exchangeInfo" \
  | jq -r '.symbols[].symbol' | sort -u > binance-global-symbols.txt

# Есть глобально, но отсутствует на Binance.US:
comm -23 binance-global-symbols.txt binance-us-symbols.txt

# Есть на Binance.US, но отсутствует в глобальном ответе:
comm -13 binance-global-symbols.txt binance-us-symbols.txt

Запускайте сравнение только из инфраструктуры, которая правомочна обращаться к обеим площадкам. Если глобальный запрос вернул 451, пустой файл нельзя считать результатом сравнения. Сначала проверьте HTTP-статус, затем смотрите разницу множеств или ищите в выводе конкретные символы, необходимые интеграции.

Что означает HTTP 451

Ответ с кодом 451 использует статус HTTP «Unavailable For Legal Reasons», определённый RFC 7725. Binance возвращает его, когда запрошенный глобальный сервис недоступен для локации, из которой приходит запрос. Решение может приниматься по исходящему IP до аутентификации, поэтому ошибка встречается и на публичных эндпоинтах без API-ключа.

На практике путаницу создают три свойства. Решение принимается по исходящему IP, а не по аккаунту, — поэтому 451 срабатывает и на публичных эндпоинтах, до всякой проверки ключа, и поэтому один и тот же код работает с ноутбука и падает с сервера. Действует он на всё семейство хостов: api, fapi и стриминговые хосты отвечают одинаково. И появиться он может без единого изменения с вашей стороны: управляемые платформы ловили его после того, как провайдер переносил мощности, а отдельные дата-центры начинали отдавать 451, пока соседние в той же стране продолжали работать — сообщения на форуме разработчиков самой Binance от владельцев размещённых ботов выглядят ровно так.

Начните диагностику без учётных данных:

url="https://api.binance.com/api/v3/ping"

curl -sS \
  -D response-headers.txt \
  -o response-body.txt \
  -w "HTTP %{http_code}\n" \
  "$url"

printf '\n--- Заголовки ---\n'
cat response-headers.txt

printf '\n--- Тело ответа ---\n'
cat response-body.txt

printf '\n--- Исходящий IP ---\n'
curl -sS https://api.ipify.org && printf '\n'

Сначала смотрите на строку статуса. Ответ 200 от /api/v3/ping исключает текущую блокировку 451 для этого хоста и исходящего маршрута. Если публичный эндпоинт вернул 451, замена или повторная генерация API-ключа не исправит запрос, потому что ключ для него вообще не требовался. Сохраните hostname, тело ответа, исходящий IP, регион провайдера и время, после чего проверьте площадку, которая обслуживает ваш аккаунт.

Правильная реакция скучна и легальна: используйте площадку, которая обслуживает вашу юрисдикцию. Если вы соответствуете требованиям Binance.US и живёте в поддерживаемом штате или территории, работайте через неё с отдельным аккаунтом и ключами. Binance.US принимает регистрацию и верификацию не во всех штатах и регионах США, поэтому актуальный список доступности нужно проверить отдельно. Если инфраструктура находится в ограниченном регионе, а вы — нет, перенесите нагрузку туда, где вы правомочны работать по принятым условиям. Обход проверки правомочности — не техническая задача, а нарушение условий, которое может стоить аккаунта, и никакая инфраструктура этого не меняет.

Другие региональные площадки

США — самый заметный пример более широкой схемы, но региональные платформы не используют один универсальный формат API. Отдельное юридическое лицо может означать другой аккаунт, ключи, базовые адреса, семейства маршрутов, продукты и документацию. Даже при знакомых торговых терминах такую площадку нужно рассматривать как самостоятельную интеграцию.

Документация Binance TR показывает, почему нельзя автоматически переносить структуру /api/v3: в ней указан базовый адрес https://www.binance.tr, маршруты вида /open/v1/..., а для части API — https://api.binance.me. Документацию и страницы поддержки Binance Japan также следует проверять отдельно, а не выводить доступность ключей, продуктов и маршрутов из устройства американской или глобальной платформы.

Рабочее правило, которое переживает изменения регулирования и продуктов, простое. Сначала определите, какое юридическое лицо обслуживает аккаунт. Затем возьмите из его актуальной документации базовый URL, способ подписи, discovery-эндпоинты, символы, веса и лимиты. Живой запрос exchangeInfo полезен для Binance.US и глобального Spot API, но не является универсальным способом обнаружения возможностей каждой региональной площадки.

При работе торговых и информационных нагрузок в разных регионах стоит учитывать две детали. Первая — стабильность адреса: если вы настроили IP whitelisting на ключе, динамический исходящий адрес превращает эту защиту в простой. Вторая — весовые бюджеты относятся к конкретным площадке и IP, поэтому нагрузку другого юридического лица или хоста нужно измерять отдельно. Под такую схему и собраны наши прокси для Binance: выделенные IPv4-адреса, статичные на весь срок плана, по одному на ключ или бота, с выбором страны — чтобы интеграция подключалась из того региона, в котором ей положено работать.