Руководство по интеграции WEEX API: аутентификация, лимиты и ошибка 403

Большинство руководств по API криптобирж заканчиваются на «создайте ключ и подключите к нему своего бота». Это приведет вас к первой ошибке -1052, а не к работающей интеграции. WEEX API — это двухстековая система: спот и фьючерсы работают на разных доменах с разными схемами ордеров. Ошибки, на которые разработчики тратят больше всего времени, не концептуальны. Это пропущенный заголовок User-Agent, часы, которые разошлись на 31 секунду, или торговая пара, которая есть на бирже, но не включена для программного доступа.

Это руководство охватывает интеграцию WEEX API от начала до конца: что покрывает API, как создать ключ, который не заблокирует вас, как на самом деле строится подпись, с какими лимитами скорости вы столкнетесь в продакшене и какие ошибки ломают большинство первых попыток. Все цифры здесь взяты из документации WEEX V3 по состоянию на август 2026 года.

Что покрывает WEEX API — а что до сих пор нет

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

Покрытие реальное, но ограниченное. В анонсе бета-версии WEEX OpenAPI указано 140+ поддерживаемых пар, но распределение неравномерное: таблица фьючерсов насчитывает около 130 бессрочных контрактов, тогда как спотовый список — около 25 пар. Если ваша стратегия торгует спотовой парой средней капитализации, проверьте этот список, прежде чем писать код, потому что наличие пары в веб-интерфейсе не означает, что она принимает API-ордера.

Два отсутствующих элемента важны для тех, кто переходит с другой площадки. FAQ по спотовому API WEEX, обновленный 14 апреля 2026 года, прямо гласит, что ни FIX API, ни интеграция с TradingView в настоящее время не поддерживаются. Если ваш стек исполнения предполагает FIX-сессию или вебхук-алерты из TradingView, вам придется перестраивать этот слой под REST и WebSocket.

Также стоит отметить: эндпоинты V1 и V2 устаревают, и WEEX рекомендует V3 для новых сборок. Примеры кода, которые вы найдете на сторонних бот-платформах, все еще могут указывать на пути V2.

Как создать API-ключ WEEX, не заблокировав себя

Создание ключа происходит на странице управления API WEEX в разделе Account. Механика занимает две минуты. Решения по конфигурации занимают больше времени, и три из них необратимы.

1. Создайте ключ. Каждый аккаунт поддерживает до 10 групп API-ключей. Новые ключи по умолчанию имеют статус Read Only.
2. Явно выберите права доступа. Readonly, Spot и Futures/Contract независимы. Отметка Spot не дает доступа к фьючерсам, а фьючерсный ордер, отправленный с ключом только для спота, вернет -1052 INSUFFICIENT_PERMISSIONS вместо чего-то более описательного.
3. Тщательно установите парольную фразу (passphrase). Руководство по безопасности WEEX рекомендует использовать только буквенно-цифровые символы — спецсимволы в парольной фразе являются задокументированным источником ошибок аутентификации. Парольную фразу нельзя изменить или восстановить. Потеряли — создавайте новый ключ.
4. Привяжите IP-адрес к белому списку. До 10 IP, через запятую. Ключи без ограничений — самый большой риск кастодиального хранения в API-настройках, и WEEX помечает их соответствующим образом.
5. Подождите. Новым или измененным ключам требуется около 15 минут для распространения по системам WEEX. Разработчики часто интерпретируют это окно как поломку подписи и начинают переписывать рабочий код.

Сохраните APIKey, SecretKey и Passphrase при создании. Только APIKey можно получить позже.

Одна привычка, которую стоит внедрить с первого дня: никогда не включайте права на вывод средств на ключе, который живет в торговом процессе. Разделяйте ключи «только для чтения» для мониторинга и ключи с правами на торговлю для исполнения, и привязывайте каждый к своему IP. Операционные затраты — десять минут; тип сбоя, который это предотвращает — полный.

Подпись WEEX API запроса: 30-секундное окно

Каждый приватный вызов WEEX API несет четыре заголовка плюс тип контента:

Сообщение, которое вы подписываете — это конкатенация, и правило конкатенации меняется в зависимости от наличия строки запроса:

# queryString присутствует
timestamp + METHOD + requestPath + "?" + queryString + body

# queryString отсутствует
timestamp + METHOD + requestPath + body

METHOD в верхнем регистре. body — это сырая JSON-строка, байт-в-байт идентичная той, что вы передаете — сериализуйте один раз, подпишите эту строку, отправьте эту строку. Повторная сериализация между подписью и отправкой — самая частая причина сбоя подписи, так как порядок ключей или пробелы могут измениться, и хеш перестанет совпадать.

