Квант на OKX API: створення демо-ключа, перший ордер і його скасування

Сюди ти, мабуть, потрапив так: побачив кілька скриншотів прибутку від квант-блогерів, загорівся, відкрив кабінет OKX, щоб узятися до справи — і застряг на першому ж кроці. Тиснеш «Керування API», а там купа опцій: apiKey, Secret, Passphrase, читання, торгівля, виведення, білий список IP. Кожне слово знайоме, а разом узяті — не зрозуміло, що куди вписувати. Тоді ти закриваєш сторінку й кажеш собі: «Потім розберуся».

Ця стаття допоможе тобі цей крок пройти. Ми (команда MeowQuant) розклали весь шлях — від відкриття API з нуля до запуску першого скрипта-ордера на Python — на кілька кроків, і кожен пройшли самі, включно з тими підводними каменями, про які офіційна документація мовчить, але на які ти майже напевно наштовхнешся. Прочитавши, ти зможеш: правильно створити API-ключ із мінімальними правами в демо-середовищі OKX, парою десятків рядків коду переконатися, що він працює, а потім на демо-рахунку виставити й скасувати свій перший ордер і звірити, чи збігається повернений статус із очікуваним. Програмістом бути не обов'язково — просто роби за прикладом.

Спершу спитай себе: тобі справді потрібен API?

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

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

То коли ж варто відкривати API? Наш висновок — у таких випадках:

• Логіка стратегії, яку ти хочеш, вбудованим ботам не до снаги: наприклад, динамічно міняти позицію за якимось індикатором чи зв'язувати кілька монет.
• Тобі потрібен бектест — масово тягнути історичні свічки, симулювати виконання. (Увага: історичні свічки — це публічні ринкові дані, їх можна тягнути й без створення ключа; сам бектест API-ключа не потребує, а права виведення — і поготів.)
• Ти хочеш одночасно крутити кілька стратегій, і керувати ними скриптом ефективніше, ніж руками.
• Ти просто хочеш вивчати квант, а біржу використовувати як пісочницю для практики.

Якщо впізнав себе — читай далі. А якщо виявив, що насправді хочеш лише «поставити сітку, щоб вона заробляла на коливаннях, поки я сплю» — то спершу відкрий у кабінеті вбудовану сітку й спробуй. Коли впрешся у стелю вбудованих інструментів, тоді й повернешся до API, не пізно буде. У нас є окрема стаття про те, як налаштувати параметри бота-сітки — вона саме для тих, хто йде цим шляхом.

Три речі, які треба розуміти перед створенням ключа

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

① Ти отримаєш три облікові дані, а не два

Багато хто думає, що API — це «один акаунт, один пароль». На OKX ти спантеличишся: він дає тобі три речі:

• apiKey: публічний ідентифікатор цього ключа, на кшталт «логіна».
• secret (Secret Key): ключ для підпису запитів, на кшталт «пароля». Показується лише один раз при створенні.
• Passphrase: рядок-кодова фраза, який ти сам задаєш під час створення. Особливий для OKX.

Третій, Passphrase, — це зона найбільших провалів новачків. Це не твій пароль для входу в OKX, а окремий рядок символів, який ти задаєш при створенні цього ключа. Гірше того: у бібліотеці ccxt для Python це поле зветься не passphrase, а password. Тому безліч людей за звичкою вписують туди пароль для входу — і потім чухають потилицю над помилкою «автентифікація не вдалася». Запам'ятай одну фразу: password у ccxt = Passphrase, який ти задав при створенні ключа.

② Права — лише «Торгівля», ні в якому разі не «Виведення»

При створенні ключа OKX дасть обрати, що цей ключ зможе робити. Головних опцій три:

• Читання: баланс, ордери, виписка — ендпойнти, які лише дивляться й нічого не чіпають. Найнижчий ризик. (До речі: свічки, стакан і ticker — це публічні ринкові дані, для них API-ключ узагалі не потрібен, тож якщо ти лише тягнеш дані для бектесту, ключ можна й не створювати.)
• Торгівля: виставляти, скасовувати, змінювати ордери. Обов'язково для стратегій. І ось момент, який легко проґавити: за визначенням із документації OKX право торгівлі охоплює ще й переказ коштів (фандинговий рахунок ↔ торговий рахунок, головний рахунок ↔ субрахунки) та частину налаштувань рахунку — це не просто «купувати й продавати».
• Виведення: вивести монети на адресу в блокчейні.

