Як викликати API біржі: ключі, підписи та коди помилок

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

Цей посібник охоплює весь шлях: що таке API біржі, які виклики потребують ключа, як насправді створюється підпис і — частина, яку майже ніхто не публікує — перелік конкретних кодів помилок, з якими ви зіткнетеся, та способи їх виправлення. Приклади використовують посібник з інтеграції WEEX API, оскільки це один із небагатьох центрів розробників бірж, який публікує свою модель дозволів, затримку поширення та ліміти запитів на операцію у відкритому доступі. Усе нижче було перевірено згідно з актуальною документацією розробника WEEX станом на 28 липня 2026 року; FAQ спотового API платформи має позначку останнього оновлення 14 квітня 2026 року.

Що робить API біржі та які виклики потребують ключа

API біржі — це набір HTTP та WebSocket ендпоінтів, які дозволяють вашому програмному забезпеченню робити те, що ви інакше робили б кліками: читати ціни, перевіряти баланс, розміщувати ордер, скасовувати його. Нічого містичного.

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

Практичний висновок: ви можете побудувати та протестувати всю частину даних бота до того, як згенеруєте ключ. Зробіть це спочатку. Це нічого не коштує і виявить помилки форматування символів та вирівнювання свічок, поки радіус ураження дорівнює нулю.

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

На WEEX шлях такий: Акаунт → Керування API → Створити API ключ, після чого йде перевірка безпеки. Кожен акаунт може мати до 10 груп API ключів, чого достатньо для запуску окремих ключів для досліджень, тестування та продакшну — і вам варто це робити, оскільки скомпрометований ключ тоді стане локальним інцидентом, а не загальним.

З цього екрана виходять три облікові дані, і вони не є взаємозамінними:

• APIKey — публічний ідентифікатор, який біржа використовує для вашої ідентифікації.
• SecretKey — приватний ключ, яким підписується ваш код. Відображається один раз.
• Passphrase — фраза, яку ви обираєте. Якщо ви її втратите, її неможливо відновити або скинути; ви видаляєте ключ і починаєте спочатку. WEEX також вимагає, щоб вона містила лише літери та цифри — без спеціальних символів. Це реальне обмеження, а не пропозиція, і парольна фраза з пунктуацією є надзвичайно поширеною причиною помилок автентифікації.

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

Два висновки з цієї таблиці. По-перше, якщо ви створили спотового бота і вибрали лише «Тільки читання», кожен ваш ордер буде відхилено — це найпоширеніша скарга «мій ключ не працює». По-друге, і це корисніше: у цьому списку немає дозволу на виведення коштів. API ключ WEEX не може вивести кошти з платформи. Це структурне обмеження варте більше, ніж будь-які поради з гігієни ключів, оскільки воно обмежує те, що зловмисник може зробити з вкраденим ключем, лише несанкціонованою торгівлею, а не виведенням гаманця.

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

Один нюанс часу, про який документація говорить прямо, а більшість сторонніх посібників пропускають: новостворені або змінені API ключі потребують приблизно 15 хвилин для поширення по системі. Якщо ваш перший виклик не вдається відразу після того, як ви відмітили новий дозвіл, зачекайте, перш ніж переписувати код підпису. Багато людей витратили годину на налагодження робочого коду через це.

Повні покрокові інструкції налаштування знаходяться в посібнику з підготовки інтеграції WEEX API.

Як викликати API біржі: чотири заголовки та рядок підпису

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

Сам підпис — це хеш рядка, який ви збираєте у фіксованому порядку:

timestamp + HTTP метод у верхньому регістрі + шлях запиту + ? + рядок запиту + тіло

Об'єднайте їх, хешуйте за допомогою HMAC SHA256, використовуючи ваш SecretKey, потім закодуйте результат у Base64. Якщо рядка запиту немає, приберіть ? та сегмент запиту. Якщо тіла немає, пропустіть його. Метод має бути у верхньому регістрі. Шлях — це шлях ендпоінту, а не повна URL-адреса.

Три деталі спричиняють більшість невідповідностей підписів:

1. Вікно часової мітки становить 30 секунд. WEEX відхиляє будь-який запит, чий ACCESS-TIMESTAMP відхиляється більше ніж на 30 секунд від часу сервера. Якщо годинник вашої машини відстає — а контейнери та віртуальні машини постійно відстають — ви отримуватимете випадкові помилки. Запитуйте ендпоінт часу сервера біржі при запуску, обчислюйте зміщення та застосовуйте його. Не довіряйте локальному годиннику.
2. Тіло, яке ви підписуєте, має бути байт-в-байт ідентичним тілу, яке ви надсилаєте. Пересеріалізація JSON між підписанням та надсиланням змінює порядок ключів або числовий формат, і хеш більше не збігається. Підписуйте точний рядок, який ви передаватимете.
3. Символи чутливі до регістру і повинні бути у верхньому регістрі, і вони повинні бути точними значеннями, які повертає ендпоінт продуктів/символів платформи. Вгадування формату — це спосіб отримати помилку недійсного символу на активі, який явно існує.

Ендпоінти знаходяться на окремих доменах за лінійками продуктів — спотові запити йдуть на api-spot.weex.com, ф'ючерсні на api-contract.weex.com, з WebSocket потоками на ws-spot.weex.com. Спрямування спотового виклику на ф'ючерсний хост призводить до помилок, які виглядають як проблеми з автентифікацією, але ними не є.

Чому мій перший виклик API не вдається? Декодування кодів помилок

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