Пример из спецификации подписи WEEX, получение стакана:

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

И ордер:

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

Затем HMAC-SHA256 с вашим секретным ключом, затем Base64.

Ограничение, на котором ловят людей в продакшене — это часы. Запросы отклоняются, если ACCESS-TIMESTAMP отклоняется более чем на 30 секунд от времени сервера WEEX, возвращая -1046 ACCESS_TIMESTAMP_EXPIRED. Контейнеры с дрейфующими часами, serverless-холодные старты и виртуальные машины без NTP периодически проваливают это — что хуже, чем постоянный сбой, потому что выглядит как сетевая проблема. Запрашивайте время сервера при запуске, сохраняйте смещение и применяйте его к каждому таймстемпу.

Приватные каналы WebSocket используют более короткое сообщение: timestamp + "/v3/ws/private", подписанное так же — те же заголовки, те же шаги HMAC-SHA256 и Base64, просто другая строка.

Лимиты WEEX API, с которыми вы столкнетесь

Превышение лимита возвращает HTTP 429 и бан на 10 секунд. WEEX разделяет лимиты на два независимых бюджета, что является частью, которую большинство интеграций моделируют неправильно.

Лимиты скорости взяты из документации WEEX spot API и FAQ, актуальны на 14 апреля 2026 года.

Различие, которое имеет значение: размещение ордеров ограничено аккаунтом, все остальное — IP. Эндпоинты размещения потребляют ноль веса IP — счетчик IP в их заголовках ответа показывает 0. Поэтому запуск трех стратегий с одного IP не утраивает ваш бюджет ордеров (он на аккаунт), но утраивает потребление 500-весового пула IP для рыночных данных и запросов.

Читайте заголовки, а не гадайте. Каждый ответ несет X-USED-WEIGHT-1M и X-REMAINING-WEIGHT-1M; эндпоинты ордеров несут X-ORDER-COUNT-10S и X-ORDER-REMAINING-10S. Back-off, управляемый заголовком оставшегося веса, будет работать лучше любого фиксированного интервала сна, который вы захардкодите.

Спотовые и фьючерсные ордера не делят схему

Это расхождение ломает общие слои абстракции, и оно нигде не выделено в документации — вы находите его, сравнивая две страницы ордеров.

Последняя строка заслуживает акцента. Эндпоинт фьючерсов может вернуть HTTP 200 с {"success": false, "errorCode": "...", "errorMessage": "..."}. Код, который проверяет только HTTP-статус, зарегистрирует отклоненный ордер как исполненный и радостно продолжит строить позицию, которой у него нет. Проверяйте success явно в каждом ответе на фьючерсный ордер.

Также есть живое несоответствие в самой документации. Страница API Public Parameters для спота все еще перечисляет строчные перечисления (buy, sell, limit, market) рядом с полем force, в то время как эндпоинты ордеров V3 в разделе Trade используют заглавные BUY, SELL, LIMIT и timeInForce. Страницы эндпоинтов отражают V3; страница параметров несет значения эпохи V2. Когда они не согласны, доверяйте странице эндпоинта — и отправляйте -1116 INVALID_ORDER_TYPE в свои логи как сигнал того, что вы скопировали не оттуда.

Символы чувствительны к регистру и должны быть в верхнем регистре. btcusdt возвращает -1121.

Пять ошибок, которые ломают большинство WEEX API интеграций

WebSocket 403 — это то, что стоит усвоить. Это не имеет ничего общего с вашими учетными данными — edge WEEX отклоняет рукопожатия без заголовков, поэтому идеально подписанная приватная подписка терпит неудачу так же, как и неподписанная. Разработчики дебажат свою подпись час, прежде чем найти это. WEEX документирует это в FAQ по спотовому API, и исправление — одна строка.

Поддерживайте соединения правильно. Сервер отправляет периодические пинги — {"event":"ping","time":"..."} на публичных каналах, {"type":"ping","time":"..."} на приватных — и ожидает {"method":"PONG","id":1} в ответ. Пропустите более 10, и сервер закроет соединение. Тихий разрыв во время волатильной сессии — это то, как бот в итоге торгует по устаревшему стакану.

Полная таксономия ошибок живет в FAQ по спотовому API WEEX и справочнике кодов ошибок.

Тестируйте в демо-режиме, прежде чем рисковать реальной маржой

