Python SDK: получить рынок, отправить ордер и проверить статус

Что должна уметь система

Материал для трейдеров и разработчиков, которые пишут собственную автоматизацию на Hyperliquid: понимают perpetual, funding, margin tier и работали с REST/WebSocket API других бирж. Полезен тем, кто переходит от ручной торговли через интерфейс к скриптам на официальном Python SDK и хочет избежать типовых ошибок с адресами, asset ID и статусом ордера.

Какую задачу решает связка info + exchange endpoint

Задача бота на Hyperliquid проста по формулировке: узнать контекст рынка, отправить ордер и убедиться, что он исполнился так, как задумано. За этим стоят два endpoint с разными требованиями к подписи и адресам. Info endpoint отдаёт через POST /info как публичную metadata рынков, так и приватные данные аккаунта — но структура и требования к идентификации у этих двух типов запросов различаются.

Exchange endpoint принимает подписанные actions — это единственный способ отправить ордер. WebSocket-подписки на книгу, trades, candles и user fills полезны для мониторинга, но клиент сам обрабатывает reconnect, повторную подписку и проверку свежести данных — это отдельная задача от подтверждения статуса ордера через info endpoint, о которой подробнее ниже в разделе про сценарий.

Механика получения рыночного контекста

Для полного контекста рынка используется метод metaAndAssetCtxs. Он возвращает universe — список активов, и параллельный массив contexts с mark price, oracle price, open interest, funding и volume. Сопоставление между universe и contexts происходит строго по позиции в массиве, а не по тикеру или id. Если отфильтровать или отсортировать один из массивов до объединения в пары, привязка ломается: funding одного актива окажется рядом с oracle price другого.

На HIP-3 рынках добавляется ещё один слой: один тикер на разных deployer DEX — это разные order books со своим oracle и margin table. Перед чтением contexts нужно понимать, к какому DEX namespace относится актив, иначе можно свериться с чужим margin tier или oracle. Deployer actions на HIP-3 — регистрация актива, обновления oracle, funding multipliers, haltTrading, margin tables и OI caps — задаются отдельно для каждого DEX и не переносятся с других perpetual рынков платформы.

Разделение ключа подписи и адреса чтения

Hyperliquid разделяет роль подписи и роль хранения через связку master/subaccount address и agent wallet (API wallet). Agent подписывает actions от имени master или subaccount, но не подходит как адрес для чтения account state — запрос позиций или баланса через agent в info endpoint часто возвращает пустой результат.

При этом ограничение ущерба конкретное: agent wallet не может инициировать вывод средств. Если ключ agent скомпрометирован, атакующий может отправлять и отменять ордера от имени аккаунта, но не выведет капитал — доступ к выводу остаётся привязан к master или subaccount. После deregistration адрес agent нельзя переиспользовать из-за жизненного цикла nonce state — это стоит закладывать в логику ротации ключей.

Сценарий: от чтения контекста до подтверждённого ордера

Условный пример иллюстрирует последовательность вызовов API без привязки к конкретному активу или моменту рынка. Бот читает metaAndAssetCtxs, находит актив по позиции в universe и берёт mark price и funding из того же индекса contexts. Пусть mark price условно 100 у.е., а oracle price условно 99.8 у.е. — premium mark над oracle в положительную сторону обычно означает, что почасовой funding будет положительным и лонги платят шортам; конкретное значение ставки здесь не задаётся, чтобы не подменять демонстрацию механики псевдо-анализом рынка.

Далее exchange client подписывает лимитный ордер условным объёмом 0.5 контракта по цене 99.5 у.е., с корректным asset ID (для perpetual и spot ID различаются) и client order id — условно 'bot-001-42'. После отправки POST /exchange бот выполняет шаги проверки, описанные ниже, и только затем обновляет внутреннее состояние позиции.

Режим исполнения задаёт, окажется ли заявка в книге вообще. ALO (add liquidity only, post only) отменяет заявку целиком, если цена пересекает книгу в момент отправки — это защищает от неожиданного taker-исполнения, но условный ордер на 99.5 у.е. может не встать в книгу, если рынок уже сдвинулся выше. IOC исполняет доступный объём немедленно и отменяет остаток. GTC остаётся в книге до исполнения или явной отмены и подходит как базовый режим для лимитных заявок без требования немедленной реакции.

