Как читать лидерборд Hyperliquid и позиции кошельков

Где на самом деле находится лидерборд

Основной API отвечает на POST https://api.hyperliquid.xyz/info, и документация info API подробно его описывает — все запросы уровня кошелька из этой статьи есть там. Лидерборд — исключение: он отдаётся обычным GET по адресу https://stats-data.hyperliquid.xyz/Mainnet/leaderboard, и этого пути в справке нет. Публичные SDK работают с ним как со вторым базовым адресом рядом с основным API, а не как с info-запросом, — и это самый ясный сигнал о его устройстве: другой хост, другая форма ответа, нет поля type, нет POST-тела.

Отсюда два следствия, и оба операционные, а не теоретические. Первое: доступность у хостов независимая. Это разные сервисы, поэтому проверка api.hyperliquid.xyz ничего не говорит о том, отвечает ли статистический хост. Мониторьте их раздельно, иначе задача по лидерборду будет молча завершаться с ошибкой, пока все остальные вызовы работают. Второе: ответ тяжёлый и медленный по сравнению с info-вызовом. По замеру напрямую с нашего сервера медианное время ответа лидерборда — около 0,7 секунды против примерно 0,3 секунды у clearinghouseState, причём отдаёт он весь рейтинг целиком, а не страницу.

Ответ представляет собой рейтинг — по объекту на кошелёк, — и его форму стоит знать до того, как на неё опираться:

{
  "ethAddress": "0x...",
  "accountValue": "1234567.89",
  "displayName": "имя трейдера или null",
  "prize": 0,
  "windowPerformances": [
    ["day",     {"pnl": "12345.6", "roi": "0.0123", "vlm": "9876543.2"}],
    ["week",    {"pnl": "...", "roi": "...", "vlm": "..."}],
    ["month",   {"pnl": "...", "roi": "...", "vlm": "..."}],
    ["allTime", {"pnl": "...", "roi": "...", "vlm": "..."}]
  ]
}

ethAddress — тот самый ключ, который вы понесёте во все вызовы уровня кошелька ниже. Показатели приходят парами «окно — метрики», а не плоскими полями, поэтому «топ по недельному PnL» означает сначала выбрать нужное окно; а все числа приходят строками — это единообразно для всего API и регулярно приводит к ошибкам сравнения. Поле displayName необязательное и часто пустое.

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

import json, time, requests

STATS = "https://stats-data.hyperliquid.xyz/Mainnet/leaderboard"
CACHE, TTL = "leaderboard.json", 3600          # совпадает с частотой обновления снимка

def leaderboard():
    try:                                        # отдаём из кеша, пока он свежий
        with open(CACHE) as f:
            blob = json.load(f)
        if time.time() - blob["fetched"] < TTL:
            return blob["rows"]
    except (FileNotFoundError, json.JSONDecodeError, KeyError):
        pass
    r = requests.get(STATS, timeout=30)          # с запасом: этот хост медленнее /info
    r.raise_for_status()
    rows = r.json().get("leaderboardRows", [])
    with open(CACHE, "w") as f:
        json.dump({"fetched": time.time(), "rows": rows}, f)
    return rows

rows = leaderboard()
print(len(rows), "кошельков")
print(rows[0]["ethAddress"], rows[0]["accountValue"])

На что смотреть: таймаут намеренно щедрый, потому что хост медленнее основного API, а кеш — именно то, что убирает медленную недокументированную зависимость с критического пути. Проверяйте поля, на которые опираетесь, а не предполагайте их: эндпоинт, отсутствующий в формальном справочнике, не несёт обязательств по совместимости — даже при том, что о его переезде на этот хост объявляли публично. Чего сниппет не делает: у него нет запасного пути на случай недоступности статистического хоста — в продакшене нужно продолжать отдавать последний удачный кеш и поднимать предупреждение, а не завершать работу с ошибкой.

Как прочитать состояние одного кошелька

