Зміст

  • Вступ

  • Передумови

    • Ключі тестової мережі

    • Завантаження і встановлення Postman

  • Створення середовища

  • Імпорт колекції

  • Виконання запитів

  • Заключні думки


Вступ

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

Мета цієї серії – познайомити вас з REST API Binance і навчити, як з ним взаємодіяти. В кінці, ви повинні бути впевнені в своїй здатності запитувати інформацію про ринки та ваші позиції, і розміщувати ряд різних типів ордерів.

У цій статті ми будемо використовувати Postman для зв'язку з біржею. Не хвилюйтеся – ми не будемо піддавати ризику реальні гроші.


Передумови

Ключі тестової мережі

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


  1. Почніть з переходу до Спотової тестової мережі.

  2. Щоб отримати доступ, вам необхідно увійти в систему з акаунтом GitHub. Створіть його, якщо ви цього ще не зробили.

  3. Натисніть "Authenticate" та увійдіть через GitHub.

  4. У розділі "API Keys", ви побачите, що у вас немає зареєстрованих ключів. Натисніть на Generate HMAC_SHA256 Key, щоб створити пару.

  5. На наступному екрані, надайте клавішам мітку. Назвіть їх як хочете і натисніть "Generate". 

  6. Вам будуть представлені два ключа: API Key та Secret Key. Важливо записати їх зараз. Якщо ви цього не зробите, вам доведеться знову розпочати процес створення ключа. Ми рекомендуємо зберігати їх в додатку для нотаток на вашому комп'ютері, щоб потім їх було легко скопіювати.

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


Завантаження і встановлення Postman

Postman – це платформа для спільної роботи API. Для нас це ідеальна відправна точка – у нас буде доступ до колекцій запитів Binance, які ми будемо тестувати, не створюючи жодного рядка коду.

Програма доступна для Mac, Windows та Linux. Перейдіть на сторінку Завантажування і завантажте файл .zip.

Після цього, знайдіть його у провіднику і встановіть. Відкрийте програму для початку роботи. Зверніть увагу, що ви можете створити акаунт для входу, але це не обов'язково. Якщо ви хочете пропустити цей крок, просто виберіть відповідний варіант у нижній частині вікна.


Створення середовища

На цьому етапі у вас повинен бути інтерфейс, схожий на наступний.



Спочатку, треба створити середовище. Це просто спосіб додати змінні до набору запитів, з якими ми збираємося працювати. Для цього нам спочатку потрібно отримати деяку інформацію з репозиторію Binance GitHub. Перейдіть сюди і завантажте файл .zip.



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



Натисніть значок шестерні у правому верхньому куті (як показано вище). Ви побачите спливаюче вікно "Manage Environments". 

  1. Виберіть "Import", і перейдіть в щойно розархівовану папку (binance-postman-api). 

  2. Потім увійдіть у папку середовища .

  3. Тепер ви побачите два файли (один для основної мережі, інший для тестової мережі). Ми шукаємо binance_com_spot_testnet_api.postman_environment.json. Переконайтеся, що ви вибрали правильний, тому що наші ключі не працюють з іншими.



Майже готово. Натисніть на "Binance Spot Testnet API", і ви побачите змінні нижче. Відредагуйте два параметра, виділених червоним, вставивши ключі, які ви зберегли раніше. Натисніть "Update" та вийдіть із спливаючого вікна.



На цьому екрані залиште поля "timestamp" і "signature" порожніми. Ці два значення будуть автоматично створюватися при кожному запиті.

Залишилося зробити ще дещо. Праворуч від іконки шестірні, яку ми натиснули, щоб налаштувати середовище раніше, ви побачите випадаюче меню, в якому наразі написано "No Environment". Натисніть на нього і виберіть "Binance Spot Testnet API".


Імпорт колекції

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

  1. Натисніть "Import" у верхньому лівому куті.

  2. У спливаючому вікні на вкладці "File" виберіть "Upload Files".

  3. Ми знову шукаємо папку binance-postman-api. Знайдіть і відкрийте її.

  4. На цей раз введіть "collections" у підкаталог.

  5. Тут знову два файли. Один для роботи з API ф'ючерсів. Але ми працюємо зі спотовим, тому вам потрібно вибрати файл binance_spot_api_v1.postman_collection.json.

  6. Тепер ви повинні побачити екран підтвердження, який ідентифікує імпорт у форматі колекції Postman. Виберіть "Import".

