Гайд по WEEX API: от API-ключа до первой подписанной сделки

Большинство интеграций WEEX API терпят неудачу не из-за логики стратегии. Они ломаются в первый же час из-за четырех неочевидных вещей: ключ, который вы только что создали, еще не активен; пара, которой вы хотите торговать, не добавлена в белый список API; WebSocket-соединение отклоняется, потому что вы не отправили заголовок User-Agent; ваша подпись неверна на один байт, потому что вы подписали пересериализованное тело запроса вместо точной строки, которую отправили.

Этот гайд охватывает WEEX API от начала до конца: создание ключей, права доступа, правила подписи, лимиты запросов, коды ошибок, которые реально стопорят разработку, и эндпоинты для бумажной торговли (paper trading), позволяющие протестировать всё без риска капиталом. Все данные ниже проверены по актуальной документации V3 на 21 августа 2026 года.

Что покрывает WEEX API: спот, фьючерсы и WebSocket

WEEX API разделен на два независимых продукта с двумя независимыми REST-доменами. Спот находится на api-spot.weex.com по пути /api/v3. Фьючерсы находятся на api-contract.weex.com по пути /capi/v3. Они используют общую схему подписи и набор заголовков, но больше ничего общего — разные флаги разрешений, разные хосты WebSocket, разные параметры ордеров.

Эндпоинты делятся на два класса доступа. Публичные эндпоинты (время сервера, глубина стакана, клайны, ставка финансирования, 24-часовые тикеры) не требуют аутентификации, что делает их самым быстрым способом проверить сетевой путь, прежде чем переходить к подписи. Приватные эндпоинты — балансы, позиции, ордера — требуют полной подписи из четырех заголовков для каждого запроса.

Для тиковых данных WEEX направляет вас к WebSocket, а не к REST-поллингу, и это правильное решение: публичные каналы несут потоки тикеров, глубины и сделок, а приватный канал — обновления аккаунта, позиций и ордеров. Поллинг глубины через REST для построения стакана просто сожжет ваш лимит веса IP без какой-либо пользы.

Один исторический ориентир для масштаба: по состоянию на 21 августа 2026 года бессрочный контракт BTC/USDT котировался по последней цене 65 088,8 USDT в книге фьючерсов WEEX — это тот же тик, который возвращает ваш вызов /capi/v3/market/ticker24h.

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

Ключи создаются в разделе Аккаунт → Управление API на веб-платформе. Каждый аккаунт может иметь до 10 групп API-ключей.

При создании возвращаются три значения, и третье — то, которое люди теряют:

• APIKey — публичный идентификатор, отправляется в заголовке ACCESS-KEY.
• SecretKey — секрет для HMAC-подписи. Показывается один раз.
• Passphrase — задается пользователем, отправляется в ACCESS-PASSPHRASE. Ее нельзя изменить или восстановить. Потеряли — создавайте ключ заново.

Три детали конфигурации вызывают больше тикетов в поддержку, чем всё остальное вместе взятое:

1. Новые ключи по умолчанию имеют статус «Только чтение». Разрешение на торговлю — отдельный чекбокс, и он специфичен для продукта: Spot для спота, Futures для контрактов. Выбор одного не включает другой. Размещение ордера с ключом «Только чтение» вернет -1052.
2. Ключи распространяются по миру около 15 минут. Ключ, который проходит аутентификацию, но падает на другом эндпоинте, обычно просто еще не полностью активен. Подождите, прежде чем отлаживать подпись.
3. Используйте в passphrase только буквы и цифры. WEEX прямо рекомендует избегать спецсимволов. Ошибки кодировки спецсимволов — это крайне неприятный класс багов.

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

WEEX Spot API vs Futures API: важные различия

Держите эту таблицу открытой во время разработки. Продукты выглядят симметрично, но это не так.

Два из этих различий бьют больнее всего. Фьючерсы требуют newClientOrderId для каждого ордера, поэтому код, написанный для спота, будет отклонен при попытке работы с контрактами. А POST_ONLY существует только во фьючерсах — у стратегии maker-only, написанной под спот, нет встроенного способа гарантировать, что она не пересечет спред.

