Как работать с Hyperliquid API

Hyperliquid API даёт доступ к рыночным данным, книге ордеров, истории аккаунта и торговым действиям. Для цен и стакана используйте публичный info endpoint или WebSocket. Для размещения и отмены ордеров — подписанные exchange-действия через отдельный API wallet.

Выберите API под задачу#

У интеграции три основных режима:

1. Публичные REST-запросы — снимки цен, книги, свечей, метаданных и состояния публичного адреса.
2. WebSocket — поток сделок, стакана, свечей, ордеров и событий аккаунта в реальном времени.
3. Подписанные действия — размещение и отмена ордеров, переводы и настройки торгового аккаунта.

Mainnet использует адрес api.hyperliquid.xyz, тестовая сеть — api.hyperliquid-testnet.xyz. Начните с testnet и публичного запроса, затем добавьте подписанные действия, когда обработка ответов и ошибок уже работает.

Публичные данные через info endpoint#

Запрос POST к пути /info принимает JSON с полем type. Значение allMids возвращает средние цены, l2Book — снимок книги ордеров, candleSnapshot — свечи, clearinghouseState — состояние perpetual-аккаунта указанного публичного адреса.

Для market data приватный ключ не нужен. Валидируйте символ, интервал и структуру ответа до передачи в расчёт. Если API временно недоступен, сохраняйте последнее корректное значение и время получения вместо подстановки нуля.

Запросы диапазона возвращают ограниченное число элементов. Для длинной истории используйте пагинацию по последнему timestamp, чтобы не пропустить и не продублировать данные.

WebSocket для стакана и сделок#

Mainnet WebSocket работает по адресу wss://api.hyperliquid.xyz/ws. После подключения отправьте subscribe с нужным типом канала: trades для сделок, l2Book для книги, candle для свечей, orderUpdates для ордеров аккаунта.

Некоторые каналы сначала присылают snapshot, а затем поток изменений. При повторном подключении обработайте новый snapshot, восстановите подписки и только после этого продолжайте обновлять локальное состояние.

Сервер может закрывать соединение. Для устойчивого клиента:

1. Обнаруживайте разрыв.
2. Подключайтесь заново с растущей паузой.
3. Восстанавливайте подписки.
4. Обрабатывайте новый snapshot.
5. Запрашивайте пропущенный интервал через REST, если он нужен.

Для тихого канала отправляйте документированный ping: соединение без сообщений закрывается после указанного в документации времени.

Как отправляются торговые действия#

Ордер формируется из рынка, стороны, цены, размера и типа исполнения, затем подписывается локально и отправляется в /exchange вместе с nonce. Ответ сообщает, осталась ли заявка в книге, исполнилась или была отклонена.

Используйте отдельный API wallet, а не основной приватный ключ в каждом процессе. Секрет хранится только там, где выполняется подпись. Клиентский интерфейс получает уже готовый результат или ограниченный серверный метод.

Timeout не означает, что ордер не был принят. Перед повтором запросите order status или fills. Client order id помогает связать отправку с фактической заявкой и не создать вторую позицию из-за автоматического retry.

Официальный Python SDK#

Документация ссылается на hyperliquid-python-sdk в GitHub-организации hyperliquid-dex. SDK реализует сериализацию, подписи и основные вызовы API, поэтому это удобная отправная точка для Python.

1. 01
   Подключите testnet

   Выполните публичный info-запрос и проверьте формат ответа без ключей.

2. 02
   Создайте отдельный API wallet

   Храните секрет вне кода и используйте его только в процессе подписи.

3. 03
   Отправьте небольшой тестовый ордер

   Проверьте округление цены и размера для конкретного рынка.

4. 04
   Отмените ордер

   Убедитесь, что отмена, status и fills корректно связаны с идентификатором.

5. 05
   Проверьте восстановление

   Перезапустите процесс и восстановите состояние без повторного ордера.

Для TypeScript есть сторонние библиотеки, а CCXT предоставляет общий интерфейс нескольких бирж. Сверяйте их версию, модель подписи и поддержку нужных методов с официальной документацией.

Rate limits и вес запросов#

Официальная документация указывает совокупный IP-лимит REST API 1200 weight в минуту. Разные типы запросов расходуют разный вес: часть info-запросов стоит 2, обычные — 20, userRole — 60, explorer-запросы — 40.

Для WebSocket действуют отдельные пределы на количество соединений, подписок и отправленных сообщений. Используйте один общий поток данных для нескольких частей приложения вместо одинакового polling в каждом модуле.

Торговые действия также имеют адресный лимит, связанный с накопленным объёмом, и стартовый буфер для нового адреса. Отмены сохраняют отдельный запас, чтобы открытые заявки можно было снять после достижения обычного предела.

Как обрабатывать ошибки и повторы#

HTTP 429 означает превышение лимита. Ошибка 422 указывает на параметры запроса. Ответ 5xx или сетевой timeout относится к транспорту и не всегда сообщает, было ли торговое действие принято.

Для чтения повторяйте запрос с увеличивающейся паузой и случайным интервалом. Для ордера сначала проверьте status, open orders и fills, затем решайте, нужен ли повтор.

Логируйте время, сеть, endpoint, безопасный request id, статус и длительность. Не записывайте приватный ключ, полную подпись, код email или персональные данные.

Ограничьте торговый процесс#

Торговый бот действует быстрее человека, поэтому ограничения должны находиться в коде до первого mainnet-ордера:

• максимальный размер одного ордера;
• максимальная общая позиция;
• число повторов;
• список разрешённых рынков;
• аварийная отмена открытых заявок;
• проверка фактического состояния после reconnect.

Обновляйте зависимости, фиксируйте версии SDK и используйте testnet для нового типа действия. Затем откройте официальную документацию API и сравните актуальные схемы запросов перед переносом интеграции в mainnet.