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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Читання: дивитися котирування, баланс, ордери. Найнижчий ризик.
• Торгівля: виставляти, скасовувати, змінювати ордери. Обов'язково для стратегій.
• Виведення: переказувати монети з рахунку.

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

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

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

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

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

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

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

Цей фрагмент виставить навмисно невиконуваний дешевий лімітний ордер на купівлю, а отримавши номер ордера — одразу скасує його. Обов'язково спершу запусти на демо (як під'єднатися до демо — наступний розділ):

import ccxt, time

okx = ccxt.okx({
    'apiKey':   'твій_apiKey',
    'secret':   'твій_secret',
    'password': 'твій_Passphrase',
})

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'])

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

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

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

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

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

import ccxt

okx = ccxt.okx({
    'apiKey':   'твій_apiKey',
    'secret':   'твій_secret',
    'password': 'твій_Passphrase',
})

# Ключовий рядок: перемикаємося на демо (Demo Trading)
okx.set_sandbox_mode(True)

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

Деякі версії підтримують також запис у конфізі 'options': {'sandboxMode': True} — ефект той самий, обирай те, що працює в тебе. Перемкнувшись на демо, ти зможеш спокійно ганяти той скрипт «ордер — скасування» хоч сто разів: навіть якщо помилково впишеш ціну біля ринкової й він реально виконається, витратиш лише віртуальні USDT.

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

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

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

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

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

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

OKX має допуск на часову мітку запиту; якщо системний час на твоєму комп'ютері чи сервері неточний (відхилення більше за кілька десятків секунд), підпис буде відхилено через застарілу мітку. Рішення — синхронізувати системний час із точним мережевим (увімкни автокорекцію через 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, далі тобі, мабуть, захочеться взяти конкретну стратегію для практики. Радимо почати з найзрозумілішого — бота-сітки, або ж спершу маленькими інструментами порахувати параметри й комісії, а потім братися до справи. Хоч яким шляхом підеш, пам'ятай порядок сьогоднішньої статті: спершу демо, потім реал на малій сумі, спершу вижити, а вже потім говорити про прибуток.