На вкладці "Collections" зліва від вікна ви тепер помітите, що у нас є папка з більш ніж 100 запитами. Вітаємо! Все гаразд. У наступному розділі ми розглянемо, які запити ми можемо відправляти.


Виконання запитів

Якщо ви розгорнете папки на вкладці "Collections" , ви побачите, що у нас є безліч різних запитів, які ми можемо зробити. За кольором кодування, ви можете помітити, що ми можемо використовувати три типи методів :


  • GET: Метод "GET" використовується для отримання даних із сервера. Ми будемо використовувати його, щоб дізнатися інформацію про баланс вашого акаунта, ціни на активи і т.д.

  • POST: Зазвичай ми використовуємо метод "POST" для створення інформації на сервері. Це необхідно для таких речей, як розміщення ордерів, запит на зняття коштів і т.д.

  • DELETE: Метод "DELETE" – це запит до сервера на видалення інформації. Він стане в нагоді для скасування ордерів.


Пошук списку символів і правил торгівлі

Час для нашого першого запиту! Ми збираємося отримати символи, якими можна торгувати на біржі, і правила торгівлі:

GET /exchangeInfo


Цей запит не приймає жодних додаткових параметрів – ви можете скопіювати і вставити його в адресний рядок, та отримаєте відповідь. У Postman легше переглядати та змінювати запити, в які ми включаємо кілька параметрів.

Щоб завантажити цей запит, виберіть "Market" > "Exchange Information". З'явиться наступна вкладка:



Тут нам більше нічого робити не потрібно, тому натискайте "Send". Ви отримаєте відповідь:



У самому верхньому виділеному розділі, ви побачите важливу інформацію:

  • статус відповіді (200 означає, що запит успішний, 400-499 означає, що у нас виникла проблема)

  • час, необхідний для отримання відповіді (менше секунди)

  • розмір відповіді (~22КБ).


У другому полі – основна частина відповіді. Вона красиво надрукована, щоб було трохи легше для очей. Вона містить інформацію про саму біржу, а також про пари, якими ви можете торгувати, і їх мінімальні/максимальні суми.

Схоже, що інформації багато, але формат дозволяє легко працювати з нею програмно. При написанні скриптів для взаємодії, ви легко зможете вибрати певні властивості певних елементів з відповіді.


Перевірка балансу акаунта

Давайте перевіримо, які активи у нас є і скільки їх:

GET /account

Цей запит можна знайти у розділі "Trade" > "Account Information". Натисніть на нього, і ви побачите макет, схожий на попередній. Однак ви також помітите, що у нас є дві нові змінні: "timestamp" та "signature". Signature (підпис) – міра безпеки. Оскільки зараз ми запитуємо конфіденційну інформацію, це доведе, що ми є власником акаунта. 

Timestamp (мітка часу) повідомляє серверу, коли запит був відправлений. Оскільки мережі можуть бути ненадійними або мати простої, сервер може отримати наш запит набагато пізніше, ніж передбачалося. Якщо пройшло занадто багато часу, він відхилить запит. Ви можете вказати, як довго ви хочете чекати, за допомогою параметра "recvWindow", який за замовчуванням рівний 5 000 мілісекунд.

Postman обробляє за нас створення обох цих полів. Натисніть "Send", і ви отримаєте відповідь. Під балансами ви повинні побачити шість активів – BNB, BTC, BUSD, ETH, LTC і TRX. Баланс буде розділений на free (вільний) і locked (заблокований). Ми ще нічого не заблокували, тому всі ваші активи повинні бути вільні.

Вітаємо з новим (неіснуючим) багатством!


Як дізнатися поточну ціну символу

Ми можемо отримати поточну ціну активу різними способами. Можливо, найпростіший – з таким запитом:

GET /api/v3/ticker/24hr

Як ви могли здогадатися, це дасть нам інформацію про ціни на активи за останню добу. Знайдіть його у "Market" > "24hr Ticker Price Change Statistic"s. Пара за замовчуванням, яку ми бачимо як змінну символу – BTCUSDT. 

Ви можете відправити його прямо зараз, щоб побачити розбивку інформації про ціни. Ви також можете змінити символ (на BNBBUSD, LTCUSDT, і т.д.), або ви можете зняти прапорець зі змінною, щоб повертати дані для 40 пар.

У нас також є більш простий виклик ("Market" > "Symbol Price Ticker"), який повертає поточну ціну, по якій торгується актив:

GET /api/v3/price

Як і в попередньому випадку, ви можете змінити змінну символу або повністю видалити її, та отримати останню ціну для всіх символів.


