Интеграция Hyperliquid в кошелёк: полный гайд для разработчиков

6 мая 2026 г.

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

Этот материал — практический обзор для разработчиков кошельков: разберём модель аккаунтов Hyperliquid, схемы подписи, варианты подключения через WalletConnect и SDK, базовый flow выставления ордера, а также ключевые моменты безопасности. Там, где уместно, в качестве практичного ориентира будем использовать подход OneKey Perps: удобная торговля бессрочниками без отказа от аппаратной защиты.

Модель аккаунтов Hyperliquid

Hyperliquid использует EVM-совместимые адреса в формате Ethereum. Пользователь подписывает действия стандартным ECDSA-приватным ключом.

В документации Hyperliquid обычно выделяются два типа адресов:

Vault Address — основной адрес на уровне протокола, которому принадлежат активы.
Agent Address — авторизованный дочерний адрес для подписи операций, который снижает трение при частых торговых действиях.

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

Способы подключения: WalletConnect или прямой SDK

Вариант 1: WalletConnect 2.0

WalletConnect — один из самых распространённых протоколов подключения кошельков. Веб-приложение Hyperliquid нативно поддерживает WalletConnect 2.0.

Типичный flow интеграции:

В приложении кошелька реализуется обработка WalletConnect 2.0 Session Proposal.
Пользователь сканирует QR-код или переходит по deep link.
Кошелёк слушает запросы eth_sendTransaction и personal_sign, после чего возвращает подпись.

Плюс такого подхода — минимальное вмешательство. Кошельку не нужно глубоко понимать внутренний протокол Hyperliquid: достаточно стандартного интерфейса Ethereum-подписей.

Вариант 2: прямой доступ через Hyperliquid Python/JS SDK

Если ты хочешь встроить в кошелёк более глубокие функции — например просмотр позиций, баланса, PnL и выставление ордеров прямо из приложения, — можно использовать SDK.

pip install hyperliquid-python-sdk

# или
npm install @nktkas/hyperliquid

Hyperliquid Python SDK уже инкапсулирует значительную часть логики подписи и отправки запросов. Для JS-интеграции можно использовать доступные SDK и прямые HTTP-вызовы к API.

Подписи: EIP-712 вместо простого eth_sign

Все пишущие операции в Hyperliquid — выставление ордеров, отмена, ввод и вывод средств — используют EIP-712 structured signing, а не простой eth_sign.

Это важно для UX и безопасности:

Кошелёк с поддержкой EIP-712 может показать пользователю понятное содержимое подписи: например «открыть лонг BTC perpetual на 0.01, лимитная цена 65000 USDC».
Кошелёк без нормального отображения EIP-712 часто показывает только hex-данные. Это неудобно и повышает риск подписать не то действие.

При интеграции стоит в первую очередь реализовать корректный парсинг и отображение EIP-712-структур. В качестве ориентира используй стандарт signTypedData_v4 из спецификации EIP-712.

Базовая интеграция API: выставление ордера

Ниже пример на JavaScript: лимитный buy-ордер через прямой вызов Exchange Endpoint.

import { ethers } from "ethers";

const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";

async function placeOrder(wallet, coin, isBuy, price, size) {
  const nonce = Date.now();

  const orderPayload = {
    type: "order",
    orders: [{
      a: 0,          // asset index (0 = BTC)
      b: isBuy,
      p: price.toString(),
      s: size.toString(),
      r: false,      // reduce-only
      t: { limit: { tif: "Gtc" } }
    }],
    grouping: "na"
  };

  // Domain и Types для EIP-712 смотри в официальной документации Hyperliquid
  const signature = await wallet._signTypedData(domain, types, orderPayload);

  const body = {
    action: orderPayload,
    nonce,
    signature,
  };

  const resp = await fetch(EXCHANGE_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  return resp.json();
}

Полные определения Domain и Types нужно брать из официальной документации Hyperliquid для Exchange Endpoint. Не стоит хардкодить их «по памяти»: при изменениях протокола это может привести к ошибкам подписи или некорректному UX.

Запрос баланса и позиций

Чтение состояния аккаунта не требует подписи. Например, можно получить данные через clearinghouseState:

async function getAccountInfo(address) {
  const resp = await fetch("https://api.hyperliquid.xyz/info", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "clearinghouseState",
      user: address,
    }),
  });

  return resp.json();
}

Ответ включает, среди прочего:

marginSummary — доступная маржа, общая стоимость аккаунта и связанные показатели;
assetPositions — детали по позициям;
crossMaintenanceMarginUsed — использованная поддерживающая маржа в cross-режиме.

Эти данные можно использовать для отображения позиций, маржи, нереализованного PnL и риск-параметров прямо в интерфейсе кошелька.

