Info endpoint: metadata и market context без ошибок

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

Материал рассчитан на трейдера и разработчика, который уже работает с Hyperliquid через API или Python SDK, понимает механику perpetual, funding и margin, и собирает собственный слой данных — дашборд, бота или систему сигналов. Предполагается знакомство с REST-запросами, JSON-структурами и базовой архитектурой торгового приложения, но не с внутренним устройством Hyperliquid info endpoint.

Зачем нужен info endpoint и что он реально возвращает

POST /info — единая точка получения как публичной metadata рынков, так и приватных данных аккаунта. В одном интерфейсе смешаны два типа запросов: метаданные без подписи (universe, asset contexts, свечи) и account queries, для которых нужен конкретный адрес. Структура ответа зависит от типа запроса, и это требует разной обвязки для парсинга — простого REST-справочника здесь не получится.

Для торгового контекста — mark price, oracle price, funding rate, open interest, объём — ключевой метод MetaAndAssetCtxs. Он даёт не единый плоский объект на актив, а два параллельных массива: universe с описанием инструментов и contexts с рыночными показателями. Такое разделение экономит трафик, но перекладывает ответственность за корректное сопоставление на клиента.

Механика сопоставления universe и contexts

MetaAndAssetCtxs связывает universe с contexts исключительно по позиции элемента: индекс 0 в universe соответствует индексу 0 в contexts, и так далее. Отдельного id или symbol-ключа для сшивки не передаётся.

Отсюда главный источник ошибок: любая операция, меняющая порядок или длину одного массива без применения той же операции к другому, разрушает пары. Фильтрация universe, сортировка по имени, удаление делистнутых инструментов до объединения массивов — и funding одного актива окажется приписан к mark price другого, без ошибки выполнения.

Правильный порядок — сначала построить пары (universe[i], contexts[i]) для всех i, затем фильтровать, сортировать, кэшировать уже пары. Индекс не стоит хранить как константу между запросами: добавление нового инструмента в universe может сдвинуть позиции существующих элементов, и старый индекс начнёт указывать не туда.

DEX namespace и рынки HIP-3: один тикер, разные площадки

HIP-3 позволяет builder deployer запускать собственный perpetual DEX на общем hypercore стеке. У каждого такого DEX — отдельные order books, margining и settings, а deployer определяет market definition, oracle, leverage limits, margin tables и OI caps самостоятельно. Namespace здесь не отдельный параметр в теле запроса MetaAndAssetCtxs, а неявный контекст: запрос выполняется в границах конкретного DEX, и полученная пара (universe, contexts) относится только к нему.

Практическое следствие: universe и contexts, полученные для одного DEX, не образуют часть единого глобального реестра. Если код объединяет ответы нескольких DEX без явной метки, какому deployer принадлежит каждый набор, он рискует смешать данные двух рынков с одинаковым тикером, но разными правилами margin и разным oracle.

Перед построением агрегированного dashboard на нескольких DEX стоит фиксировать источник для каждой полученной пары (universe, contexts) и не объединять данные разных DEX в одну таблицу без метки namespace — иначе сопоставление по тикеру повторяет ту же ошибку, что сопоставление по индексу без сшивки массивов.

Agent wallet и account queries: где чтение ломается чаще всего

Для account queries — позиции, баланс, открытые ордера, история fills — info endpoint требует master или subaccount address. Agent wallet (он же API wallet) создан для подписи exchange-действий от имени основного аккаунта, но не является валидным адресом для чтения его состояния. Это asymmetric-модель: один ключ подписывает, другой адрес читает.

Типичная ошибка самодельных интеграций — передать адрес agent wallet как параметр user при запросе account state, по аналогии с тем, как этот адрес фигурирует в exchange-запросах для подписи. Результат — пустой ответ, который легко спутать с отсутствием позиций у трейдера, хотя проблема в самом переданном адресе.

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

