Архитектура торгового бота: данные, сигнал, исполнение и reconciliation

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

Статья для опытных пользователей CEX и DEX, которые уже понимают perpetual, funding и margin tier, но проектируют собственного торгового бота на Hyperliquid и хотят избежать типовых архитектурных ошибок при работе с API, websocket и reconciliation.

Слой данных: где бот берёт market context

Первый слой — получение контекста рынка через POST /info с методом metaAndAssetCtxs. Ответ содержит universe (список активов) и параллельный массив contexts с mark price, oracle price, open interest, funding и volume. Сопоставление происходит строго по позиции в массиве, а не по тикеру: если бот фильтрует или сортирует один из массивов до объединения в пары, привязка ломается и сигнал строится на данных другого актива.

За единой точкой входа POST /info скрыты два разных типа запросов: публичная metadata рынков без подписи и account queries (позиции, баланс, ордера), для которых обязателен конкретный адрес — master или subaccount. Смешивать эти типы в одной абстракции парсера рискованно: структура ответа и требования к идентификации у них разные.

При работе с HIP-3 рынками добавляется dex namespace. Один и тот же тикер на разных deployer dex — это разные order books с собственным oracle и margin table, поэтому бот должен явно указывать, с каким dex он работает.

Realtime-слой: websocket и почему снимок не равен истине

Второй слой — websocket-подписки на книгу ордеров, trades, candles и user fills для быстрой реакции. Клиент обязан сам обрабатывать reconnect, повторную подписку на все каналы после разрыва и проверку свежести данных по временной метке или sequence внутри сообщения, а не по факту наличия соединения.

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

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

Слой исполнения: exchange endpoint, asset id и типы ордеров

Третий слой — отправка подписанных действий через POST /exchange. Asset id различается для perpetual и spot рынков и требует сопоставления с конкретным dex при работе через HIP-3. Client order id обязателен для сопоставления ордера с его фактическим статусом — без него reconciliation превращается в угадывание по времени и размеру.

Тип ордера напрямую влияет на исполнение. ALO (add liquidity only, post only) отменяет заявку целиком при пересечении книги вместо частичного taker fill — это защищает от неожиданной комиссии, но заявка может вообще не исполниться в быстром рынке. IOC отменяет неисполненный остаток немедленно, GTC остаётся в книге. TWAP для крупных объёмов отправляет suborders каждые 30 секунд с ограничением slippage, но может отстать от целевого объёма при недостаточной ликвидности — это механизм растягивания исполнения, а не гарантия заполнения.

Все типы ордеров отправляются через один exchange endpoint с разным набором полей payload. Отдельно TP/SL: такие ордера срабатывают по mark price, а не по последней случайной сделке; market-вариант приоритетно закрывает позицию в пределах заданной tolerance, а limit-вариант даёт контроль цены, но не гарантирует полный fill после срабатывания триггера.

Сценарий: от сигнала до отправленного ордера

Бот торгует пробой уровня на perpetual рынке. Сигнал строится на сочетании цены, объёма и open interest: рост цены при росте OI и подтверждающем объёме говорит о притоке нового капитала, тогда как рост цены при падении OI означает закрытие противоположных позиций без нового спроса — движение менее устойчиво. Метрики берутся из metaAndAssetCtxs, а не из цены последней сделки.

Перед отправкой ордера бот оценивает через websocket или повторный запрос к info endpoint глубину книги на уровнях выше пробитого уровня — доступный объём именно по ценовым шагам, а не только mid price. Если объём на пробое слабый или OI не растёт, сценарий отменяется до отправки ордера.

Условный расчётный пример: заявка на вход 20 000 USD (все цифры условны) отправляется после пробоя. Допустим, на трёх ближайших ценовых шагах книги доступно по 8 000, 7 000 и 9 000 USD ликвидности соответственно. Если основной объём заявки закрывается первыми двумя шагами, средняя цена исполнения близка к цене пробоя; если бы та же суммарная глубина была смещена к третьему, самому дальнему шагу, итоговая средняя цена оказалась бы хуже при той же общей ликвидности. Поэтому бот оценивает распределение объёма по шагам, а не только агрегированную сумму в стакане.

Reconciliation: сверка фактического статуса ордера и позиции

