Ваш бот на Hyperliquid постоянно получает 429. Решите это раз и навсегда.

Вы пишете бота, который каждую секунду опрашивает Hyperliquid для получения цен. В тестировании всё работает отлично. Потом вы добавляете второй актив. Затем пять. Затем начинаете проверять позиции и финансирование с той же частотой, раз уж можно. Через несколько минут API начинает возвращать HTTP 429, и ваш бот слепнет в самый неподходящий момент.

Это самый распространённый сбой у начинающих разработчиков на Hyperliquid, и решение почти никогда не заключается в «переходе на более высокий тариф». Проблема архитектурная: большинство ботов обращаются к каждому эндпоинту как к одинаковому по стоимости, опрашивают данные, которые почти не меняются, с той же частотой, что и данные, обновляющиеся каждый блок, и игнорируют инструменты, которые Hyperliquid предоставляет для полного отказа от REST. Стоит разобраться, как на самом деле работает система весов, и ошибки 429 превратятся из неизбежности в нечто, что можно исключить архитектурно раз и навсегда.

В этом руководстве разобраны все ограничения Hyperliquid, объяснена математика весов для каждой категории эндпоинтов, а также рассмотрены паттерны кэширования, WebSocket и батчинга, позволяющие держать производственного бота далеко от лимита.

Весовой бюджет: 1 200 в минуту, но не все вызовы равнозначны

REST API Hyperliquid использует систему весов. Каждый IP-адрес получает общий бюджет в 1 200 весовых единиц в минуту. Но стоимость каждого запроса существенно варьируется в зависимости от вызываемого эндпоинта.

Запросы к Exchange API (размещение ордеров, отмена, изменение) стоят 1 + floor(batch_length / 40) весовых единиц. Один ордер стоит 1. Батч из 39 ордеров тоже стоит 1. Батч из 40 стоит 2. Это делает батчинг одним из самых эффективных инструментов управления лимитами.

Info-эндпоинты делятся на три категории:

| Категория | Вес | Эндпоинты | | --- | --- | --- | | Лёгкие | 2 | l2Book, allMids, clearinghouseState, orderStatus, spotClearinghouseState, exchangeStatus | | Тяжёлые | 20 | Все остальные задокументированные info-запросы (позиции, сделки, история финансирования, таблицы лидеров) | | Самые тяжёлые | 60 | userRole |

Некоторые эндпоинты также масштабируются по размеру ответа. Вызовы recentTrades, historicalOrders, userFills, userFillsByTime, fundingHistory и ряда других добавляют дополнительный вес за каждые 20 возвращаемых элементов. Эндпоинт candleSnapshot добавляет вес за каждые 60 элементов. Запросы к Explorer API начинаются с веса 40 плюс 1 за каждый блок для blockList.

Именно математика подводит разработчиков. Если ваш бот опрашивает allMids раз в секунду (вес 2 каждый запрос), это уже 120 весовых единиц в минуту только на ценовые данные. Добавьте проверки clearinghouseState с той же частотой (ещё 120), и вы уже используете 20% бюджета до того, как разместили хоть один ордер. Добавьте эндпоинт с весом 20, например userFills, с той же частотой, и сжигаете 1 200 весовых единиц в минуту только на сделки. Бюджет исчерпан.

Лимит по адресу, о котором большинство разработчиков забывает

Ограничение по IP все знают, потому что ошибки 429 громкие. Но Hyperliquid также применяет отдельный лимит на каждый адрес кошелька, и он тише, но не менее болезнен при превышении.

Каждый адрес начинает с буфером в 10 000 запросов. После этого лимит растёт в зависимости от торгового объёма: один дополнительный запрос за каждый 1 USDC, наторгованный совокупно с момента создания адреса. Аккаунт с лайфтайм-оборотом $500 000 получает бюджет 510 000 запросов. Новый адрес в тестовой сети, который никогда не торговал, исчерпает буфер за несколько часов при агрессивном опросе.

При достижении лимита по адресу API ограничивает вас до одного запроса каждые 10 секунд. Это не жёсткая блокировка, а поводок. Бот продолжает работать, но в режиме черепашьего шага. Есть и хорошая новость: операции отмены получают более щедрый бюджет — min(limit + 100,000, limit * 2), так что закрыть позиции всегда можно, даже при ограничении на всё остальное.

Субаккаунты считаются отдельными пользователями для лимитов по адресу, поэтому распределение операций между субаккаунтами может помочь. Но не путайте это с IP-лимитами, которые применяются ко всему трафику с одного IP вне зависимости от того, какой адрес делает запрос.

Лимиты WebSocket: 1 000 подписок, а не 1 000 на соединение

Переход с REST-опроса на WebSocket-подписки — это самая эффективная оптимизация по лимитам, которую большинство разработчиков может сделать. Подписки доставляют данные боту при изменении, не потребляя весовой бюджет REST. Но у WebSocket-соединений есть собственные ограничения, и самое распространённое заблуждение касается подсчёта подписок.