Параметры TP/SL во фьючерсах заслуживают большего внимания. Привязка tpTriggerPrice и slTriggerPrice к ордеру на вход означает, что ваш стоп существует на бирже с момента открытия позиции, а не выставляется последующим вызовом, который может не пережить краш процесса или разрыв сети. Вы также можете выбрать источник триггера для каждой ноги через TpWorkingType и SlWorkingType — MARK_PRICE для стопа является более безопасным дефолтом, так как CONTRACT_PRICE может быть искажен случайной сделкой на неликвидной паре.

Как правильно подписать запрос к WEEX API

Каждый приватный вызов несет четыре заголовка: ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP, плюс Content-Type: application/json.

Правило подписи идентично для обоих доменов. Соберите строку:

timestamp + METHOD + requestPath + "?" + queryString + body

Уберите ? и queryString, если нет параметров запроса; уберите body, если его нет. Подпишите HMAC-SHA256 с вашим SecretKey, затем закодируйте результат в Base64.

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

Обратите внимание на data=body, а не json=payload. Подписывайте точные байты, которые передаете. Если ваш HTTP-клиент пересериализует словарь — меняет порядок ключей или вставляет пробелы — сервер вычислит другой дайджест, и вы получите -1047 без намека на то, что причиной был пробел.

Окно времени для timestamp составляет 30 секунд относительно сервера WEEX. Если часы хоста дрейфуют, запросы начнут периодически падать, что выглядит как баг подписи. Вызывайте GET /capi/v3/market/time и отслеживайте смещение, вместо того чтобы доверять локальному времени.

Приватные каналы WebSocket подписываются иначе: сообщение — это только timestamp + requestPath, где requestPath равен /v3/ws/private. Ни метода, ни тела.

Один нюанс документации: страница подписи фьючерсов иллюстрирует правило, используя пути спота (/api/v3/order). Правило верно, примеры путей — нет. Используйте /capi/v3/... для домена контрактов.

Лимиты WEEX API: два ведра, а не одно

WEEX использует два независимых счетчика лимитов, и их смешивание — причина, по которой боты получают неожиданные 429.

Важная деталь: размещение ордера потребляет ноль веса IP, а отмены и запросы потребляют ноль лимита ордеров. Это действительно разные реестры. Маркет-мейкер, который агрессивно выставляет и отменяет ордера, исчерпает лимит ордеров при размещении, в то время как трафик отмен будет тихо съедать вес IP — и ни один счетчик не предупредит о другом.

Читайте заголовки, а не считайте запросы на клиенте. X-REMAINING-WEIGHT-1M и X-ORDER-REMAINING-1M приходят с каждым вызовом и отражают взгляд сервера. Превышение лимита возвращает HTTP 429 и вызывает бан на 10 секунд; продолжение «долбежки» после 429 — кратчайший путь к отключению доступа к API службой контроля рисков.

Если вы запускаете несколько стратегий с одной машины, помните, что ведро IP общее. Два бота на одном сервере конкурируют за те же 500 веса на 10 секунд.

Ошибки WEEX API, стопорящие большинство интеграций

Ответы об ошибках — это пара кода и сообщения. Вот те, что всплывают при интеграции:

-1058 заслуживает особого внимания. Не каждый контракт WEEX доступен для API-торговли. Вызывайте GET /capi/v3/market/apiTradingSymbols при запуске, кэшируйте массив и проверяйте символы перед созданием ордера. Эта проверка исключает целый класс ошибок времени выполнения.

Еще два момента, которые выглядят как баги, но ими не являются. WebSocket-хендшейк, возвращающий 403, почти всегда означает, что вы забыли заголовок User-Agent — содержимое произвольное, но файрвол сбрасывает соединения без него. Документация противоречит сама себе по ошибкам отмены: справочник кодов относит -1054 к системной ошибке, а -3200 к «ордер не существует», в то время как FAQ фьючерсов относит «ордер не существует» к -1054. Обрабатывайте оба кода при отмене.