Перевірка поточної глибини книги ордерів

Глибина книги ордерів (також називається глибина ринку або DOM) може багато розповісти нам про ринок. Ми збираємося здійснити виклик, щоб повернути корисну інформацію:

GET api/v3/depth

Коли ми відправляємо його зі значеннями за замовчуванням ("Market" > "Order Book"), ми отримуємо відповідь, в якій повідомляється про бід та аск для BTCUSDT. Сервер тестової мережі не видасть стільки даних, скільки фактичний, тому нижче наведено знімок екрана того, що ви очікуєте побачити в реальному середовищі:



У виділеному вище розділі ми бачимо перший бід. Оскільки ми дивимося на книгу для BTCUSDT, верхнє число – це ціна, яку хтось готовий заплатити за ваш BTC. Нижче вказана сума, яку вони готові купити. Таким чином, це говорить про те, що цей ордер запитує 0,999 BTC за курсом 9 704,65 USDT за BTC. Якби ми продовжили прокрутку вниз, то побачили б зниження ціни пропозиції – це означає, що покупцю будуть платити менше. 

Краща пропозиція, природно, буде найпривабливішою, якщо ви хочете отримати прибуток. Проте, якщо ви намагаєтеся продати по ринку, скажімо, 3 BTC, ви зможете продати тільки 0,999 BTC за найкращою ціною. Вам потрібно буде приймати подальші (дешевші) пропозиції, поки ваш ордер не буде виконаний повністю.



Продовжуйте прокручувати, і ви побачите аск. Функціонально вони схожі на бід, за винятком того, що являють собою ордери на продаж BTC за USDT. 


Розміщення тестового ордера

Тепер ми розмістимо тестовий ордер.

POST api/v3/order/test

Незважаючи на те, що ми просто використовуємо кошти тестової мережі, цей запит насправді не призведе до розміщення ордера. Це може стати в нагоді для тестування ордерів перед їх відправкою. Знайдіть його у розділі "Trade" > "Test New Order (TRADE)".



Як бачите, у нас задіяно ще більше параметрів. Давайте пройдемося по відміченим:


  • symbol - ми вже зустрічалися з цим раніше. Це пара, якою ви хочете торгувати.

  • side – тут ви вказуєте, чи хочете ви КУПУВАТИ або ПРОДАВАТИ. Для пари BTCUSDT, BUY вказує, що ви хочете купити BTC за USDT, тоді як SELL буде продавати BTC за USDT.

  • type – тип ордера, який ви хочете надіслати. Можливі значення (детально тут):

    • LIMIT

    • MARKET

    • STOP_LOSS

    • STOP_LOSS_LIMIT

    • TAKE_PROFIT

    • TAKE_PROFIT_LIMIT

    • LIMIT_MAKER

  • timeInForce– цей параметр виражає те, як ви хочете, щоб ордер виконувався:

    • GTC (Діє до відміни) – можливо, це найпопулярніше налаштування. GTC гарантує, що ваш ордер дійсний до тих пір, поки він не буде виконаний або поки ви його не скасуєте.

    • FOK (Виконати або Анулювати) – ФОК дає вказівку біржі виконати ордер відразу. Якщо біржа не може зробити цього, ордер негайно анулюється.

    • IOC (виконати відразу або скасувати) – ордер повинен бути виконаний повністю або частково негайно, або він буде скасований. На відміну від FOK, ордери не скасовуються, якщо вони можуть бути частково виконані.

  • quantity – просто кількість активу, який ви хочете купити або продати.

  • price – ціна, по якій ви хочете продати. Для пари BTCUSDT це виражається в USDT.

  • newClientOrderId – ідентифікатор ордера. Це не обов'язкове поле, але ви можете встановити в ньому ідентифікатор, який спростить запит пізніше. В іншому випадку він генерується випадковим чином на біржі.

Добре! Тепер створимо тестовий ордер. Ми збираємося використовувати автоматично згенеровані значення: лімітний ордер на продаж 0,1 BTC за USDT за ціною 9 000$. Натисніть "Send". Якщо все було успішно, ми просто отримаємо {{}} як відповідь. 

 

Розміщення реального ордера

Час розмістити справжній фейковий ордер. 

POST /api/v3/order

Перейдіть у "Trade" > "New Order". Ви вже знайомі з тестовими ордерами, тому параметри тут не здивують. Давайте залишимо все значення як є, але змінимо ціну, по якій ми продаємо, на 40 000$. Змініть значення ціни, щоб відобразити це. Потім натисніть "Send".