Числовой сценарий: сборка market context для одного актива

1. 01
   Этап 1

   Задача: получить mark price, oracle price, funding и open interest для ETH-perp перед расчётом margin buffer.

2. 02
   Этап 2

   Ответ MetaAndAssetCtxs по структуре — массив из двух элементов: первый содержит universe (список объектов с полем name и другими параметрами инструмента), второй — contexts (список объектов с markPx, oraclePx, funding, openInterest и прочими рыночными полями), одинаковой длины.

3. 03
   Этап 3

   В условном примере ETH находится в universe на индексе 3 (universe[3].name = "ETH").

4. 04
   Этап 4

   Для того же индекса берётся contexts[3]: markPx — строка "3182.4", oraclePx — "3179.9", funding — "0.0000125" за период, openInterest — "48213.6" в базовом активе (значения условные, приведены для иллюстрации формата).

5. 05
   Этап 5

   Только пара universe[3] и contexts[3] на момент запроса образует валидный набор для ETH.

6. 06
   Этап 6

   Ошибка на практике — закэшировать индекс 3 для ETH в конфиге бота и переиспользовать его без проверки.

7. 07
   Этап 7

   Если Hyperliquid добавит новый актив в universe раньше позиции ETH, индекс сдвинется — условно ETH окажется на позиции 4 — и закэшированная тройка значений начнёт молча указывать на другой контракт.

8. 08
   Этап 8

   Индекс нужно пересчитывать при каждом свежем запросе universe, а не хранить между сессиями.

Rate limits и частота запросов metadata

Info endpoint работает по weighted REST limit, и повторные запросы полного universe с contexts при высокой частоте опроса быстро расходуют лимит, особенно если приложение параллельно дергает account queries для нескольких subaccount. Для metadata, которая меняется медленнее рыночных цен — состав universe, margin tables, leverage limits — разумно разделить частоту опроса: universe кэшировать на разумный интервал, а быстро меняющиеся contexts запрашивать чаще или получать через WebSocket subscriptions.

WebSocket предоставляет realtime подписки на книгу, trades, candles, user fills и состояние аккаунта, но клиент обязан сам обрабатывать reconnect, повторную подписку после разрыва и проверку freshness данных по sequence или времени. Смешивание REST info-запросов для первичной загрузки metadata и WebSocket для последующих обновлений — рабочая схема, но она требует явной логики разделения «начального снимка» и «дельты», иначе легко получить дублирование или устаревшие значения после переподключения.

Retry-стратегия для info-запросов и её отличие от exchange-запросов

Retry для info endpoint проще, чем для exchange endpoint: запросы metadata идемпотентны по своей природе — повторный вызов MetaAndAssetCtxs не создаёт побочных эффектов, поэтому backoff с jitter при 429 можно применять без дополнительных проверок статуса. Это отличается от retry POST /exchange, где повторная отправка подписанного action при неопределённом статусе первого запроса требует проверки фактического состояния ордера, а не слепого повтора.

Практический вывод: слой чтения metadata и слой отправки ордеров должны иметь разные retry-политики. Объединение этих слоёв в единый generic retry-wrapper — частая причина либо избыточной нагрузки на rate limit при простом чтении контекста, либо недостаточно агрессивного повтора для info-запросов, которые безопасно повторять чаще, чем действия по подписи.

Проверочный список перед тем, как строить логику на market context

Перед подключением модуля расчёта margin buffer, сигнальной системы или dashboard к данным из info endpoint стоит пройти явную проверку: правильный тип адреса для приватных данных (master/subaccount, не agent wallet); сшивка universe и contexts строго по индексу до любой фильтрации, без переиспользования индекса между сессиями; привязка каждой пары (universe, contexts) к конкретному DEX namespace при работе с HIP-3 рынками; раздельная частота опроса медленной metadata и быстрых contexts; отдельная retry-политика для чтения и для подписанных действий.

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