Когда адреса есть, дальше всё — документированный API. Запрос clearinghouseState возвращает состояние кошелька по бессрочным контрактам: сводку по марже, доступный к выводу баланс и открытые позиции пользователя в assetPositions. Весит он 2 — дешёвый уровень, вместе с l2Book и allMids, — и не требует ни ключа, ни подписи, ни аккаунта. Одна деталь области действия, которую упускают старые гайды: запрос принимает необязательный параметр dex, и без него вы получаете первый perp-DEX. Позиции на развёрнутых разработчиками DEX по HIP-3 нужно запрашивать отдельно, если они вам важны.

import requests

INFO = "https://api.hyperliquid.xyz/info"

def wallet_state(address):
    r = requests.post(INFO, json={"type": "clearinghouseState", "user": address}, timeout=10)
    r.raise_for_status()
    return r.json()

state = wallet_state("0x0000000000000000000000000000000000000000")   # адрес пользователя или субаккаунта
for item in state["assetPositions"]:
    p = item["position"]
    print(p["coin"], p["szi"], "вход", p["entryPx"], "uPnL", p["unrealizedPnl"])

Чтение позиций по адресу устроено ровно так: szi — знаковый размер, поэтому отрицательное значение означает шорт; entryPx — средняя цена входа; рядом находятся unrealizedPnl и marginUsed. Для корректно определённого адреса пользователя или субаккаунта пустой список assetPositions означает отсутствие открытых позиций, а не ошибку, — это важно, когда вы идёте по сотням адресов и должны отличать «в нуле» от «не ответил». Оговорка, о которой предупреждает документация: не направляйте этот запрос на адрес агента или API-кошелька — там можно получить пустой результат по кошельку, который очевидно держит позиции.

Два ограничения определяют, что на этом вызове можно построить. Это снимок, а не поток: об изменении позиции вы узнаёте, только спросив снова, поэтому ваше разрешение по времени равно интервалу опроса. И пользовательские вебсокет-подписки перестают масштабироваться в пределах одного адреса: документированные лимиты Hyperliquid разрешают максимум 10 уникальных пользователей в пользовательских вебсокет-подписках на один IP.

Этот потолок формирует архитектуру, а не закрывает её. Работают три схемы, и они комбинируются:

• До десяти кошельков на адрес — пользовательские подписки, вариант с наименьшей задержкой и правильный выбор для личного кабинета.
• Разнести подписки — по десять уникальных пользователей на исходящий адрес, тогда список наблюдения растёт вместе с числом адресов.
• Следить за рынком, а не за кошельками — общерыночная подписка на сделки несёт массив users с покупателем и продавцом каждой сделки, поэтому можно фильтровать поток по своему списку наблюдения для обнаружения изменений, а затем сверять только затронутые кошельки через clearinghouseState. Именно так построены некоторые современные трекеры кошельков: задача подписки на каждый кошелёк превращается в задачу фильтрации.

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

Как достать сделки, стоящие за позицией

Позиция говорит, где кошелёк находится; сделки — как он туда пришёл. Эндпоинт userFills возвращает до 2 000 последних исполнений по адресу, а флаг aggregateByTime объединяет частичные исполнения одного пересекающего ордера. Для всего, что ограничено временем, есть userFillsByTime: он принимает обязательный startTime в миллисекундах и необязательный endTime со значением «сейчас» по умолчанию, а документация отмечает не более 2 000 исполнений в ответе при доступных всего 10 000 последних.

Поведение startTime — то место, где первая реализация обычно ошибается, и ловушка не в размере окна, а в работе с курсором при обрезанных ответах. startTime включающий и задаётся в миллисекундах, а несколько исполнений могут попасть в одну и ту же миллисекунду, поэтому сдвиг на last_time + 1 способен молча потерять записи, стоявшие за последней увиденной. Безопасная схема — перекрывающийся курсор: начинайте заново с последней отметки времени, а не за ней; дедуплицируйте по идентификатору исполнения — tid или хешу транзакции; и сдвигайте курсор только после обработки всего, что вернул ответ. Учитывайте и горизонт: не более 2 000 исполнений в ответе и всего 10 000 последних, так что глубокой истории здесь нет вовсе, а попытка сделать вид, что она есть, даёт молча обрезанную выгрузку.

