Як викликати API криптобіржі, щоб не отримати блокування

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

Цей посібник розглядає, що таке API біржі, як фактично формується запит, які дозволи потрібно ввімкнути та де реально можуть бути скомпрометовані API-ключі. Усі специфічні для платформи цифри нижче взяті з документації API спотової та ф'ючерсної торгівлі WEEX, востаннє оновленої 14.04.2026, і відображають стан на серпень 2026 року. Ліміти запитів і моделі дозволів відрізняються між біржами та змінюються з часом — перевіряйте актуальну документацію перед тим, як будувати щось на основі цих даних.

Що насправді дозволяє робити API криптобіржі

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

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

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

Ще одне обмеження, яке варто знати перед плануванням стеку: WEEX наразі не підтримує торгівлю через вебхуки TradingView або протокол FIX. Якщо ваш робочий процес залежить від будь-чого з этого, це рішення приймається зараз, а не після того, як ви написали інтеграцію.

Як викликати API біржі за чотири кроки

Приватний API-виклик — це звичайний HTTPS-запит, що несе чотири елементи підтвердження. Зробіть усі чотири правильно, і виклик спрацює; помиліться в одному, і ви отримаєте конкретний код помилки, який вкаже, де саме.

Крок 1 — Створіть і збережіть облікові дані. На WEEX ключі створюються в розділі Акаунт → Керування API. Кожен акаунт може містити до 10 груп API-ключів. Створення повертає три значення: APIKey (публічний ідентифікатор), SecretKey (використовується для підпису) та Passphrase, яку ви визначаєте самі. Passphrase неможливо відновити або змінити — якщо ви її втратите, єдиний варіант — видалити ключ і створити новий. Використовуйте лише літери та цифри; документація WEEX спеціально радить уникати спеціальних символів. Як створити API-ключ WEEX, щоб не втратити доступ.

Крок 2 — Створіть рядок для підпису. WEEX об'єднує в порядку: часову мітку в мілісекундах, HTTP-метод у верхньому регістрі, шлях запиту, потім рядок запиту з префіксом знака питання, якщо він є, потім тіло запиту, якщо воно є. Для запиту глибини це виглядає приблизно так: 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20. Порядок не підлягає обговоренню, як і регістр — символи повинні бути у верхньому регістрі, а нижній регістр btcusdt поверне помилку недійсного символу, а не підказку.

Крок 3 — Підпишіть його. Хешуйте рядок за допомогою HMAC SHA256, використовуючи ваш SecretKey, потім закодуйте результат у Base64. Це значення вставляється в заголовок ACCESS-SIGN разом із ACCESS-TIMESTAMP. Повна специфікація підпису знаходиться в документації WEEX, і її варто прочитати рядок за рядком — створення підпису є місцем, де ламається більшість перших інтеграцій.

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

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

Дозволи API-ключів: що ввімкнути, а що залишити вимкненим

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

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

Якщо вам потрібна торгівля, увімкніть рівно один ринок. Спотовий бот із дозволом на ф'ючерси несе ризик, який він ніколи не використає. Коли ордер повертає помилку -1052 (недостатньо дозволів), причиною майже завжди є цей чекбокс — ключ був створений до того, як був обраний дозвіл на торгівлю, або дозвіл був наданий для неправильного ринку.

Налаштуйте IP-білий список, поки ви в процесі створення. WEEX позначає необмежені ключі як ризик безпеки у власній документації, і це реальне обмеження: запит з адреси, якої немає в білому списку, повертає -1056 (недійсний IP), незалежно від того, чи ідеальний підпис. У цьому й суть. Ключ із білого списку, який витік, — це ключ, який зловмисник не зможе використати зі своєї інфраструктури.

Чи безпечна торгівля через API біржі? Де насправді витікають ключі

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

Шляхи витоку, які з'являються неодноразово:

• Ключі, завантажені в публічний репозиторій. Жорстко закодовані облікові дані у файлі конфігурації, відправленому на GitHub, за лічені хвилини збираються автоматизованими сканерами.
• Ключі, вставлені в сторонній бот або сервіс «сигналів». Надання ключа з дозволом на торгівлю неперевіреній платформі фактично означає передачу контролю над вашими позиціями. Якщо сервіс вимагає дозвіл на торгівлю для того, що потребує лише даних, це відповідь на питання, чи варто його використовувати.
• Ключі, якими діляться в чатах підтримки. Жоден легітимний агент підтримки біржі не запитує SecretKey або Passphrase. WEEX чітко заявляє про це у своїх примітках для розробників.
• Один ключ для всього, назавжди. Один ключ, який не оновлюється, для розробки, тестування та продакшену означає, що витік будь-де — це витік всюди.

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

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