Hyperliquid допускает максимум 10 одновременных WebSocket-соединений на IP с лимитом 30 новых соединений в минуту. Лимит подписок — 1 000 суммарно по всем соединениям. Открытие пяти соединений не даёт вам 5 000 подписок. По-прежнему 1 000, совместно.

Лимит исходящих сообщений — 2 000 в минуту, с максимумом 100 одновременных inflight post-сообщений. Подписки, привязанные к пользователю (например, UserEvents), ограничены 10 уникальными пользователями на IP.

Математика подписок имеет значение. Hyperliquid торгует более 200 бессрочными контрактами. Каждая пара «актив — тип данных» требует отдельной подписки. Если подписаться на Trades и L2Book по каждому активу, это уже 400+ подписок только на два типа данных. Добавьте Candle хотя бы на одном таймфрейме — перевалит за 600+. На двух таймфреймах превысите лимит в 1 000.

Динамическое управление подписками

Производственным ботам редко нужны все фиды по всем активам одновременно. Более эффективный подход — поддерживать список наблюдения и ротировать подписки в зависимости от того, что стратегия реально требует прямо сейчас. Подпишитесь на AllMids один раз для всех цен (одна подписка), затем добавляйте фиды по конкретным активам только для монет, которыми вы активно торгуете или мониторите для входа.

Когда актив покидает список наблюдения, отписывайтесь и освобождайте слот. Такой паттерн позволяет оставаться в рамках 1 000, даже если вселенная активов насчитывает сотни, потому что активное множество в любой момент времени обычно значительно меньше.

Что реально происходит при получении 429

Ответ 429 от Hyperliquid означает отклонение запросов, но это предупредительный выстрел. API возвращает сообщение об ошибке в теле ответа и может включать заголовок Retry-After, точно указывающий, сколько нужно ждать. Краткосрочные события с превышением лимита приводят к отклонению запросов, а не к блокировке аккаунта. Но систематический агрессивный трафик может повлечь более серьёзные последствия.

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

1. Проверьте заголовок Retry-After. Если есть, ждите ровно столько.
2. Если заголовка нет, начните с задержки 1 секунда.
3. Удваивайте задержку после каждой последовательной ошибки: 1с, 2с, 4с, 8с, 16с, 32с.
4. Ограничьте 60 секундами. Если 429 продолжаются на этом уровне, что-то системно не так.
5. Сбрасывайте таймер задержки после успешного запроса.

async def request_with_backoff(endpoint, payload, max_retries=6):
    delay = 1
    for attempt in range(max_retries):
        response = await client.post(endpoint, json=payload)
        if response.status_code != 429:
            return response
        retry_after = response.headers.get("Retry-After")
        wait = int(retry_after) if retry_after else delay
        await asyncio.sleep(wait)
        delay = min(delay * 2, 60)
    raise RateLimitExceeded(f"Still 429 after {max_retries} retries")

Батчинг: самая недооценённая оптимизация

Система батчинга Hyperliquid исключительно щедра. Батч из 39 Exchange API-запросов (ордера, отмены, изменения) стоит столько же, сколько один запрос: вес 1. Батч из 40 стоит вес 2. Батч из 79 всё ещё вес 2. Значит, бот, размещающий 30 ордеров по одному, сжигает 30 единиц веса, тогда как те же 30 ордеров в одном батче — всего 1.

Есть важный нюанс для лимитов по адресу. Батчевые запросы считаются как один запрос для IP-ограничения, но как n запросов для ограничения по адресу. Батчинг экономит IP-бюджет, но не экономит бюджет по адресу. Для большинства разработчиков IP-лимит является основным ограничением, поэтому батчинг всё равно даёт наибольший выигрыш. Просто помните, что высокочастотный бот, отправляющий сотни батчевых ордеров в минуту, всё равно будет расходовать буфер по адресу.

Кэширование: перестаньте повторно запрашивать данные, которые почти не меняются

Ставка финансирования на Hyperliquid рассчитывается раз в час. Open interest обновляется каждый блок, но существенно не меняется посекундно для большинства активов. Метаданные биржи (списки активов, параметры маржи) меняются, пожалуй, раз в неделю при новых листингах. Тем не менее большинство ботов опрашивают всё это с той же агрессивной частотой, что и ценовые данные.

Локальный слой кэша с TTL-экспирацией устраняет большинство этих лишних вызовов:

• Цены (allMids): Переходите на WebSocket. Нулевой вес REST.
• Позиции (clearinghouseState): Опрашивайте каждые несколько секунд (например, 5–15 секунд), кэшируйте между опросами.
• Ставки финансирования: Кэшируйте на несколько минут (например, 10–15 минут). Расчёт происходит раз в час, так что даже 15-минутный кэш означает не более 4 проверок за один расчётный период.
• Сделки (userFills): Подпишитесь через WebSocket UserEvents для обновлений в реальном времени. REST-опрос используйте только как резервную сверку.
• Метаданные (списки активов, спецификации): Кэшируйте агрессивно (метаданные меняются редко). Загружайте при старте и обновляйте периодически.