Ця помилка 403 у WebSocket заслуговує на окрему увагу. Вона не має нічого спільного з вашими обліковими даними, не дає коду помилки для пошуку і викликана пропуском, який більшість HTTP-бібліотек роблять мовчки. Це тип помилки, яка з'їдає весь день.

Повний список знаходиться в довіднику кодів помилок WEEX API.

Які ліміти запитів API біржі?

Ліміти запитів — це те, що добре працює при тестуванні і ламається в продакшні, тому що вони спрацьовують лише тоді, коли волатильність зростає і ваш бот починає активно працювати. Стандарт на WEEX — 10 запитів на секунду, з жорсткішими опублікованими лімітами на конкретні операції.

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

Коли ви отримуєте 429, зменшуйте частоту експоненціально. Повторні спроби негайно в щільному циклі — це спосіб, яким акаунти потрапляють під ризикові контролі, і WEEX автоматично вимкне дозволи API на акаунті, який генерує стійкі високочастотні недійсні запити. Відновлення означає звернення до підтримки. Опубліковані примітки щодо лімітів та дозволів знаходяться в FAQ WEEX API.

Чи безпечна торгівля через API біржі?

«Безпечна» — неправильне формулювання. API ключ — це обмежена делегація повноважень, і питання в тому, наскільки суворо ви її обмежуєте.

Структурні захисти роблять більшу частину роботи. Обмежені дозволи означають, що ключ «тільки читання» не може торгувати. Відсутність дозволу на виведення на ключах WEEX означає, що жоден ключ не може вивести ваші кошти з платформи. Білий список IP означає, що вкрадений ключ марний з мережі зловмисника. Незалежні сфери споту та ф'ючерсів означають, що помилка спотового бота не може відкрити позицію з кредитним плечем. Складіть ці чотири фактори, і реальний найгірший сценарій знижується з «акаунт спустошено» до «небажані угоди з однієї відомої IP-адреси» — відновлювано та виявляємо.

Що залишається — на вас:

• Ніколи не додавайте ключі в репозиторій і не вбудовуйте їх у клієнтський код. Використовуйте змінні середовища або менеджер секретів.
• Використовуйте окремі ключі для кожного середовища, щоб відкликання скомпрометованого ключа тестування не зупинило продакшн.
• Оновлюйте за розкладом і видаляйте ключі, як тільки підозрюєте витік.
• Логуйте кожну відповідь, включаючи помилки. Сплеск помилок часто є першою ознакою того, що щось не так, і ви не можете бачити те, що не записуєте.
• Вбудовуйте запобіжники в самого бота — максимальна частота ордерів, максимальне проковзування, максимальна позиція — тому що ліміти біржі захищають біржу, а не ваш P&L.

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

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

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

Поетапне розгортання, яке працює: тільки публічні ендпоінти → ключ «тільки читання» на живих даних → демо-ендпоінти для життєвого циклу ордера → живий ключ з мінімальним розміром → масштабування. Кожен етап виявляє свій клас помилок, і тільки останній коштує грошей.

Ще одна операційна деталь, яка ламає довготривалих ботів: сервер WebSocket періодично надсилає ping, і ваш клієнт повинен відповісти pong. Не відповісте більше десяти разів — і сервер закриє підключення. Бот, який «випадково перестає отримувати дані через кілька годин», майже завжди має відсутній обробник pong.

Ваш чек-лист перед першим живим викликом

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

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

FAQ

1. Як викликати API біржі без написання коду?

Ви не можете викликати його безпосередньо, але вам не обов'язково писати клієнт самостійно. Трекери портфелів, податкові інструменти та сторонні платформи ботів приймають API ключ біржі та обробляють запити за вас. Надайте цим інструментам ключ «тільки читання», якщо вони дійсно не потребують торгівлі — більшість не потребують.

2. Чи потрібен API ключ для публічних ендпоінтів ринкових даних?

Ні. Ціни, свічки, глибина стакану та список символів не потребують автентифікації на WEEX та більшості великих бірж. Єдиний нюанс — підключення WebSocket, які потребують заголовка User-Agent навіть на публічних каналах, інакше брандмауер поверне 403.

3. Чому мій API ключ працює для балансів, але не для розміщення ордерів?

Тому що дозвіл на торгівлю окремий від дозволу на читання і за замовчуванням вимкнений. Увімкніть сферу Спот або Ф'ючерси в керуванні API, потім зачекайте близько 15 хвилин, поки зміни поширяться, перед повторною спробою. До того часу ви продовжуватимете бачити помилки недостатніх дозволів.

4. Чи може хтось вивести мої кошти, якщо вкраде мій API ключ?

Не на WEEX — API ключі обмежені лише читанням та торгівлею, без дозволу на виведення. Вкрадений ключ все ще може розміщувати небажані ордери, тому білий список IP та швидке видалення ключів мають значення, але він не може вивести активи з платформи.

5. Що таке помилка часової мітки і як її виправити?

Запити відхиляються, якщо підписана часова мітка відхиляється більше ніж на 30 секунд від часу сервера біржі. Виправлення — запитувати ендпоінт часу сервера при запуску програми, зберігати зміщення та застосовувати його до кожного підпису, замість читання локального системного годинника, який відстає.

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

Жодне з них не підтримується станом на оновлення документації платформи у квітні 2026 року. Інтеграції мають проходити через інтерфейси REST та WebSocket. Перевірте поточну документацію розробника перед будівництвом навколо цього, оскільки підтримувані протоколи змінюються.

7. Скільки API ключів може мати один акаунт?

До 10 груп ключів. Використовуйте цей запас — окремі ключі для розробки, тестування та продакшну означають, що відкликання одного скомпрометованого облікового запису не виведе всю вашу операцію офлайн.

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

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