Ключевые требования к безопасности

При интеграции деривативов в кошелёк безопасность должна быть приоритетом. Бессрочники, плечо и автоматизированные подписи быстро увеличивают риск, если UX или архитектура сделаны неаккуратно.

1. Изоляция приватного ключа

Подпись сделок должна происходить в защищённой среде: Secure Enclave, TEE или на аппаратном устройстве. Приватный ключ нельзя передавать в application layer и тем более хранить рядом с торговой логикой.

Для аппаратного подхода можно ориентироваться на открытую архитектуру OneKey: приватный ключ остаётся изолированным, а приложение получает только результат подписи.

2. Повторное подтверждение суммы и параметров сделки

Перед отправкой ордера пользователь должен видеть понятный экран подтверждения:

актив;
направление: long или short;
размер позиции;
цену;
тип ордера;
reduce-only, если применимо;
плечо;
ориентировочную цену ликвидации, если она доступна.

Не показывай пользователю только raw JSON или hex-подпись. Для деривативов это особенно опасно.

3. Ограничение прав Agent Address

Если используется Agent-режим, интерфейс должен ясно показывать:

какой Agent Address авторизован;
какие действия он может выполнять;
как его отозвать;
когда была выдана авторизация.

Agent обычно используется для автоматизации или частых торговых операций. Его преимущество в том, что он снижает радиус ущерба: такой адрес может выполнять ограниченные действия, например выставлять ордера, но не должен иметь возможность выводить средства.

4. Защита от replay-атак

Используй nonce-механику Hyperliquid и следи, чтобы nonce для каждой операции монотонно увеличивался. Это снижает риск повторного воспроизведения старых подписанных действий.

Рекомендуемая архитектура: ориентир на OneKey и OneKey Perps

OneKey hardware wallet поддерживает Ethereum EIP-712 signatures, а открытые SDK дают разработчикам доступ к API структурированной подписи. Это делает архитектуру OneKey удобной отправной точкой для интеграции EVM-совместимых деривативных протоколов, включая Hyperliquid.

Если твоя команда хочет дать пользователям торговлю бессрочниками внутри кошелька, стоит посмотреть на подход OneKey Perps: торговый интерфейс остаётся быстрым и удобным, но критичные операции подписи не выносятся из безопасного контура.

Практичный workflow может выглядеть так:

Пользователь подключает OneKey.
В интерфейсе OneKey Perps он смотрит рынок, позиции и маржу.
Перед сделкой кошелёк показывает читаемые EIP-712-данные.
Подпись подтверждается пользователем через защищённый контур.
Ордер отправляется в Hyperliquid API.

Если тебе нужен готовый пользовательский путь для торговли бессрочниками с акцентом на self-custody, попробуй скачать OneKey и протестировать OneKey Perps. Это не обещание доходности и не инвестиционная рекомендация, а практичный способ оценить UX и архитектуру безопасной торговли криптой с плечом.

Частые вопросы

Q1: Какие способы подключения кошельков поддерживает Hyperliquid?

Hyperliquid нативно поддерживает MetaMask, WalletConnect 2.0-совместимые кошельки, а также программный доступ через прямую подпись приватным ключом. В теории любой Ethereum-кошелёк, который умеет делать ECDSA-подписи, может быть интегрирован.

Q2: Чем Agent Address отличается от основного адреса?

Agent Address — это дочерний адрес подписи, авторизованный основным адресом. Обычно он используется для торговых ботов или частых операций. Agent может выполнять ограниченные действия, например выставлять ордера, но не должен иметь права вывода средств. Это уменьшает потенциальный ущерб при компрометации Agent-ключа.

Q3: Нужно ли получать разрешение у команды Hyperliquid для интеграции API?

Hyperliquid — permissionless-протокол. Info Endpoint публичен. Для пишущих операций через Exchange Endpoint нужна валидная EIP-712-подпись, но отдельное разрешение, whitelist или API-лицензия не требуются.

Q4: Как показать нереализованный PnL в интерфейсе кошелька?

В ответе clearinghouseState поле assetPositions содержит данные по каждой позиции. Для отображения нереализованной прибыли или убытка используй поле unrealizedPnl. Значение номинировано в USDC.

Q5: Какой endpoint использовать для тестнета?

Для тестовой сети Hyperliquid используется:

https://api.hyperliquid-testnet.xyz/

Его можно применять на этапе разработки и QA без работы с реальными средствами.

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

Этот материал предназначен для технического ознакомления и не является инвестиционной, юридической или финансовой рекомендацией. Торговля бессрочниками связана с высоким риском, особенно при использовании плеча. Перед production-интеграцией разработчикам нужно внимательно изучить правила протокола, подписи, маржинальную модель и сценарии отказа.