Посібник з інтеграції 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.

Як створити ключ WEEX API, не заблокувавши себе

Створення ключа відбувається на сторінці керування API WEEX у розділі Акаунт. Механіка займає дві хвилини. Конфігураційні рішення займають більше часу, і три з них незворотні.

1. Створіть ключ. Кожен акаунт підтримує до 10 груп API-ключів. Нові ключі за замовчуванням мають статус Read Only.
2. Виберіть дозволи явно. Readonly, Spot та Futures/Contract є незалежними. Вибір Spot не надає доступу до ф'ючерсів, а ф'ючерсний ордер, надісланий з ключем тільки для споту, поверне -1052 INSUFFICIENT_PERMISSIONS замість чогось більш описового.
3. Встановіть парольну фразу обережно. Власні рекомендації WEEX з безпеки радять використовувати лише буквено-цифрові символи — спеціальні символи в парольній фразі є задокументованим джерелом помилок автентифікації. Парольну фразу неможливо змінити або відновити. Втратите її — доведеться створювати новий ключ.
4. Прив'яжіть IP-білий список. До 10 IP-адрес через кому. Ключі без обмежень — це найбільший ризик зберігання в налаштуваннях API, і WEEX позначає їх як такі.
5. Зачекайте. Створені або змінені ключі потребують приблизно 15 хвилин для поширення в системах WEEX. Розробники часто сприймають це вікно як помилку підпису і починають переписувати робочий код.

Зберігайте APIKey, SecretKey та Passphrase під час створення. Тільки APIKey можна отримати згодом.

Одна звичка, яку варто прийняти з першого дня: ніколи не вмикайте дозволи, пов'язані з виведенням коштів, на ключі, який використовується в торговому процесі. Розділяйте ключі лише для читання для моніторингу та ключі з правами на торгівлю для виконання, і надайте кожному власну IP-прив'язку. Операційні витрати — десять хвилин; режим відмови, який це запобігає — повна втрата.

Підписання запиту WEEX API: 30-секундне вікно

Кожен приватний виклик WEEX API містить чотири заголовки плюс тип контенту:

Повідомлення, яке ви підписуєте, є конкатенацією, і правило конкатенації змінюється залежно від наявності рядка запиту:

# рядок запиту присутній
timestamp + METHOD + requestPath + "?" + queryString + body

# рядок запиту відсутній
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. Контейнери з дрейфуючими годинниками, «холодні» запуски безсерверних функцій та віртуальні машини без NTP — все це періодично дає збій, що гірше, ніж постійна помилка, бо виглядає як проблема мережі. Запитуйте час сервера при запуску, зберігайте зміщення та застосовуйте його до кожного часового мітки.

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

Ліміти запитів WEEX API, з якими ви зіткнетеся

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

Ліміти запитів взяті з документації спотового API WEEX та 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. Відкат, керований заголовком залишку ваги, перевершить будь-який фіксований інтервал очікування, який ви захардкодите.

Спотові та ф'ючерсні ордери не мають спільної схеми

Це розбіжність, яка ламає спільні рівні абстракції, і вона не виділена помітно ніде в документації — ви знайдете це, порівнявши дві сторінки ордерів.

Останній рядок заслуговує на увагу. Ф'ючерсна кінцева точка може повернути 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 — це те, що варто засвоїти. Це не має нічого спільного з вашими обліковими даними — край 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-білі списки, відкат лімітів — це стандартна робота з інтеграції біржі.

Єдине, що не є стандартним і на що варто виділити час — це розбіжність схем споту/ф'ючерсів. Спільна абстракція ордерів на обох поверхнях виглядатиме правильно при перегляді, але не працюватиме у продакшені. Будуйте їх як два адаптери.

Готові почати? Створіть ключ у розділі Акаунт → Керування API на 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. Скільки часу потрібно, щоб новий ключ WEEX API почав працювати?

Приблизно 15 хвилин для поширення нового або зміненого ключа. Помилки автентифікації всередині цього вікна очікувані і не є проблемою підпису.

6. Чи можу я тестувати стратегії WEEX API без реальних коштів?

Так, для ф'ючерсів. Демо-кінцеві точки за адресою /capi/v3/sim/ приймають ті самі автентифіковані запити і повертають баланси, номіновані в SUSDT. Ставтеся до них як до інструменту інтеграційного тестування, а не як до бектесту стратегії.

Попередження про ризики

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

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