У разі успіху, ваша відповідь містить детальну інформацію щодо ордера. 


Перевірка статуса відкритого ордера

Ми отримали підтвердження, що ордер було розміщено у попередньому розділі, але що, якщо ми захочемо перевірити його пізніше? У нашому розпорядженні є кілька запитів.

GET /api/v3/openOrders

Ви знайдете його у розділі "Trade" > "Current Open Orders (USER_DATA)". BTCUSDT обрана за замовчуванням. Якщо ви натиснете "Send", ви отримаєте всі свої відкриті ордери BTCUSDT (поки ви повинні бачити тільки той, який ми встановили раніше). Ви можете не вказувати символ, який замість цього поверне всі ваші відкриті ордери.

GET /api/v3/allOrders

"Trade" > "All Orders (USER_DATA)" дає вам огляд всіх ордерів, а не тільки відкритих. Тут ви повинні вказати символ. "orderId", "startTime", "endTime" – необов'язкові параметри, які можуть допомогти вам уточнити пошук. Ми залишимо їх тут, тому зніміть галочки. Натисніть "Send", і ви побачите ту саму відповідь, що і раніше. Якщо у вас були закриті або скасовані ордери, ви також побачите їх тут. 


І нарешті, ми можемо запитувати конкретні ордери за допомогою:

GET /api/v3/order

Отримайте його у розділі "Trade" > "Query Order (USER_DATA)". Вам потрібно буде вказати або "orderId", або "origClientOrderId" (необов'язковий тег "newClientOrderId", який можна додати до ордерів). Зніміть галочку "orderId". Для "origClientOrderId" ми збираємося надати тег за замовчуванням, який використовувався раніше – "my_order_id_1". Заповніть поле і натисніть "Send", щоб отримати відповідь.


Скасування ордера

Через деякий час ми можемо вирішити, що ціль у 40 000$ є занадто оптимістичною, тому ми хочемо скасувати ордер. В цьому випадку ми б використовували:

DELETE /api/v3/order

У розділі "Trade" > "Cancel Order", запит, який дозволить нам виділити ордери для скасування. Зніміть галочку з "orderId" і "newClientOrderId" і передайте "my_order_id_1" як значення для "origClientOrderId".

Коли ви надішлете цей запит, ордер буде повернуто. Якщо ви прокрутите вниз до "status", ви побачите, що він дійсно скасований. Щоб підтвердити це, знову використовуйте кінцеву точку GET /api/v3/openOrders (з порожнім списком) або GET /api/v3/order з origClientOrderId.


Розмізення ордера, який заповнюється миттєво

Наш попередній ордер не було виконано, тому що це був лімітний ордер, який спрацює тільки тоді, коли ціна BTC досягне 40 000$. У разі маркет ордера ми, по суті, говоримо "купіть/продайте по будь-якій ціні, по якій актив зараз торгується". Цей ордер заповниться миттєво.

Для цього повернемося до "Trade" > "New Order". Ми збираємося продемонструвати тип відповіді (newOrderRespType), який є параметром, який ми можемо налаштувати в залежності від відповіді, яку ми хочемо отримати від сервера. Тут є три варіанти: ACK, RESULT, або FULL – ви можете побачити приклади кожної відповіді тут. Ми збираємося використовувати "ACK", який дасть нам просте підтвердження того, що ордер було отримано.

Нижче ви можете побачити, що ми збираємося відправити маркет ордер на продаж BNB за BUSD за поточною ринковою ціною.



Зверніть увагу, що відповідь дає нам мінімальну інформацію:



Ви можете переконатися, що ордер був заповнений через кінцеву точку /api/v3/allOrders.


Перевірка ваших угод

Нарешті, давайте подивимося на кінцеву точку для перевірки ваших угод:

GET /api/v3/myTrades

Запит знаходиться у розділі "Trade" > "Account Trade List (USER_DATA)". Він дозволяє вам перевіряти кожну угоду по певному символу. Якщо ви хочете бачити всі свої угоди для символу за замовчуванням (BTCUSDT), просто зніміть прапорець "startTime", "endTime" та "fromId". Відповідь поверне до 500 угод – просто змініть ліміт, якщо хочете побачити більше.


Налагодження з Postman

У Postman, можна додатково розкрити необроблений HTTP-запит і відповідь.



Це меню відкриє консоль Postman, яке показує деталі кожного запиту.



Заключні думки

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

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

У вас є ще запитання? Відвідайте наш зростаючий форум спільноти розробників Binance, або ознайомтеся з документацією.