Сочетание WebSocket-подписок для быстро меняющихся данных и кэшированных REST-опросов для медленных данных, как правило, снижает общее потребление REST-веса более чем на 90% по сравнению с наивной архитектурой опроса. Для большинства ботов это означает, что бюджета в 1 200 весовых единиц в минуту хватит с запасом на годы роста без единого срабатывания лимита.

Разделяйте бюджет на данные и бюджет на торговлю

В документации Hyperliquid указано, что лимиты для категорий info и exchange-эндпоинтов раздельны. Это ключевой архитектурный принцип. Запросы рыночных данных никогда не должны конкурировать с размещением ордеров за весовой бюджет.

На практике это означает построение бота с двумя отдельными путями запросов: один для получения данных (info-эндпоинты, аналитика, мониторинг), другой для исполнения (ордера, отмены, изменения). Если в слое данных возникнет баг, вызывающий всплеск запросов, торговый путь останется незатронутым. Если слой исполнения занят пакетной отменой во время события ликвидации, потоки данных продолжают работу.

Для разработчиков, использующих предварительно вычисленную аналитику, это разделение становится ещё чище. Вместо того чтобы тратить бюджет info-эндпоинтов на обработку сырых данных (запросы сделок для сотен адресов, вычисление когортных агрегатов, отслеживание изменений таблиц лидеров), можно потреблять эту аналитику через выделенный слой. API HyperTracker предоставляет позиции по когортам, агрегаты Smart Money и оценку риска ликвидации в виде предварительно вычисленных эндпоинтов, так что весовой бюджет Hyperliquid вашего бота остаётся полностью сосредоточен на данных, доступных только у Hyperliquid: цены, ваши собственные позиции и исполнение ордеров.

Строите быстрее, опрашиваете меньше

HyperTracker вычисляет когортную аналитику по 16 поведенческим сегментам, чтобы вашему боту не приходилось парсить сотни кошельков. Один API-вызов заменяет тысячи запросов позиций. Начните с бесплатного тарифа.

Изучить API

Мониторинг бюджета в продакшне

Разница между ботом, который «работает на тестировании», и тем, который надёжно работает в продакшне, — это мониторинг. Hyperliquid предоставляет info-эндпоинт userRateLimit, который возвращает текущий статус лимита по адресу, оставшийся бюджет и использование. Периодический опрос (например, раз в 30 секунд) даёт раннее предупреждение до того, как вы упрётесь в стену.

Помимо встроенного эндпоинта Hyperliquid, оснастите бота метриками:

• Запросов в минуту по типу эндпоинта: Знайте, какие эндпоинты потребляют больше всего веса.
• Частота 429: Любое ненулевое значение означает ошибку в математике бюджета.
• Частота переподключений WebSocket: Частые переподключения могут указывать на то, что упавшие соединения съедают лимит в 30 новых подключений в минуту.
• Коэффициент попаданий в кэш: Низкий показатель означает слишком короткие TTL или отсутствие кэширования там, где оно нужно.
• Перцентили задержки ответов (p50, p95, p99): Рост задержки может сигнализировать о приближении к лимитам ещё до появления 429.

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

Архитектура, которая масштабируется без лимитных проблем

Вот стек, который держит производственных Hyperliquid-ботов в рамках бюджета независимо от количества отслеживаемых активов:

1. WebSocket в приоритете: Используйте AllMids для цен, L2Book для глубины по активным активам, UserEvents для сделок. Это устраняет самый высокочастотный REST-опрос.
2. Кэшируйте всё медленное: Ставки финансирования, метаданные и исторические запросы получают локальные TTL-кэши. Обновляйте по расписанию, а не по требованию.
3. Батчингуйте все записи: Группируйте ордера, отмены и изменения в батчи. По формуле весов батчи до 40 элементов стоят вес 1.
4. Разделяйте данные и исполнение: Используйте разные менеджеры запросов с независимым мониторингом. Баг в данных не должен блокировать сделку.
5. Выносите аналитику на аутсорс: Пусть предварительно вычисленный API вроде HyperTracker занимается когортной аналитикой. Тратьте бюджет Hyperliquid на то, что только Hyperliquid может дать.
6. Мониторинг и алерты: Отслеживайте потребление веса по эндпоинтам, следите за трендами 429 и корректируйте TTL или количество подписок до достижения лимитов.

Каждый разработчик на Hyperliquid хотя бы раз получает 429. Те, кто строит долговечные продукты, перепроектируют архитектуру так, чтобы это больше не повторилось. Все инструменты есть: весовое бюджетирование, щедрый батчинг, нативная поддержка WebSocket и эндпоинт userRateLimit, показывающий точное состояние ваших лимитов. Используйте их, и ограничение скорости превратится в ограждение, которого вы никогда не касаетесь.