Тут є майже безвинятковий безпековий мінімум: для квант-ключа став лише «Читання» й «Торгівля» — і ніколи не став «Виведення». Логіка проста: поставиш «Виведення» — витік дорівнює тому, що ти віддав ключ від сейфа; не поставиш — то принаймні ніхто не виведе монети на адресу в блокчейні. Тільки не вважай це страховкою, та й прикриває воно менше, ніж здається: як сказано вище, право торгівлі саме собою вже охоплює переказ коштів і частину налаштувань рахунку, тож гроші між фандинговим, торговим рахунками й субрахунками зловмисник усе одно пересуне. До того ж ключ лише з правом торгівлі теж здатен обнулити тебе. Той, хто його отримав, може агресивно виставляти ордери в малоліквідній парі з тонкою книгою заявок і сам виступати контрагентом; твої гроші йдуть як «торгові збитки», у виписці кожен рядок виглядає як звичайна угода, а розкрутити це потім набагато важче, ніж підозріле виведення. Реально працює лише все разом: не давати право виведення, прив'язати білий список IP і регулярно міняти ключ. Автоматизованій торгівлі дія «виведення» взагалі непотрібна, тож це право несе тобі лише шкоду без жодної користі.

③ Чи ставити білий список IP

OKX дозволяє прив'язати до ключа білий список IP — приймаються лише запити з указаних адрес. Це дуже корисний додатковий запобіжник.

Критерій простий: якщо твій скрипт крутиться на машині зі сталим IP (наприклад, хмарний сервер, домашній інтернет зі статичною публічною адресою) — додай цей IP у білий список, і безпека одразу підніметься на щабель. На кожен ключ OKX дозволяє прив'язати до 20 IP, підтримуються й підмережі, тож «вихідна адреса інколи змінюється» ще не привід відмовлятися від білого списку.

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

Створюємо API-ключ у кабінеті OKX

Три речі зрозумів — тепер до кабінету по ключ. Спершу уточнимо, який саме ключ тобі треба створити за цією статтею: демо-ключ (Demo Trading). Демо й реал в OKX — два незалежні середовища, і ключ теж створюється окремо всередині демо-середовища: реальний ключ жодним перемикачем на демо не перетвориш. Скрипти виставлення й скасування ордера далі в статті справді надсилають ордери на біржу, тож для першого запуску бери демо-ключ; коли процес відпрацюєш, тими самими кроками створиш ключ і на реалі.

Нижче шлях створення ключа, актуальний для поточного кабінету OKX (інтерфейс іноді трохи міняється, але логіка лишається; якщо хочеш демо-ключ — спершу перемкнись у демо-середовище, а вже потім проходь цей шлях):

1. Увійди в OKX, наведи курсор на аватар у верхньому правому куті, у випадному меню знайди «API» або «Керування API» і зайди.
2. На сторінці керування API натисни «Створити API-ключ». Якщо запитає про призначення — обери варіант для власної торгівлі, не обирай стороннє підключення.
3. Дай ключу назву (примітку), наприклад meow-grid-bot, щоб згодом одразу впізнати, для чого він.
4. Задай Passphrase. Тут ти сам вигадуєш рядок-кодову фразу, запам'ятай її — її використовуватиме ccxt, і вона прив'язана лише до цього ключа; загубиш — лишається тільки видалити й створити заново.
5. Постав права: «Читання» й «Торгівля», без «Виведення». (Дивись мінімум із попереднього розділу.)
6. Якщо запускаєш на машині зі сталим IP — впиши білий список IP (до 20 IP на ключ, підмережі підтримуються). Залишити порожнім теж можна, але знай ціну: за офіційним правилом ключ без прив'язаного IP, який має право торгівлі чи виведення, спливає після 14 днів без активності, і викликати його можна з будь-якої машини.
7. Підтверди, пройди двофакторну перевірку (телефон / пошта / Google Authenticator).
8. З'явиться apiKey і Secret Key. Secret показується лише цей один раз — одразу скопіюй і збережи в безпечне місце. Закриєш сторінку — більше не побачиш ніколи; загубиш — лишається видалити ключ і створити заново.

На цьому кроці в тебе на руках мають бути три речі: apiKey, Secret і Passphrase, який ти щойно задав сам. Збережи їх у локальний файл, який не синхронізується в хмару — не роби скриншот у месенджер, не вставляй у жодні онлайн-нотатки. Наступним кроком ми цими трьома обліковими даними під'єднаємося.

Під'єднуємося через Python + ccxt і перевіряємо

Облікові дані на руках — далі перевіримо, що вони справді працюють. Ми використовуємо бібліотеку ccxt — вона загортає API сотень бірж в єдиний інтерфейс, тож тобі не доведеться гризти сирі деталі підпису OKX: кількома рядками коду перевіриш баланс і виставиш ордер.

