Ваш 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 одночасних очікуючих 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 розраховується раз на годину. Відкритий інтерес оновлюється кожен блок, але для більшості активів не змінюється суттєво в розрізі секунди. Метадані біржі (списки активів, специфікації, параметри маржі) змінюються хіба що раз на тиждень при нових лістингах. Проте більшість ботів опитують усе це з тією ж агресивною частотою, що й цінові дані.

Локальний шар кешування з TTL-закінченням терміну усуває більшість цих зайвих викликів:

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

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

Розділіть бюджет даних і бюджет торгівлі

Документація Hyperliquid зазначає, що ліміти для категорій ендпоінтів info та exchange є окремими. Це критично важливе архітектурне спостереження. Ваші запити ринкових даних ніколи не повинні конкурувати за ліміт із розміщенням ордерів.

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

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

Будуйте швидше, опитуйте менше

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

Дослідіть API

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

Різниця між ботом, який «працює під час тестування», і тим, що надійно працює в продакшні, — це моніторинг. Hyperliquid надає info-ендпоінт userRateLimit, який повертає поточний статус адресного ліміту, залишковий бюджет і використання. Його periodically-запити (наприклад, кожні 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, який показує точно, де ви стоїте. Використовуйте їх, і ліміт стане огорожею, якої ви ніколи не торкнетеся.