Как начать работу с Python SDK для Hyperliquid

Что вы на самом деле настраиваете

Три вещи, и их стоит назвать до того, как трогать терминал, потому что путаница между ними и есть вся сложность.

Ваш основной кошелёк — это счёт. Он держит средства, и именно на этот адрес всё записывается.

API-кошелёк — это агент, которого счёт уполномочивает. Он подписывает ордера. Выводить средства он не может.

SDK — это обёртка на Python вокруг подписанного HTTP-интерфейса. Он не делает ничего, чего нельзя было бы сделать через requests и библиотеку подписи; он лишь избавляет вас от реализации схемы подписи.

Установка и настройка

1. Установите пакет

   pip install hyperliquid-python-sdk. Это эталонная реализация, поддерживаемая в организации hyperliquid-dex на GitHub.

   Вы должны увидеть hyperliquid-python-sdk доступен в вашем окружении

2. Создайте API-кошелёк в приложении

   Делайте так, а не кладите в файл приватный ключ основного кошелька. Агент может торговать и не может выводить, поэтому худший случай при утечке файла ограничен.

   Одобрение агента — действие в сети, подписанное вашим основным кошельком, ровно как шаг Establish Connection при первом подключении.

   Вы должны увидеть приватный ключ агента, уполномоченного на вашем счёте

3. Заполните конфиг двумя разными адресами

   secret_key — приватный ключ API-кошелька. account_address — публичный ключ вашего основного кошелька.

   Эта асимметрия является самой частой причиной провала первой попытки, и README обращает на неё внимание отдельно по той же причине.

   Вы должны увидеть конфиг, которым SDK может и подписывать, и запрашивать

4. Прочитайте что-нибудь до того, как что-то писать

   Создайте Info и запросите средние цены или стакан. Подпись здесь не нужна вообще, поэтому если сработало, то и сетевой путь, и выбор эндпоинта у вас в порядке, а любой последующий сбой является проблемой подписи, а не связности.

   Вы должны увидеть живые рыночные данные, напечатанные из информационного эндпоинта

5. Поставьте один маленький ордер через Exchange

   Проверяйте в самом приложении, что он дошёл. Момент, когда вы видите собственный программный ордер в интерфейсе, и есть момент, когда настройка действительно проверена.

   Вы должны увидеть ордер, видимый в панели открытых ордеров приложения

Два класса

Info — сторона чтения. Метаданные рынков, средние цены, стаканы, свечи, позиции и исполнения адреса. Ключ не нужен. Создаётся с URL API и, если WebSocket не нужен, с skip_ws=True.

Exchange — сторона записи. Ордера, отмены, смена плеча, переводы. Каждый запрос подписывается настроенным вами ключом.

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

Что ломается на первой попытке

Пустые данные на любой запрос. В account_address стоит адрес API-кошелька, а не мастера. Запрашивайте по мастер-адресу; подписывайте агентом.

Ордера отклоняются по размеру. Ниже минимального номинала в $10.00 либо без выравнивания по шагу цены и лота этого рынка. И то, и другое берётся из метаданных рынка, а не является глобальным.

Быстро прилетает ограничение частоты. Обычно это цикл опроса стакана. Вместо него подпишитесь через WebSocket. Лимиты и почему они устроены именно так.

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

Всё работало, а после передеплоя перестало. Снятый с регистрации агент, чей адрес вы переиспользовали. Создайте нового: документация предупреждает, что очищенное состояние нонсов делает переиспользование риском повторного воспроизведения.

От работающего кода к работающей стратегии

SDK доводит вас до поставленного ордера за вечер. Расстояние оттуда до чего-то, что стоит запускать, — по большей части не код.

Дисциплина типов ордеров. Используйте post-only, когда намерены быть мейкером, и reduce-only на каждом выходе. И то, и другое предотвращает целые классы дорогих случайностей, и каждое является одним флагом. Полный список.

Считайте размер от стакана, а не от баланса. Стратегия, игнорирующая глубину, платит проскальзывание, многократно превышающее разницу в комиссиях, которую она оптимизировала.

Решите, что происходит, когда процесс умирает. Стоящие ордера продолжают работать без вас. Это либо свойство, либо опасность, и это должно быть решением.

Запуск бота и о чём подумать в первую очередь покрывает остаток этого списка.

Куда дальше

Сам API — эндпоинты, модель агента и лимиты — и типы ордеров, которые вы будете через него отправлять.