Какие задачи решает API V5 и когда нужен ключ?
Ключ нужен для запросов к вашему счёту. В документации V5 запросы разложены по разделам: рынок, торговля, позиции, счёт, активы, пользователь. Запрос времени из раздела рынка идёт без ключа и подписи. Запросы к счёту, заявкам и самому ключу подписываются.
Подписанный запрос несёт три обязательных заголовка: X-BAPI-API-KEY с ключом, X-BAPI-TIMESTAMP со временем в миллисекундах и X-BAPI-SIGN с подписью. Четвёртый, X-BAPI-RECV-WINDOW, задаёт, сколько запрос считается действительным, по умолчанию это 5000 мс. Ключ бывает двух видов. Обычный выдаёт биржа парой из ключа и секрета, подпись идёт по HMAC. Во втором варианте пару RSA вы создаёте сами и отдаёте бирже только публичную часть.
Здесь проходит граница, которую легко пропустить. Подключение по API ещё не торговля: это транспорт, по которому программа получает данные и может отправить заявку. Откуда берётся торговый сигнал и как проверить исполнение, разобрано в руководстве торговый бот: как работает и как проверить.
Как различать ключи mainnet, testnet и demo?
Ключ работает только в той среде, где создан, и только на её адресе. Типичная причина отказа при первом подключении - ключ от одной среды, а адрес от другой: биржа прямо просит это проверить в описании кода 10003. Там же упомянута четвёртая среда, демо внутри тестовой сети, но создавать в ней ключ документация не советует.
| Среда | Адрес REST | Где создают ключ |
|---|---|---|
| Mainnet, основная | api.bybit.com | сайт биржи, API Management |
| Testnet, тестовая | api-testnet.bybit.com | сайт тестовой сети |
| Demo, демо-счёт | api-demo.bybit.com | сайт биржи, режим Demo Trading |
Демо-счёт - отдельный счёт со своим ID, и набор методов у него неполный: рыночные запросы доступны все, а из остальных только часть. Для некоторых стран у основной площадки свой адрес, список есть в документации.
Создать ключ можно только на сайте, в приложении такого пункта нет. Новому аккаунту биржа может не дать этого сделать первые 48 часов после регистрации. При создании задают права. Для проверки подключения хватит ключа только для чтения, а право на вывод средств стороннему сервису не нужно: чем уже права, тем меньше риск при утечке ключа.
Срок действия смотрят у самого ключа. В его параметрах есть deadlineDay, остаток дней, и expiredAt, дата окончания. Документация оговаривает, что эти поля относятся к ключам без привязки к IP или к случаю, когда менялся пароль. Общий срок «на все ключи» из чужих инструкций переносить на свой ключ не стоит.
Как проверить подключение и понять ошибку?
Проверяют в два приёма: сначала связь без ключа, потом сам ключ запросом на чтение.
- Отправьте GET /v5/market/time на адрес своей среды. Параметров и ключа запрос не требует. В ответе должны прийти retCode 0 и два поля времени: timeSecond и timeNano.
- Сверьте это время с часами своего компьютера. Метка времени в подписанном запросе должна быть не старше окна recv_window. Опережать серверное время она может меньше чем на 1000 мс.
- Отправьте подписанный GET /v5/user/query-api. Он доступен ключу с любыми правами и возвращает параметры самого ключа: readOnly, список permissions, привязанные IP, срок.
- Сравните ответ с тем, что вы задавали при создании. readOnly 1 означает только чтение, 0 - чтение и запись.
Успешный первый шаг говорит только о том, что адрес доступен и биржа отвечает. Про ключ он ничего не доказывает, это проверяет третий шаг. Если на нём пришла ошибка, смотрите код в поле retCode.
| Код | Что пишет биржа | Что сверить |
|---|---|---|
| 10002 | время запроса вне допустимого окна | часы компьютера, синхронизацию времени |
| 10003 | ключ недействителен | совпадают ли ключ и адрес среды |
| 10004 | ошибка подписи | порядок строки для подписи и секрет |
| 10005 | доступ запрещён | права ключа |
| 10006 | превышен лимит запросов | частоту обращений |
| 10010 | IP не совпадает | список адресов, привязанных к ключу |
| 33004 | срок действия ключа истёк (код для деривативов) | дату в параметрах ключа |
Лимит запросов считается по каждому методу отдельно и на аккаунт, а сверху действует общий лимит по IP. Сам лимит биржа возвращает в заголовке ответа X-Bapi-Limit, остаток - в X-Bapi-Limit-Status, так что гадать не приходится.
Риски и ограничения. Ключ и секрет равны паролю: их не пересылают, не вставляют в чужие формы и не хранят в открытом виде. Поля и коды приведены по документации, живой запрос к бирже для этого разбора не отправлялся. Адреса, коды и правила биржа меняет, перед работой сверяйтесь с текущей документацией. Исправное подключение не гарантирует результата торговли: торговля связана с риском потери капитала. Материал образовательный, это не индивидуальная инвестиционная рекомендация.
Как биржа считает издержки сделки, отправленной по API, разобрано в ответе про комиссии Bybit на споте и фьючерсах.
Источники
- Документация Bybit V5: Integration Guidance - адреса сред, заголовки подписи, окно времени, общий формат ответа.
- Get Bybit Server Time - публичный запрос времени сервера и его поля.
- Demo Trading Service - отдельный учебный счёт, его адрес и доступные методы.
- Параметры ключа: Get API Key Information - права, привязка к IP и срок действия.
- Error Codes - коды ошибок и их описания.
- Rate Limit Rules - как считается лимит и какие заголовки его показывают.
- Справка Bybit: How to Create Your API Key - где создают ключ и ограничение для новых аккаунтов.
