Hyperliquid Webhook: полный разбор схем интеграции

При создании систем автоматической торговли событийная архитектура обычно эффективнее, чем постоянный polling через REST. В случае с Hyperliquid важно понимать: протокол не предоставляет классический HTTP Webhook «из коробки». Поэтому разработчикам приходится добиваться похожего эффекта через WebSocket-подписки или прослушивание on-chain событий, а затем пересылать события на собственный HTTP endpoint.

Ниже разберём основные способы «превратить» Hyperliquid в webhook-based систему и покажем практические примеры кода.

Зачем нужен Webhook-подход

Основные проблемы классического REST polling:

• частые запросы тратят bandwidth и вычислительные ресурсы;
• интервал polling неизбежно добавляет задержку реакции на событие;
• при мониторинге нескольких аккаунтов количество запросов растёт почти линейно.

Преимущества Webhook / event-driven архитектуры:

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

Официальная WebSocket-документация Hyperliquid — ключевой ориентир для построения событийной архитектуры.

Схема 1: WebSocket-подписка → HTTP Webhook

Это самый распространённый вариант. Ты запускаешь локально или в облаке небольшой bridge-сервис: он подписывается на Hyperliquid WebSocket, получает события, форматирует их и отправляет HTTP POST дальше — например, в торгового бота, систему алертов или сервис записи в базу данных.

Архитектура:

Hyperliquid WS --> [Bridge-сервис] --> HTTP POST --> [Downstream consumer]

Пример bridge-сервиса на Python + FastAPI:

import asyncio
import json
import httpx
import websockets
from fastapi import FastAPI
import threading

app = FastAPI()

WEBHOOK_TARGET = "https://your-downstream-service.example.com/events"
WS_URL = "wss://api.hyperliquid.xyz/ws"

async def ws_to_webhook(user_address: str):
    async with websockets.connect(WS_URL) as ws:
        # Подписка на обновления ордеров пользователя
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Подписка на сделки пользователя
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "userFills", "user": user_address}
        }))

        async for raw in ws:
            event = json.loads(raw)
            async with httpx.AsyncClient() as client:
                await client.post(WEBHOOK_TARGET, json=event, timeout=5)

@app.on_event("startup")
def start_ws_listener():
    user_addr = "0xYOUR_ADDRESS"
    thread = threading.Thread(
        target=asyncio.run,
        args=(ws_to_webhook(user_addr),),
        daemon=True
    )
    thread.start()

Схема 2: serverless-функции

Для низкочастотных событий — например, ежедневной или почасовой сводки по funding rate — вместо постоянного WebSocket-соединения можно использовать serverless-функции. Cloud function, например AWS Lambda или Cloudflare Workers, просыпается по расписанию, запрашивает Hyperliquid REST API, обрабатывает данные и отправляет результат в Slack, Telegram или внутреннюю систему.

Пример Cloudflare Worker, который запускается по cron каждый час:

export default {
  async scheduled(event, env, ctx) {
    const resp = await fetch("https://api.hyperliquid.xyz/info", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ type: "metaAndAssetCtxs" }),
    });

    const [meta, ctxs] = await resp.json();

    // Ищем монеты, у которых funding rate выше 0.05% по модулю
    const highFunding = ctxs
      .map((ctx, i) => ({ coin: meta.universe[i].name, rate: parseFloat(ctx.funding) }))
      .filter(x => Math.abs(x.rate) > 0.0005);

    if (highFunding.length > 0) {
      await fetch(env.SLACK_WEBHOOK_URL, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `Алерт по высокому funding rate: ${highFunding.map(x => `${x.coin} ${(x.rate*100).toFixed(4)}%`).join(", ")}`
        }),
      });
    }
  }
};

Схема 3: прослушивание on-chain событий

Поскольку торговые данные Hyperliquid записываются on-chain, теоретически можно получать полную историю операций через прослушивание событий в сети. Документация Hyperliquid предоставляет EVM-совместимый RPC-интерфейс, поэтому можно использовать стандартные Ethereum-инструменты вроде ethers.js или web3.py.

from web3 import Web3

HL_RPC = "https://rpc.hyperliquid.xyz/evm"
w3 = Web3(Web3.HTTPProvider(HL_RPC))

