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

Публичные цены можно получить без ключа через POST /info; поток сделок и книги — через WebSocket; размещение ордера относится к подписанным действиям POST /exchange. Разделите эти три задачи до выбора SDK: так вы не дадите торговому ключу больше полномочий, чем требуется приложению.

Карта Hyperliquid API#

Mainnet REST API работает на https://api.hyperliquid.xyz. Для тестовой сети используется соответствующий домен api.hyperliquid-testnet.xyz. WebSocket mainnet находится по адресу wss://api.hyperliquid.xyz/ws.

У API есть два основных HTTP-направления:

• info endpoint возвращает рынки, книги, свечи, состояния аккаунта, исполнения и другие данные;
• exchange endpoint принимает подписанные действия: ордера, отмены, переводы и настройки аккаунта.

WebSocket нужен, когда периодический HTTP-опрос создаёт задержку и лишний расход лимита. Он отдаёт snapshot при подписке, затем присылает обновления соответствующего канала.

Начинайте разработку с testnet и публичного запроса. Подписание и отправку ордеров добавляйте после того, как логирование, повторы и обработка ошибок уже работают без секретов.

Публичные запросы к info endpoint#

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

Публичность endpoint не отменяет проверку входных данных. Символ рынка, интервал свечи и адрес пользователя должны приходить из разрешённого формата, а ответ API — проходить runtime-валидацию до использования в расчёте.

Для интерфейса цены полезно хранить три состояния: последнее корректное значение, время его получения и признак ошибки. При сбое не заменяйте цену нулём — это выглядит как реальный market data и может привести к неверному решению пользователя.

WebSocket для книги и сделок#

После подключения клиент отправляет сообщение subscribe с объектом subscription. Для потока сделок указываются type: "trades" и символ coin; для книги — type: "l2Book". Первый пакет некоторых пользовательских каналов содержит snapshot, последующие — изменения.

Документация предупреждает о периодических разрывах со стороны сервера. Клиент должен:

1. обнаружить закрытие соединения;
2. повторно подключиться с backoff;
3. восстановить подписки;
4. обработать новый snapshot;
5. при необходимости запросить пропущенный интервал через HTTP.

Соединение без сообщений закрывается через 60 секунд. Для тихого канала отправляйте документированный ping и ожидайте pong, а не создавайте бесконечный цикл переподключений.

Подписанные exchange-действия#

Ордер — это не обычный публичный POST. Действие формируется с параметрами рынка, стороны, цены, размера и типа исполнения, подписывается локально и отправляется вместе с nonce и signature.

Nonce должен быть монотонным для подписывающего адреса. Повтор запроса после timeout требует особой осторожности: сервер мог принять действие, даже если клиент не получил ответ. Перед повторным ордером запросите состояние или используйте client order id, чтобы сопоставить результат.

Для автоматизации лучше создать отдельный API wallet в механике, поддерживаемой Hyperliquid, вместо использования основного приватного ключа в каждом процессе. Отдельно предусмотрите аварийную отмену ордеров и способ быстро отозвать доступ.

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

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

Типовой безопасный порядок разработки:

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

   Проверьте URL сети и выполните публичный запрос без ключей.

2. 02
   Добавьте отдельный API wallet

   Храните секрет вне кода и выдайте процессу только необходимое назначение.

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

   Сверьте округление цены и размера с требованиями конкретного рынка.

4. 04
   Проверьте отмену и восстановление

   Бот должен корректно пережить timeout, reconnect и частично выполненный ордер.

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

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

IP-лимит считается не простым количеством HTTP-вызовов, а суммарным весом. Документация указывает базовый бюджет 1200 weight в минуту: разные info-типы расходуют разный вес, а explorer-запросы заметно тяжелее обычных.

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

Не запускайте одинаковый polling в каждом компоненте. Один серверный сборщик или общий WebSocket-поток может раздавать нормализованные данные нескольким частям приложения и существенно уменьшить нагрузку.

Ошибки, timeout и идемпотентность#

Разделяйте ошибки транспорта и ответ протокола. HTTP 429 означает ограничение частоты, timeout не сообщает, было ли действие принято, а отклонённый ордер обычно содержит причину, которую стоит сохранить без секретных полей.

Retry допустим для публичного чтения с backoff и jitter. Для торгового действия автоматический повтор без проверки состояния может удвоить позицию. Сначала запросите order status или fills, затем принимайте решение.

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

Безопасность ключей и процесса#

Храните секреты в предназначенном для этого хранилище, регулярно обновляйте зависимости и фиксируйте версии SDK. Используйте testnet для изменения схемы подписи или нового типа ордера. При проблеме сначала сравните payload с официальной документацией API, затем переходите к диагностике ошибок Hyperliquid.