Ліміти запитів і помилки, що вбивають перший виклик

Ліміти запитів — це те, де «це працювало в тестуванні» перетворюється на «це перестало працювати в продакшені». WEEX застосовує два окремі лічильники: вага на основі IP для більшості ендпоінтів і кількість ордерів на основі акаунта для розміщення ордерів. Розміщення ордерів не споживає вагу IP, тому два бюджети витрачаються незалежно.

Джерело: FAQ щодо спотового та ф'ючерсного API WEEX, востаннє оновлено 14.04.2026.

Перевищте ліміт, і ви отримаєте HTTP 429 плюс 10-секундний бан. Вам не потрібно вгадувати, наскільки ви близькі — кожна відповідь містить заголовки, що повідомляють про споживання: X-USED-WEIGHT та X-REMAINING-WEIGHT для ваги IP, X-ORDER-COUNT та X-ORDER-REMAINING для кількості ордерів, кожен із суфіксом інтервалу (X-USED-WEIGHT-1M охоплює останню хвилину). Читання цих заголовків і зниження активності до того, як ви впретеся в стіну, — це різниця між стійкою інтеграцією та тією, яку банять щогодини. WEEX публікує вагу для кожного ендпоінта у своїх правилах обмеження доступу.

Коли виклик не вдається, код помилки точно вказує причину. Ось ті, на які припадає більшість невдач першої інтеграції:

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

Одна примітка щодо версії: WEEX рекомендує будувати інтеграцію на основі ендпоінтів V3. V1 та V2 застарівають, тому інтеграція, написана на основі старішої документації, успадковує міграцію, яка їй не потрібна.

Тестуйте перед торгівлею: ендпоінти для паперової торгівлі

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

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

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

Що варто запам'ятати

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

Якщо ви починаєте з нуля, порядок такий: створіть ключ «лише читання», викличте публічний ендпоінт, викличте автентифікований ендпоінт читання, потім симулюйте, потім торгуйте найменшим розміром, який дозволяє ваша стратегія. API-хаб WEEX охоплює доступ до споту та ф'ючерсів для 100+ активів, а FAQ для розробників відповідає на питання щодо дозволів, лімітів запитів і формату символів, які генерують більшість тікетів у підтримку.

FAQ

1. Чи потрібно вміти програмувати, щоб використовувати API біржі?

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

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

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

3. Чому мій API-ключ працює в тестуванні, але не працює в продакшені?

Дві найпоширеніші причини — це білий список IP та ліміти запитів. Ключ, доданий у білий список вашої машини розробки, повертає -1056 із сервера продакшену, а обсяги трафіку, які проходять у тестуванні, можуть перевищувати бюджет ваги 500 на 10 секунд на IP під реальним навантаженням.

4. Скільки часу потрібно, щоб новий API-ключ почав працювати?

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

5. У чому різниця між REST і WebSocket для API бірж?

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

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

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

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

Криптоактиви волатильні, і торгівля через API може посилити як швидкість, так і розмір збитків, аж до повної втрати коштів на вашому торговому рахунку. Автоматизовані стратегії зазнають невдач способами, якими ручна торгівля не зазнає: бот, який досягає ліміту запитів посеред виконання, може залишити позицію відкритою, яку ваш код вважає закритою, розрив з'єднання WebSocket може приховати сповіщення про виконання, поки ордери продовжують виконуватися, а логічна помилка може розмістити сотні ненавмисних ордерів, перш ніж ви помітите. Кредитне плече на ф'ючерсах посилює кожен із цих ризиків. Ризики кастодіального зберігання та облікових даних однаково реальні — скомпрометований SecretKey або Passphrase можуть бути використані для торгівлі на вашому акаунті, а втрачену Passphrase неможливо відновити. Використовуйте дозволи «лише читання» там, де торгівля не потрібна, увімкніть білий список IP, тестуйте на ендпоінтах паперової торгівлі перед тим, як вкладати реальні кошти, і ніколи не починайте перше реальне розгортання з сумами, які ви не можете дозволити собі втратити. Ніщо з вищесказаного не є інвестиційною порадою.