Четвёртый слой замыкает цикл: после отправки ордера бот не считает задачу выполненной по факту отправки запроса. Client order id используется для повторного запроса к info endpoint, который возвращает фактический статус — исполнен полностью, частично или отменён — и текущее состояние позиции. Именно это подтверждённое состояние, а не websocket-снимок, становится основанием для постановки стопа, пересчёта маржи и следующего сигнала.

Для чтения статуса и позиции нужен master или subaccount address — agent wallet, использованный для подписи ордера, здесь не подходит и вернёт пустой результат при попытке прочитать account state. Разделение адресов для подписи и для чтения — требование самого API, которое нужно заложить в архитектуру клиента с самого начала. Расчёт буфера до ликвидации также опирается на подтверждённый статус позиции и mark price, а не на последнюю случайную сделку в ленте.

Последовательность действий при отправке одного ордера

Ниже — последовательность шагов, которая связывает описанные слои в единый рабочий цикл при отправке одного ордера от сигнала до подтверждённого статуса.

1. 01
   1. Обновить market context

   Запросить metaAndAssetCtxs, сопоставить universe и contexts по позиции массива, получить mark price, oracle price, OI и volume для нужного dex.

2. 02
   2. Подтвердить сигнал через realtime-данные

   Проверить свежесть websocket-подписок по временной метке или sequence; если данные устарели или соединение разрывалось — восстановить состояние перед принятием решения.

3. 03
   3. Оценить книгу по уровням

   Через websocket или повторный запрос к info endpoint оценить доступный объём по конкретным ценовым шагам выше или ниже сигнального уровня, а не только mid price.

4. 04
   4. Сформировать и отправить action

   Подготовить подписанный action с корректным asset id для нужного dex, указать тип ордера (ALO, IOC, GTC или TWAP) и обязательный client order id, отправить через exchange endpoint.

5. 05
   5. Сверить статус через info endpoint

   По client order id запросить фактический статус — исполнен, частично исполнен или отменён — и подтверждённое состояние позиции; не полагаться на факт отправки запроса как на подтверждение исполнения.

6. 06
   6. Пересчитать маржу и буфер до ликвидации

   Использовать подтверждённый статус позиции, режим margin (cross или isolated) и mark price для пересчёта дистанции до ликвидации и постановки стопа.

Частые ошибки при переносе бота в production

Первая — сортировка или фильтрация universe и contexts по отдельности перед сопоставлением по позиции массива: привязка данных к активу ломается незаметно, и бот получает контекст не того инструмента.

Вторая — попытка читать позиции и баланс через agent wallet вместо master или subaccount address, из-за чего reconciliation получает пустой ответ и бот принимает решение вслепую.

Третья — отсутствие client order id при отправке через exchange endpoint, из-за чего сопоставление ордера со статусом превращается в угадывание вместо точной сверки.

Четвёртая — расчёт margin buffer без учёта того, что cross margin использует общий доступный collateral аккаунта, а isolated ограничивает маржу конкретной позицией: переключение режима без пересчёта размера позиции и денежного стоп-лосса меняет фактическую дистанцию до ликвидации.

SDK, agent wallet и жизненный цикл nonce

Официальный Python SDK Hyperliquid содержит примеры Info client и Exchange client, подписи actions, размещения ордеров и базовой работы с websocket. Эти примеры полезны как отправная точка, но не закрывают производственные требования сами по себе: собственные timeouts, идемпотентность повторных запросов и полноценный reconciliation-цикл остаются задачей разработчика бота. Разделение двух клиентов в SDK отражает разделение самого API: Info client вызывает публичные и account-специфичные методы, Exchange client подписывает и отправляет actions.

Отдельный источник расхождений в production — жизненный цикл agent wallet и связанного с ним nonce state. После deregistration адрес agent не следует использовать повторно: nonce state привязан к конкретному адресу, и его повторное использование ломает предсказуемость подписи действий. Хранение соответствия между agent wallet, master address и статусом должно быть частью state, которое бот проверяет перед подписью каждого действия — иначе заявки могут отправляться какое-то время без видимых проблем, а затем API начинает отклонять подписи с ошибками, трудно диагностируемыми без явного лога состояния agent wallet.