Спершу встанови бібліотеку. Відкрий термінал (командний рядок) і набери:

pip install ccxt

Після встановлення створи файл okx_check.py, перепиши туди цей фрагмент і заміни заглушки в трьох лапках на свої облікові дані:

import ccxt

# Три облікові дані: apiKey, secret, password (= Passphrase)
okx = ccxt.okx({
    'apiKey':   'твій_apiKey',
    'secret':   'твій_secret',
    'password': 'твій_Passphrase',   # особливе для OKX, новачки найчастіше пропускають саме це
})

# Тягнемо баланс рахунку, перевіряємо, що автентифікація пройшла
balance = okx.fetch_balance()
print('USDT доступно:', balance['USDT']['free'])
print('USDT усього:', balance['USDT']['total'])

Збережи й запусти в терміналі python okx_check.py. Якщо він вивів твій баланс USDT (хай навіть 0) — вітаємо, автентифікація пройшла, API під'єднано. Якщо видав помилку — не панікуй: у вісьмох випадках із десяти одне з трьох облікових даних уписане неправильно або пропущене. Перегорни до розділу «Підводні камені, на які найчастіше наступають» — там перелічено, який текст помилки якій причині відповідає.

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

Перший скрипт: ордер і скасування

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

Перед ордером з'ясуй дві дрібниці:

Як писати symbol (торгову пару). У ccxt спотові пари пишуть у форматі базова/котирувальна монета: біткоїн до USDT — це BTC/USDT, ефір до USDT — ETH/USDT. Зверни увагу: прямий слеш, великі літери. Помилковий формат — ще одне джерело частих помилок.

Параметри ордера. Метод виставлення у ccxt — create_order(symbol, type, side, amount, price), п'ять параметрів: торгова пара, тип ордера (limit лімітний / market ринковий), напрямок (buy купити / sell продати), кількість, ціна.

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

import ccxt, time

# 🔴 Цей фрагмент справді виставляє ордер, тож облікові дані мають бути
#    від демо-ключа (Demo Trading). Демо-ключ створюють окремо всередині
#    демо-середовища; реальний — це не той самий набір облікових даних.
okx = ccxt.okx({
    'apiKey':   'демо_apiKey',
    'secret':   'демо_secret',
    'password': 'демо_Passphrase',
})

# Ключовий рядок: без нього ордер нижче висітиме на реалі за справжні гроші
okx.set_sandbox_mode(True)

# Самоперевірка: має надрукувати 1. Якщо друкує None — далі не запускай
print(okx.headers.get('x-simulated-trading'))

symbol = 'BTC/USDT'

# Виставляємо навмисно невиконуваний лімітний ордер: ціна набагато нижча за ринкову
order = okx.create_order(
    symbol=symbol,
    type='limit',
    side='buy',
    amount=0.0001,     # кількість дуже мала, орієнтуйся на мінімальний обсяг
    price=20000,       # набагато нижче поточної ринкової ціни BTC, висить і не виконується
)
order_id = order['id']
print('Ордер виставлено, номер:', order_id)

time.sleep(2)

# Скасовуємо щойно виставлений ордер
canceled = okx.cancel_order(order_id, symbol)
print('Запит на скасування прийнято:', canceled['id'])

# У відповіді на скасування немає поля статусу — вона лише означає, що запит прийняли
time.sleep(1)
od = okx.fetch_order(order_id, symbol)
print(od['status'])  # скасування - це лише прийняття запиту; справжній кінцевий стан видно тут

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

Про amount (кількість): у кожної торгової пари є мінімальний обсяг і обмеження точності, надто мала кількість буде відхилена біржею. Якщо видає «кількість не відповідає правилам» — спершу подивись okx.load_markets() для цієї пари в полях limits і precision і впиши за мінімумом, який там вимагається.

Спершу демо: обкатуй на фейкових грошах

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

Демо в OKX зветься Demo Trading (демо-торгівля), перемкнутися в нього можна і в застосунку, і на вебсайті. Зверни увагу: у демо свій власний API-ключ — офіційна документація OKX веде так: окремий Demo Trading API Key створюють усередині демо-середовища, а не додають перемикач до реального ключа. Коли облікові дані замінено, щоб ccxt працював із демо, після ініціалізації увімкни перемикач sandbox:

import ccxt

# Увага: ці три — від ключа демо (Demo Trading), а не від реального
okx = ccxt.okx({
    'apiKey':   'демо_apiKey',
    'secret':   'демо_secret',
    'password': 'демо_Passphrase',
})

# Ключовий рядок: ccxt додасть до всіх наступних запитів заголовок демо
okx.set_sandbox_mode(True)