Тестируйте на эндпоинтах бумажной торговли WEEX

WEEX добавил эндпоинты симуляции торговли во фьючерсах, которые достаточно точно имитируют реальность:

• GET /capi/v3/sim/balance — симулированные балансы в SUSDT
• GET /capi/v3/sim/position/allPosition — позиции, включая пары лонг/шорт в режиме хеджирования
• POST /capi/v3/sim/order — размещение ордеров
• GET /capi/v3/sim/order/history — история симулированных сделок

Тот же домен, те же заголовки, та же подпись. Замена /capi/v3/order на /capi/v3/sim/order — часто всё, что нужно для полного теста интеграции.

Используйте их для проверки частей системы, которые ломаются только в реальных условиях: логика переподключения после разрыва WebSocket, восстановление состояния ордера, если исполнение пришло раньше подтверждения REST, расчет размера позиции. Это ошибки, которые стоят денег, и для их выявления не нужен реальный капитал.

Важно знать: WEEX не поддерживает исполнение по вебхукам TradingView и FIX-шлюз. Если ваша стратегия рассчитывала на них, планируйте REST и WebSocket.

Заключение

WEEX API прост, как только вы поймете, что спот и фьючерсы — это два продукта, делящих схему подписи и почти ничего больше. Правильные заголовки, подпись точных байтов, кэширование белого списка символов, чтение заголовков лимитов вместо подсчета запросов и явная обработка -1047, -1052 и -1058 — это покрывает большинство проблем.

Последовательность, экономящая время: создание ключа с правами «Только чтение», подтверждение ответа публичного эндпоинта, работающее приватное чтение, прогон стратегии на бумажной торговле, и только потом включение прав на торговлю и привязка IP. Полные ссылки на эндпоинты — в документации WEEX Futures API и Spot API, а специфика лимитов — в FAQ фьючерсного API.

FAQ

1. Нужны ли разные ключи для спота и фьючерсов?

Нет, один ключ может иметь оба разрешения. Но это разные чекбоксы, и оба выключены по умолчанию. Ключ только с Spot будет возвращать -1052 на фьючерсных ордерах.

2. Каковы лимиты WEEX API?

Два независимых ведра: 500 веса на 10 сек на IP для REST и 300 ордеров в минуту на аккаунт для фьючерсов. WebSocket ограничен 20 соединениями на IP и 100 каналами на соединение. Превышение возвращает 429 и бан на 10 сек.

3. Почему ключ возвращает -1049 сразу после создания?

Ключи распространяются по системам WEEX около 15 минут. Подождите. Если не помогло, проверьте, нет ли в passphrase спецсимволов — рекомендуется только alphanumeric.

4. Можно ли торговать любой парой WEEX через API?

Нет. Только пары из белого списка. Вызывайте GET /capi/v3/market/apiTradingSymbols для актуального списка; всё остальное вернет -1058.

5. Поддерживает ли WEEX алерты TradingView или FIX?

Нет, по состоянию на апрель 2026 года. Автоматизация — только через REST и WebSocket.

6. Как протестировать стратегию без риска?

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

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

Криптоактивы волатильны; торговля ими может привести к потере капитала. API-торговля концентрирует этот риск. Автоматизированные системы могут выставить сотни ордеров до того, как человек заметит ошибку, а ошибка подписи, устаревший фид цен или необработанное переподключение могут открыть нежелательные позиции. Фьючерсы добавляют риск плеча: до 400x на некоторых контрактах WEEX могут ликвидировать позицию за секунды, а использование CONTRACT_PRICE как триггера стопа на тонком рынке подвергает вас стоп-аутам из-за фитилей. API-ключи — это риск кастодиальный: непривязанный ключ с правами торговли — это активный доступ из любой точки интернета. Привяжите IP, держите права торговли выключенными до тестов на бумажной торговле и рассчитывайте позиции исходя из того, что ваш код рано или поздно ошибется.