Посібник з WEEX API: від API-ключа до вашого першого підписаного ордера

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

Цей посібник проведе вас через WEEX API від початку до кінця: створення ключів, дозволи, правила підпису, ліміти запитів, коди помилок, що зупиняють розробку, та ендпоінти для паперової торгівлі, які дозволяють протестувати все без ризику капіталом. Усе нижчеперелічене перевірено на основі актуальної документації V3 станом на 21 серпня 2026 року.

Що охоплює WEEX API: спот, ф'ючерси та WebSocket

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

Ендпоінти поділяються на два класи доступу. Публічні ендпоінти (час сервера, глибина стакану, klines, ставка фінансування, 24-годинні тікери) не потребують жодної автентифікації, що робить їх найшвидшим способом перевірити роботу мережевого шляху перед підписом. Приватні ендпоінти — баланси, позиції, ордери — вимагають повного чотиризаголовкового підпису для кожного запиту.

Для будь-яких даних рівня тіків WEEX спрямовує вас до WebSocket, а не до REST-опитування, і це правильне рішення: публічні канали передають потоки тікерів, глибини та торгів, а приватний канал передає оновлення рахунку, позицій та ордерів. Опитування глибини через REST для побудови стакану лише вичерпає ваш ліміт ваги IP без жодної користі.

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

Як створити WEEX API-ключ та налаштувати дозволи

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

Створення повертає три значення, і третє — це те, яке люди часто втрачають:

• APIKey — публічний ідентифікатор, що надсилається в заголовку ACCESS-KEY.
• SecretKey — секрет для HMAC-підпису. Відображається один раз.
• Passphrase — визначена користувачем, надсилається в ACCESS-PASSPHRASE. Її неможливо змінити або відновити. Якщо втратите її, доведеться створювати ключ заново.

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

1. Нові ключі за замовчуванням мають статус Read-only. Дозвіл на торгівлю — це окремий чекбокс, і він специфічний для продукту: Spot для спотової торгівлі, Futures для контрактів. Вибір одного не активує інший. Розміщення ордера з ключем Read-only повертає -1052.
2. Ключам потрібно близько 15 хвилин для глобального поширення. Ключ, який проходить автентифікацію, але видає помилку на іншому ендпоінті, зазвичай просто ще не повністю активний. Зачекайте, перш ніж починати налагодження підпису.
3. Використовуйте лише буквено-цифрові символи для парольної фрази. WEEX наполегливо рекомендує уникати спеціальних символів. Невідповідності кодування у спеціальних символах — це вкрай неприємний клас помилок для виправлення.

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

WEEX spot API проти futures API: важливі відмінності

Це таблиця, яку варто тримати відкритою під час розробки. Два продукти виглядають симетричними, але це не так.

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

Параметри 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 без жодного натяку на те, що причиною був пробіл.

Вікно часової мітки становить 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 — позиції, включаючи пари long/short у режимі хеджування
• 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 — це покриває більшість проблем.

Послідовність, яка економить найбільше часу: створіть ключ із дозволом Read-only, підтвердьте відповідь публічного ендпоінта, налаштуйте один підписаний приватний виклик, запустіть повну стратегію проти ендпоінтів паперової торгівлі, і лише потім увімкніть дозвіл на торгівлю та прив'яжіть білий список IP. Повні посилання на ендпоінти знаходяться в документації WEEX futures API та документації WEEX spot API, а деталі дозволів та лімітів зібрані в FAQ ф'ючерсного API.

FAQ

1. Чи потрібні окремі ключі WEEX API для споту та ф'ючерсів?

Ні — один ключ може мати обидва дозволи. Але це окремі чекбокси, і кожен з них за замовчуванням вимкнений. Ключ, у якого відмічено лише Spot, повертатиме -1052 на кожному ф'ючерсному ордері, і навпаки.

2. Які ліміти запитів WEEX API?

Два незалежні кошики: 500 ваги на 10 секунд на IP для загальних REST-ендпоінтів та 300 розміщень ордерів на хвилину на акаунт для ф'ючерсів. WebSocket обмежений 20 одночасними з'єднаннями на IP, 100 каналами на з'єднання. Перевищення будь-якого з них повертає HTTP 429 і 10-секундний бан.

3. Чому мій ключ WEEX API повертає -1049 відразу після створення?

Новим і зміненим ключам потрібно близько 15 хвилин для поширення системами WEEX. Якщо ключ свіжий, зачекайте перед подальшим налагодженням. Якщо проблема зберігається, перевірте, чи містить парольна фраза спеціальні символи — WEEX рекомендує лише буквено-цифрові.

4. Чи можу я торгувати будь-якою парою WEEX через API?

Ні. Програмно доступні лише пари з білого списку API-торгівлі. Викликайте GET /capi/v3/market/apiTradingSymbols для отримання актуального списку; усе, що поза ним, повертає -1058.

5. Чи підтримує WEEX сповіщення TradingView або FIX?

Станом на оновлення документації у квітні 2026 року жодне з них не підтримується. Автоматизація працює через REST та WebSocket API.

6. Як протестувати стратегію WEEX API без ризику коштами?

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

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

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