Их стоимость легко оценить неверно в обе стороны. Оба эндпоинта по сделкам весят 20 — базовый уровень для info-запросов — плюс дополнительный вес за каждые 20 элементов в ответе. Полный ответ на 2 000 исполнений стоит, таким образом, около 120 весов по документированной формуле — примерно как 60 вызовов clearinghouseState: достаточно дорого, чтобы история сделок жила в медленной фоновой задаче, и достаточно дёшево, чтобы один такой вызов сам по себе не сломал минутный бюджет.

Как следить за кошельком на практике

Две оговорки до всякой архитектуры, потому что словосочетание «копитрейдинг» обещает больше, чем открывает платформа. API копитрейдинга у Hyperliquid нет — в смысле эндпоинта, который зеркалил бы действия другого трейдера на ваш счёт. Есть публичный доступ на чтение состояния любого кошелька и обычный торговый API для ваших собственных ордеров. Любая система «следования» — это ваш собственный конвейер: прочитать кошелёк, принять решение, выставить свой ордер. А значит, и задержка, и проскальзывание, и само решение торговать — тоже ваши.

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

Закрытие позиции рыночным ордером — та же история с другой стороны. У торгового API Hyperliquid нет отдельного эндпоинта закрытия: позиция закрывается встречным ордером с флагом reduce_only, а рыночное исполнение выражается агрессивным лимитным ордером с ограничением по проскальзыванию, а не типом MARKET. Хелпер market_close в официальном Python SDK делает под капотом именно это — прочитайте его, прежде чем писать своё.

Так что архитектура сводится к бюджету опроса, и бюджет документирован: REST-запросы делят общий лимит в 1 200 весов в минуту на один IP-адрес. При весе 2 у clearinghouseState арифметика даёт 600 проверок кошельков в минуту с адреса. Но прежде чем планировать мощность вокруг этого числа, важнее три программных рычага:

• Кешируйте то, что не меняется. Лидерборд — раз в час, meta — раз в сутки. Это вызовы весом 20, которым нечего делать в цикле.
• Опрашивайте по уровням, а не равномерно. Кошелькам с открытыми позициями нужны секунды, пустым — минуты. Равномерный опрос тратит большую часть бюджета на подтверждение того, что ничего не произошло.
• Отступайте по наблюдаемому сигналу, а не по предполагаемому. Заголовка с остатком квоты в ответах нет, поэтому считайте расход сами, а 429 воспринимайте как данные: наши замеры ниже показывают, что восстановление намного короче, чем подсказывает формулировка «в минуту».

Наш тест: сколько кошельков обслуживает один адрес

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

Окружение и профиль нагрузки. Адреса PapaProxy.net по SOCKS5 с IP whitelisting, цель — публичный POST /info на api.hyperliquid.xyz; без ключей и подписи, адреса кошельков взяты из ответа самого лидерборда. Датацентровый и ISP-пулы прогонялись отдельными сериями и нигде не сводились в общую цифру. Число одновременных запросов с адреса наращивали ступенями по 150 секунд — каждая покрывает полную минуту по часам, — а лестницу останавливали на первом HTTP 429. Прогон 6–7 августа 2026 года.

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

Применение лимита началось заметно выше номинальной арифметики. Бюджет 1 200 весов в минуту при весе 2 подразумевает 600 вызовов; первый отказ пришёл примерно вдвое позже, и тот же рисунок повторился на каждом эндпоинте, где удалось достичь лимита:

Во всех четырёх случаях израсходованный бюджет оказался в 1,8–2,3 раза выше документированных 1 200. Измеренное поведение в целом сохранило документированные весовые уровни, но точка первого 429 заметно менялась между прогонами и эндпоинтами — около 21% между двумя эндпоинтами веса 2 на одном пуле.