# Обработка новых блоков
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)
    for tx in block.transactions:
        # Фильтрация по адресу контракта Hyperliquid
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"Новая транзакция: {tx['hash'].hex()}")

w3.eth.subscribe("newHeads", handle_new_block)

На практике такой подход больше подходит для индексирования, аудита и построения аналитики. Для реакции на пользовательские ордера и сделки чаще удобнее WebSocket-подписки.

Надёжность: retry и идемпотентность

В продакшене downstream-сервис может быть временно недоступен. Поэтому bridge-сервису нужен механизм повторных попыток:

import tenacity

@tenacity.retry(
    stop=tenacity.stop_after_attempt(3),
    wait=tenacity.wait_exponential(multiplier=1, min=1, max=10),
    reraise=True,
)
async def send_webhook(client: httpx.AsyncClient, url: str, payload: dict):
    resp = await client.post(url, json=payload, timeout=5)
    resp.raise_for_status()

Downstream consumer тоже должен обрабатывать события идемпотентно, чтобы повторная доставка не приводила к двойной обработке. Практичный вариант — добавлять к каждому событию уникальный ID и хранить в базе список уже обработанных ID.

Мониторинг и алерты

Если подключить Webhook-события к системе мониторинга, можно быстро отслеживать важные ситуации:

• события ликвидации (liquidation): сразу отправлять алерт и оценивать, нужно ли пополнять маржу;
• резкие изменения funding rate: проверять, не стали ли издержки по позиции выше ожидаемых;
• отказы ордеров: смотреть, достаточно ли маржи и корректны ли параметры заявки.

Для полноценной панели мониторинга можно использовать Grafana вместе с bridge-сервисом, который получает события из Hyperliquid и пишет метрики в подходящее хранилище.

OneKey Wallet: безопасное исполнение автоматических сделок

Webhook-система автоматизации в итоге часто должна запускать сделки. На этом этапе главный риск — безопасность приватных ключей. Аппаратный кошелёк OneKey даёт аппаратную подпись через USB или Bluetooth: даже если автоматизированный скрипт будет скомпрометирован, злоумышленник не сможет подписать транзакцию без физического устройства.

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

OneKey Perps — практичный вариант execution layer для трейдеров бессрочников. Его можно использовать вместе с твоей Webhook-автоматизацией, чтобы собрать более безопасную и управляемую инфраструктуру для торговли.

Попробуй скачать OneKey и протестировать OneKey Perps на небольших объёмах, прежде чем переносить автоматизацию в продакшен.

FAQ

Q1: Hyperliquid нативно поддерживает HTTP Webhook?

Нет. На текущий момент Hyperliquid не предоставляет встроенные HTTP Webhook. Реальные-time события доступны через WebSocket, а разработчику нужно самостоятельно построить bridge-слой «WS → HTTP».

Q2: Будут ли проблемы с производительностью WebSocket при мониторинге многих аккаунтов?

Для каждого аккаунта нужна отдельная WebSocket-подписка. Для десятков аккаунтов параллельные соединения обычно вполне реалистичны. Для тысяч аккаунтов лучше проектировать connection pool и использовать асинхронный фреймворк, например asyncio.

Q3: Как защитить Webhook-сообщения от подделки?

Если bridge-сервис и downstream consumer находятся под твоим контролем, источник сообщений — твой собственный WebSocket listener, и дополнительная проверка может быть не нужна. Но если Webhook endpoint доступен внешним сторонам, стоит добавить HMAC-подпись и проверку подписи на стороне получателя.

Q4: Хватит ли бесплатного тарифа Cloudflare Workers для мониторинга Hyperliquid?

У бесплатного тарифа Workers есть лимиты по количеству запросов в день — 100 000 запросов/день. Для низкочастотного мониторинга, например запуска раз в час, этого обычно достаточно. Для real-time мониторинга лучше использовать платный тариф или собственный сервер.

Q5: Чем отличаются WebSocket-подписки userFills и orderUpdates?

userFills отправляет детали исполнения, когда ордер был исполнен: цену, объём, комиссии. orderUpdates сообщает об изменении статуса ордера: размещение, частичное исполнение, отмена и другие состояния. Эти подписки дополняют друг друга.

Риск-дисклеймер

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