API wallets и agent wallets: права и безопасная модель ключей

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

Материал рассчитан на опытных пользователей CEX/DEX, которые уже работают с perpetual, funding и стейблкоин-депозитами и переходят к автоматизации через API. Предполагается знакомство с моделью подписи транзакций, разницей master address и subaccount, а также с тем, что REST и WebSocket API Hyperliquid требуют собственной обвязки поверх официального SDK.

Почему нельзя просто дать боту приватный ключ от кошелька

Частая ошибка при подключении торгового бота — использовать тот же приватный ключ, которым подписываются депозиты и выводы. На Hyperliquid маржа привязана к адресу пользователя в hypercore, а не к кастодиальной записи биржи, поэтому этот адрес фактически и есть капитал пользователя. Если ключ от master address оказывается в переменных окружения сервера, в логах или в коде репозитория, компрометация этого ключа равна компрометации всего баланса — включая возможность вывода.

Agent wallet, он же API wallet, решает именно эту задачу: это отдельный ключ, который подписывает действия от имени master или subaccount, но сам не является этим адресом. Он создаётся специально для автоматизации и может быть отозван без необходимости менять master address или переносить капитал.

Что именно может подписывать agent wallet

По документации agent wallet годится для подписи ордеров и отмен через exchange endpoint — то есть для всех действий, формирующих торговую активность: биржа принимает подписанные actions, где важно указать корректный идентификатор торгуемого инструмента (asset id) и свой внутренний номер заявки (client order id) — по нему потом можно сверить, что стало с ордером. Это ровно тот объём прав, который нужен алгоритму: открыть позицию, закрыть, изменить лимитную заявку.

А вот для чтения account state — позиций, баланса, открытых ордеров — правило другое: в запросе нужно указывать master или subaccount address, а не адрес агента. Если подставить туда адрес agent wallet, ответ часто будет пустым, потому что агент физически не хранит баланс и позиции — он только подписывает поручения от имени того адреса, который их хранит. Дальше по тексту это разделение прав на подпись и на чтение разворачивается в конкретные архитектурные и операционные решения при построении бота.

Жизненный цикл ключа: nonce state и deregistration

Agent wallet не статичен — у него есть жизненный цикл, привязанный к внутреннему счётчику подписанных сообщений (nonce state). Документация прямо указывает: после deregistration (отзыва прав) адрес agent не следует использовать повторно, потому что счётчик этого адреса уже прожил свой цикл. Это отличается от привычной модели биржевых API-ключей, где отозванный ключ теоретически можно восстановить или переиспользовать после повторной активации.

Для операционной практики это означает: при ротации ключей бота нужно генерировать новый agent wallet, а не переиспользовать старый после deregistration. Если у вас несколько ботов или сред (тестовая и продакшн), логичнее держать под каждую отдельный agent wallet, привязанный к одному master address, — это упрощает точечный отзыв прав без остановки остальных процессов.

Как это выглядит в архитектуре реального бота

На практике бот использует два клиента с разными адресами. Info client вызывает публичные методы — например запрос, который отдаёт список торгуемых инструментов и рядом с ним параллельный массив с их текущими параметрами: маркировочной ценой, оракульной ценой, открытым интересом, ставкой funding и объёмом торгов — без подписи вообще. Exchange client подписывает и отправляет ордера, используя agent wallet. Для проверки статуса позиции и баланса info client снова вызывается, но уже с master или subaccount address как параметром запроса — не с адресом агента.

Ответ на отправку ордера фиксирует лишь факт приёма подписанного поручения биржей, а не финальное исполнение ордера: подтверждение статуса — отдельный шаг через info endpoint, сверенный по собственному номеру заявки (client order id). Именно на этом стыке чаще всего живут баги архитектуры клиента: бот либо путает адреса при чтении, либо принимает ответ на отправку ордера за подтверждение исполнения, не сверяя его отдельным запросом.

Типы ордеров и что это значит для agent wallet

Exchange endpoint поддерживает разные режимы исполнения, и agent wallet подписывает их одинаково — разница в том, как биржа обрабатывает заявку после приёма. ALO (add liquidity only, post only) означает: если заявка пересекает книгу и могла бы исполниться как тейкер, она отменяется вместо рыночного исполнения. IOC отменяет неисполненный остаток заявки сразу после попытки матчинга, а GTC оставляет её в книге до исполнения или отмены. Выбор режима — часть логики стратегии, а не подписи.