И вот вывод, который важнее самого запаса. Темп, на котором мы остановились для устойчивой многоадресной работы, — 574 вызова в минуту с датацентрового адреса — оказался близок к документированной плановой цифре в 600. То есть документация остаётся разумной базой для планирования мощности, а дополнительный запас до первого отказа правильнее считать допуском на всплески, а не той мощностью, на которой можно сэкономить при покупке.

Три находки, которые меняют то, как вы пишете клиент. Остаток квоты не отдаётся: ни один ответ не нёс заголовка с лимитом — ни при успехе, ни при 429, — поэтому ведите собственный счётчик по документированным весам, а 429 сообщает лишь о том, что применение лимита уже наступило. Восстановление в этих прогонах было быстрым: после 429 адрес снова отвечал через 5,3–5,4 секунды. Считайте это наблюдением, а не гарантированным периодом остывания, и сохраняйте и отступление, и собственный учёт весов. И лимит считается по адресу, а не по подсети: четыре адреса внутри одной /24 держали 2 278 вызовов в минуту на датацентре против 2 274 у четырёх адресов из разных /24 (2 052 против 2 044 на ISP), причём отказов не было ни в одной группе, — покупать адреса вразброс по блокам смысла нет.

Одна аномалия, которую мы не объяснили. В пересчёте на документированные веса три потолка из четырёх собираются вокруг 2 500 (±12%). Но allMids с датацентра прошёл 1 622 вызова в минуту — 3 244 веса — вообще без отказа, тогда как тот же вызов с ISP упёрся в 429 уже на 1 089. Разрыв смотрит в сторону, обратную результату по clearinghouseState, так что систематического преимущества пула здесь не видно. Правдоподобные объяснения по убыванию: потолок не константа и меняется от прогона к прогону; более крупный ответ allMids не дал набрать нужный темп до конца лестницы; лимит на этом эндпоинте считается иначе. Наши данные их не различают. Практический урок важнее самой загадки: потолок — не константа, поэтому не планируйте вплотную к измеренному максимуму, оставляйте запас.

Устойчивая рабочая точка. Это и есть число для планирования — то, которое мы держали, а не то, на котором сломалось:

Совокупная пропускная способность росла вместе с числом адресов: строго линейно до пяти адресов и близко к линейному дальше. Один вызов clearinghouseState равен одному кошельку, поэтому нужное число адресов равно «кошельки, делённые на интервал обновления»:

Проще говоря: один адрес обслуживает примерно 574 кошелька при обновлении раз в минуту, 287 — раз в 30 секунд и 95 — раз в 10 секунд. То есть паре сотен кошельков при обновлении раз в полминуты хватит ровно одного адреса, а пяти тысячам понадобится девять даже при неспешном минутном цикле — и больше полусотни при десятисекундном. А если вы используете общерыночный поток сделок для обнаружения изменений, эти числа описывают вашу сверку, а не таймер по каждому кошельку, — и счёт обычно получается заметно меньше.

К чему это приводит связку, с которой статья началась? Всё, что до нескольких сотен кошельков, — задача программная: кешировать лидерборд, фильтровать поток сделок вместо опроса каждого кошелька, разнести оставшийся опрос по уровням и отступать по собственному счётчику. Дальше ограничением становится документированный поадресный бюджет, и мощность добавляется так же, как добавляются воркеры: новыми исходящими адресами, у каждого свой бюджет, а их число считается по таблице выше. Ровно эту часть закрывают наши выделенные прокси — выделенные IPv4-адреса от одного IP, статичные на весь срок плана: адрес закреплён за вами, а непрерывные блоки штрафа не несут, раз лимит считается по адресу. Перед масштабированием парка опроса сверьтесь с актуальными условиями использования площадки, а вызов лидерборда держите вне быстрого цикла независимо от того, сколько у вас адресов.