WEEX поставляет симулированную фьючерсную среду, доступную через тот же аутентифицированный паттерн, по пути /capi/v3/sim/. Эндпоинт демо-баланса возвращает позиции, номинированные в SUSDT — симулированном USDT — наряду с availableBalance, frozen и unrealizePnl. Демо-версии PlaceOrder, GetAllPositions и GetOrderHistory все доступны.

Используйте это для того, для чего это действительно хорошо: проверка построения подписи, обработки ошибок и логики переподключения. Не используйте это для проверки экономики стратегии. Симулированная площадка не имеет позиции в очереди, поведения частичного исполнения под нагрузкой и проскальзывания — трех вещей, которые отделяют бэктест от P&L.

Для калибровки на лайв-стороне: WEEX котировал бессрочные контракты BTC по 65,088.80 USDT на своем рынке фьючерсов BTC/USDT по состоянию на 21 августа 2026 года, с кредитным плечом до 400×. Этот потолок плеча — причина быть консервативным с автоматизированной системой, а не фича, на которую стоит опираться. Баг в подписи, который стреляет дубликатами ордеров, выживаем при 3×. Но не при 400×.

Короткая версия

WEEX API прост, как только выполняются три условия: ваши часы синхронизированы в 30-секундном окне, ваш WebSocket отправляет User-Agent, а ваш фьючерсный код проверяет поле success, а не HTTP-статус. Все остальное — права доступа, белые списки IP, back-off лимитов — стандартная работа по интеграции биржи.

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

Готовы начать? Создайте ключ в Account → API Management на WEEX, сначала направьте его в демо-режим и расширяйте права только тогда, когда ваши пути переподключения и ошибок доказаны.

FAQ

1. Бесплатен ли WEEX API?

Да. Отдельной платы за доступ к API нет. Вы платите стандартные торговые комиссии спота или фьючерсов за исполненные ордера, так же, как при ручной торговле.

2. Сколько API-ключей я могу создать на WEEX?

До 10 групп API-ключей на аккаунт. Каждый ключ может быть настроен независимо с правами Readonly, Spot или Futures/Contract и своим белым списком IP до 10 адресов.

3. Почему мой WEEX API-ключ работает в Postman, но не с моего сервера?

Почти всегда это белый список IP (-1056) или дрейф часов (-1046). Облачные среды часто выходят с вращающегося NAT IP, которого нет в вашем белом списке, а контейнеры без NTP дрейфуют за пределы 30-секундного окна подписи.

4. Поддерживает ли WEEX API вебхуки FIX или TradingView?

Нет. По состоянию на обновление документации в апреле 2026 года, ни FIX API, ни интеграция с TradingView не поддерживаются. REST и WebSocket — доступные транспорты.

5. Сколько времени проходит, прежде чем новый API-ключ WEEX начинает работать?

Около 15 минут для распространения нового или измененного ключа. Ошибки аутентификации внутри этого окна ожидаемы и не являются проблемой подписи.

6. Могу ли я тестировать стратегии WEEX API без реальных средств?

Да, для фьючерсов. Демо-эндпоинты под /capi/v3/sim/ принимают те же аутентифицированные запросы и возвращают балансы, номинированные в SUSDT. Относитесь к ним как к тестовому стенду интеграции, а не как к бэктесту стратегии.

Предупреждение о рисках

Криптоактивы волатильны, и их торговля может привести к частичной или полной потере капитала. API-торговля концентрирует этот риск, а не снижает его: логическая ошибка, необработанный отказ или устаревший фид WebSocket могут исполнить десятки непреднамеренных ордеров, прежде чем человек заметит. WEEX предлагает плечо до 400× на некоторых бессрочных контрактах, что увеличивает как правильные, так и неправильные сигналы — автоматизированная система, работающая с высоким плечом, может быть ликвидирована в одно неблагоприятное движение.

Специфические риски для учета в API-деплое: риск кастодиального хранения от ключей без ограничений или утечек, которые дают полный контроль над аккаунтом; операционный риск от дрейфа часов, банов по лимитам и разорванных соединений, которые оставляют позиции без управления; риск ликвидности на низколиквидных парах, где рыночный ордер двигает стакан против вас; и риск контрагента и регуляторный риск, так как доступность API-торговли и конкретных пар может измениться без уведомления. Привязывайте белый список IP, держите права на вывод средств выключенными на торговых ключах, ограничивайте размер позиции в коде, а не в намерениях, и тестируйте пути ошибок в демо-режиме перед деплоем капитала. Ничто здесь не является инвестиционным советом.