# Самоперевірка: цей рядок має надрукувати 1, інакше ти досі на реалі
print(okx.headers.get('x-simulated-trading'))

# Далі всі запити несуть позначку демо, на віртуальних коштах
balance = okx.fetch_balance()
print('USDT на демо доступно:', balance['USDT']['free'])

Не підміняй цей рядок записом sandboxMode у конфізі: заголовок демо додає сам метод set_sandbox_mode(), тож запис в options конструктора його не запускає, і запит однаково лягає на реал. Щойно той print видасть 1, ти зможеш спокійно ганяти той скрипт «ордер — скасування» хоч сто разів: навіть якщо помилково впишеш ціну біля ринкової й він реально виконається, витратиш лише віртуальні USDT.

Наша звичка така: будь-яку нову стратегію, будь-який змінений код спершу безперервно крутимо на демо достатній час, переконуємося, що колбек ордера, скасування й зміна балансу відповідають очікуванням, і лише тоді прибираємо рядок set_sandbox_mode(True), повертаємо облікові дані реального ключа й переходимо на реал, та й то перший раз — лише на дуже малу суму. Цей порядок не раз нас рятував: кілька логічних багів спливли ще на стадії демо, а якби одразу пішли на справжні гроші — ціною були б не лише гроші.

Підводні камені, на які найчастіше наступають

Це розділ, який варто зберегти найбільше. Кожен пункт нижче — помилка, на яку ми наступали самі або раз по раз бачили у спільнотах; звіривши, заощадиш собі кілька годин.

Passphrase пропущено / уписано неправильно (найчастіше)

Помилка зазвичай автентифікаційного типу (на кшталт «Invalid sign» чи «passphrase incorrect»). Перевір, чи в поле password у ccxt уписано саме той Passphrase, який ти задав при створенні ключа, а не пароль для входу й не secret. Тільки не гадай за враженнями: спершу витягни з помилки код. 50105 — це саме «Passphrase не той», а 50113 означає, що не пройшов сам підпис; шукати в цих випадках треба зовсім різні речі.

Помилка часової мітки / запит застарів

OKX має допуск на часову мітку запиту; якщо системний час на твоєму комп'ютері чи сервері неточний (розходження з часом сервера понад 30 секунд), запит буде відхилено через застарілу мітку (помилка 50102). Рішення — синхронізувати системний час із точним мережевим (увімкни автокорекцію через NTP). Хмарні сервери зазвичай мають це за замовчуванням, локальні машини інколи «пливуть».

Недостатньо прав

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

Спрацював ліміт частоти (Rate Limit)

Якщо в циклі шалено тягнеш котирування чи виставляєш/скасовуєш ордери, упрешся в обмеження частоти інтерфейсу й отримаєш щось на кшталт «Too Many Requests». Найпростіше рішення — увімкнути обмеження швидкості ccxt при ініціалізації: ccxt.okx({..., 'enableRateLimit': True}), він сам уставлятиме паузи між запитами. Не бий по інтерфейсу циклом while True без жодної затримки.

Помилка в symbol

Напишеш BTC/USDT як BTCUSDT, btc/usdt чи візьмеш ф'ючерсний формат для спотового ордера — отримаєш «торгова пара не існує». Запам'ятай: спот — це ВЕЛИКІ/ВЕЛИКІ зі слешем; не впевнений — спершу print(okx.load_markets().keys()) і подивись, які пари взагалі доступні.

IP не в білому списку

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

Ризик-менеджмент і настрій: квант ≠ гарантований прибуток

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

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

Тож кілька реальних порад тобі-початківцю:

• Спершу мала сума. Перший раз на реалі — сума, яку не шкода втратити повністю. Сприймай це як плату за навчання, а не як капітал.
• Постав ліміт позиції. Зашивай у скрипт ліміт на одну угоду й на всю позицію, не давай програмі шансу поставити на кін усі твої кошти.
• Залиш стоп-лос. Хоч якою гарною виглядає стратегія, дай їй чітку лінію стоп-лосу чи максимальної просадки — спрацювала, зупиняйся.
• З ф'ючерсами й плечем обережно. Ця стаття вся про спот. Ф'ючерси з плечем можуть обнулити капітал за лічені хвилини; на початковій стадії наполегливо радимо торгувати лише спотом, а вже потім, коли налагодиш процес і настрій, говорити далі.
• Поспостерігай, як він працює. Перші кілька днів роботи нової стратегії на реалі не кидай напризволяще — стеж, переконайся, що поведінка збігається з тим, що ти бачив на демо.

Поширені запитання

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