Reduce only описывает не тип ордера, а его поведение относительно текущей позиции: заявка только уменьшает объём и не откроет позицию в обратную сторону. Это важно для частичного закрытия и для случаев, когда объём мог быть рассчитан с ошибкой из-за рассинхронизации локального состояния с реальной позицией — reduce only не даст боту случайно перевернуть позицию вместо сокращения. Для оценки фактического исполнения стоит смотреть не только на mid price, а на доступный объём по уровням книги, очередь заявки и среднюю цену по нескольким fills, если ордер исполнился частями.

Последовательность подтверждения ордера после отправки

Практический порядок действий приведён ниже.

1. 01
   Зафиксировать client order id

   Перед отправкой ордер получает уникальный client order id (условно 'bot-001-42'), по которому позже его можно будет найти в ответах info endpoint независимо от того, как биржа присвоила внутренний id.

2. 02
   Отправить подписанный action на exchange endpoint

   Exchange client подписывает и отправляет ордер через POST /exchange с корректным asset ID для нужного типа рынка (perpetual или spot) и выбранным режимом исполнения (ALO, IOC или GTC).

3. 03
   Не считать ответ API финальным статусом

   Ответ на POST /exchange подтверждает только приём action, а не гарантированное исполнение — решения об изменении внутреннего состояния позиции должны опираться на отдельную проверку, а не на этот ответ.

4. 04
   Запросить статус через info endpoint с адресом master или subaccount

   Повторный запрос отправляется с master или subaccount address, не с agent wallet — при чтении account state через agent результат часто пустой.

5. 05
   Найти ордер по client order id среди открытых и исполненных

   Сопоставление идёт по заранее сохранённому client order id, а не по предположению о порядке ордеров или по времени отправки.

6. 06
   Обновить внутреннее состояние только после подтверждения

   Если ордер найден и его статус подтверждён, бот обновляет локальную позицию; если ордер не найден или частично исполнен, логика реконсиляции должна учитывать среднюю цену по нескольким fills, а не только последний известный статус.

TWAP и scale-ордера в автоматизации

Помимо базовых лимитных и market-ордеров, документация описывает TWAP и scale как отдельные типы для работы с крупным объёмом. TWAP отправляет suborders каждые 30 секунд, применяет ограничение slippage и может отставать от целевого объёма, если ликвидности недостаточно для исполнения очередной порции в срок — это стоит закладывать в мониторинг исполнения, а не считать TWAP гарантированным способом набрать позицию за фиксированное время.

Scale order задаёт верхнюю и нижнюю границу цены, число уровней и общий объём: платформа расставляет серию лимитных заявок внутри диапазона одним действием. Каждый уровень ведёт себя как обычная лимитная заявка на книге HyperCore — размещённый без пересечения книги, он ждёт встречной ликвидности и обычно исполняется как maker. При резком одностороннем движении цена может проскочить весь диапазон, и часть уровней либо не исполнится, либо исполнится быстрее ожидаемого — бот должен отслеживать частичное исполнение лестницы через info endpoint, а не считать её единым атомарным действием.

TP/SL и лимиты запросов в автоматизации

Take profit и stop loss срабатывают по mark price, а не по last trade price, что снижает влияние коротких фитилей на срабатывание триггера. Market-вариант приоритетно закрывает позицию в пределах заданной tolerance, а limit-вариант даёт контроль цены закрытия, но не гарантирует полный fill: если рынок ушёл дальше лимитной цены, часть или весь объём может остаться неисполненным, и это тоже требует отдельной проверки состояния позиции.

REST и WebSocket подчиняются отдельным лимитам: документация задаёт weighted REST limit и лимиты на число WebSocket-подключений, подписок, inflight posts и сообщений. Retry-логика должна учитывать тип запроса, идемпотентность повторной отправки и backoff с jitter, а не просто повторять запрос при таймауте — иначе один и тот же ордер может быть отправлен дважды, если статус не был предварительно уточнён.

Роль официального SDK и интерфейса в проверке автоматизации

Официальный репозиторий Python SDK содержит примеры Info client, Exchange client, подписи actions, размещения ордеров и базовой работы с WebSocket, но это именно примеры, а не production-обвязка: собственные timeouts, идемпотентность запросов и reconciliation статуса ордера с локальным состоянием — задача разработчика бота, а не готовая часть SDK.

Официальный интерфейс торговли остаётся первичной точкой проверки того, что видит бот программно: доступные рынки, режим маржи, форма ордера, текущие комиссии аккаунта, transfer-маршруты и фактический статус позиции. При отладке расхождений между ожидаемым и полученным через API состоянием интерфейс — это независимый способ свериться, не связанный с тем же кодом, в котором могла быть ошибка.