Отдельная точка ошибок — asset id, который различается для perpetual и spot рынков. Если бот отправляет поручение с asset id не того рынка, ошибка произойдёт не на уровне подписи, а на уровне содержимого самого поручения: agent wallet подписывает то, что ему передали, независимо от корректности этого содержимого.

Rate limits и WebSocket как часть той же модели прав

Разделение ключей не отменяет необходимости соблюдать общие ограничения API. Документация задаёт взвешенный лимит REST-запросов, а также отдельные лимиты на количество WebSocket-подключений, подписок, запросов «в полёте» и сообщений. Retry-логика бота должна учитывать тип запроса, безопасность повторной отправки без задвоения ордера, паузу перед повтором и фактический статус ордера, а не только сам факт сетевой ошибки.

WebSocket-подключение добавляет отдельный слой ответственности: подписки на книгу ордеров, сделки, свечи, исполнения пользователя и состояние аккаунта в реальном времени требуют корректной обработки переподключения, повторной подписки после разрыва, контроля последовательности и свежести данных, а также штатного закрытия соединения. Эта инфраструктура нужна независимо от того, каким ключом подписываются ордера — agent wallet её не упрощает и не заменяет.

Что официальный SDK не делает за вас

Официальный Python SDK содержит примеры Info client, Exchange client, подписи поручений, размещения ордеров и базовой работы с WebSocket — этого достаточно, чтобы понять структуру запросов и повторить их в собственном коде. Но примеры остаются примерами: полноценную стратегию повторных попыток с учётом лимитов, устойчивую сверку между отправкой ордера и его статусом, а также обработку долгих сетевых сбоев и переподключения WebSocket в продакшне нужно достраивать самостоятельно поверх SDK.

Корректная настройка ключей — необходимое, но не достаточное условие надёжности бота. Она защищает капитал от компрометации подписи, но не отменяет инженерную работу: без неё даже идеально разделённые ключи не спасут от бота, который дублирует ордера при обрыве связи или неверно интерпретирует статус заявки.

Пошаговая настройка разделения ключей для торгового бота

Ниже последовательность действий при подготовке бота к работе с реальным капиталом, основанная на разделении ролей между master address, subaccount и agent wallet.

1. 01
   Создать отдельный agent wallet

   Сгенерируйте новую пару ключей специально для бота, не переиспользуя ключи от master address или от других ботов. Каждая среда — тестовая и продакшн — получает собственный agent wallet.

2. 02
   Авторизовать agent wallet на master address или subaccount

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

3. 03
   Настроить чтение account state через master или subaccount address

   В коде info client укажите параметром запроса именно master или subaccount address, а не адрес agent wallet. Проверьте это на раннем этапе: попытка прочитать баланс или позиции по адресу агента вернёт пустой результат, и лучше обнаружить эту ошибку до подключения реального капитала.

4. 04
   Провести тестовый ордер с проверкой по client order id

   Отправьте небольшой ордер через exchange client, подписанный agent wallet, присвоив ему собственный client order id. Затем отдельным запросом к info endpoint убедитесь, что статус ордера и итоговая позиция совпадают с ожидаемым — это проверяет всю цепочку подписи, отправки и сверки на малой сумме до масштабирования.

5. 05
   Настроить ротацию и deregistration ключей

   Заложите в операционный процесс регулярную замену agent wallet и порядок действий при подозрении на утечку: немедленный deregistration скомпрометированного ключа и генерация нового, без повторного использования старого адреса — его nonce state уже прожил свой цикл.

Что дополнительно проверять на рынках, развёрнутых через HIP-3

Если agent wallet бота торгует на рынке, развёрнутом через HIP-3 deployer actions, права на подпись ордеров остаются теми же, но качество исполнения зависит от параметров, которые задаёт не пользователь, а деплойер рынка: обновления оракульной цены, множители funding, возможность приостановки торгов (halt trading) и предельные значения открытого интереса (OI caps). Эти параметры не влияют на то, что может подписывать agent wallet, но напрямую влияют на то, стоит ли вообще направлять на такой рынок автоматическую стратегию.

Перед подключением бота к новому HIP-3 рынку имеет смысл свериться с этими параметрами через официальный интерфейс отдельно от проверки прав ключа: конфигурация деплойера может измениться независимо от настроек agent wallet, а бот, ориентирующийся только на статичный список рынков в своём коде, рискует не заметить halt trading или изменённый cap вовремя.