Подключение

На этой странице описаны жизненный цикл ончейн-аккаунта (Account), пополнение и управление API-кошельками. Адреса контрактов приведены в разделе Контракты, а GET /exchange-info возвращает актуальные адреса Exchange, Factory и роутера депозитов.

Обзор

Hypercall использует модель «менеджер и API-кошелёк»:

• Менеджер: EOA, который создаёт аккаунт и владеет им (обычно это ваш основной кошелёк).
• Аккаунт: контракт BeaconProxy, на котором хранятся ваши балансы и позиции в HyperCore и который исполняет подписанные директивы.
• API-кошелёк: EOA, которому менеджер разрешает на аккаунте подписывать заявки и их отмену.

Аккаунты создаются через Factory. Подписанные директивы отправляет в Exchange секвенсор Hypercall: вы подписываете, Hypercall отправляет.

Жизненный цикл аккаунта

1. Проверка существующих аккаунтов

// Exchange
function getAccounts(address manager) external view returns (ManagedAccount[] memory);

struct ManagedAccount {
    address account;
    address manager;
    ApiWallet[] apiWallets; // { bytes32 name; address addr; }
}

2. Создание аккаунта

// Factory
function createAccount(uint96 salt) external payable returns (address account);
function getCreationDeposit() external view returns (uint256); // in HYPE wei
function predictAccount(address manager, uint96 salt) external view returns (address account, bool exists);

Требования:

• msg.value >= getCreationDeposit(). Factory задаёт депозит за создание в USD и пересчитывает его в HYPE по спотовой цене HyperCore с округлением вверх. В основной сети сейчас это $1,50.
• Если настроен фильтр создания, он должен разрешать msg.sender.

Поведение:

• Разворачивает аккаунт через CREATE2 на основе адреса менеджера и salt, поэтому адрес можно заранее узнать через predictAccount.
• Регистрирует аккаунт в Exchange и назначает msg.sender менеджером.
• Переводит весь msg.value на аккаунт в HyperCore в виде HYPE. Депозит на сумму от $1 активирует аккаунт в HyperCore.

const factory = new ethers.Contract(FACTORY_ADDRESS, FACTORY_ABI, signer);
const salt = 0n;
const [predicted] = await factory.predictAccount(managerAddress, salt);
const value = await factory.getCreationDeposit();
await (await factory.createAccount(salt, { value })).wait();

3. Смена менеджера

Функции передачи прав менеджера нет. Менеджер может смениться только по итогам ончейн-аукциона ликвидации, а в основной сети аукционист не настроен. При смене Exchange генерирует событие AccountTransferred(account, oldManager, newManager), а аккаунт генерирует ManagerSet(oldManager, newManager).

Управление API-кошельками

API-кошельки хранятся на аккаунте под именем типа bytes32. Они подписывают директивы в домене EIP-712 HypercallApiSign. Подробнее в разделе Подпись EIP-712.

Добавление, замена и удаление

Отправьте директиву hc_update_api_wallet, подписанную менеджером в домене HypercallManagerSign:

HCUpdateApiWallet(address account,uint64 nonce,UpdateApiWallet action)UpdateApiWallet(bytes32 name,address addr)

• Новое name добавляет кошелёк. Существующее name заменяет привязанный к нему кошелёк.
• addr = 0x0 удаляет кошелёк с именем name.
• API-кошелёк не может совпадать с менеджером и не может уже быть активным на аккаунте.

Отправьте запрос на POST /v1/actions/hc_update_api_wallet с полями account, nonce, action ({ "name": "0x...", "addr": "0x..." }) и signature. POST /v1/actions/hc_update_api_wallet/typed-data возвращает точные типизированные данные для подписи. Ончейн-результат можно получить, опрашивая GET /v1/directives/{directive_id}. Аккаунт генерирует событие ApiWalletUpdated(name, addr).

Запросы

// Account
function getApiWallets() external view returns (ApiWallet[] memory);
function getApiWallet(bytes32 name) external view returns (address);
function isApiWalletActive(address addr) external view returns (bool);

Пополнение и депозиты

Депозит USDC в Hypercall

// Exchange
function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor это прямой способ пополнить денежный баланс Hypercall из HyperEVM. Функция списывает нативный USDC в HyperEVM с msg.sender в Exchange, а затем зачисляет его на баланс Exchange в HyperCore через CoreDepositWallet от Circle.

Кто может вызывать:

• Любой кошелёк, роутер, солвер или zap-контракт.
• USDC оплачивает msg.sender.
• account это аккаунт или кошелёк Hypercall, на который зачисляются средства. Не определяйте зачисляемый аккаунт по msg.sender.

Требования:

• account != address(0) и amount > 0
• msg.sender выдал Exchange разрешение (approve) на amount USDC

event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

Hypercall зачисляет средства только после сопоставления этого события с зафиксированным депозитом в HyperCore. Средства зачисляются на аккаунт из поля account.

await usdc.approve(EXCHANGE_ADDRESS, amount);
await exchange.depositUsdcFor(accountAddress, amount);

Функция роутера deposit(account, token, amount, isPerp) это универсальный хелпер, который приложение использует для USDC, спотовых токенов и опционных токенов.

Депозит опционных токенов

// Exchange
function depositOption(address account, address token, uint256 amount) external;

• account должен быть зарегистрированным аккаунтом Hypercall.
• token должен быть поддерживаемым опционом в Option Registry.
• Сжигает amount у msg.sender (предварительно выдайте approve для Exchange) и генерирует событие Deposit(account, msg.sender, token, amount), по которому движок зачисляет позицию.

Вывод средств с аккаунта

// Account, manager only
function transferTo(address recipient, address token, uint256 amount) external;

Переводит нативный HYPE (token = 0x0) или ERC20, хранящиеся на аккаунте в HyperEVM, на адрес recipient. Используйте эту функцию, чтобы завершить перевод из HyperCore в HyperEVM или вывести все средства с аккаунта. Недоступна, пока аккаунт находится в ликвидации.

Одобрение билдера для перпов

// Account, manager only
function approveZeroFeeBuilder(address builder) external;

Одобряет билдера Hyperliquid для аккаунта с максимальной комиссией 0%. Каждая перп-заявка Hypercall содержит билдер-код Hypercall, поэтому перед первой перп-заявкой один раз вызовите эту функцию с hl_builder_address из GET /exchange-info. Приложение делает это на шаге Enable trading.

События

// Exchange
event AccountTransferred(address indexed account, address indexed oldManager, address indexed newManager);
event Deposit(address indexed account, address indexed from, address indexed token, uint256 amount);
event Withdraw(address indexed account, address indexed to, address indexed token, uint256 amount);
// Factory
event AccountCreated(address indexed account, address indexed manager);
// Account
event ApiWalletUpdated(bytes32 indexed name, address indexed addr);
event ManagerSet(address indexed oldManager, address indexed newManager);

Ошибки

• Factory__CreationDepositNotMet(uint256 expected): msg.value меньше депозита за создание
• Factory__CreationNotAllowed(): заблокировано фильтром создания
• Exchange__AccountDoesNotExist(address account): аккаунт не зарегистрирован
• Exchange__TokenNotSupported(address token): опционный токен не поддерживается
• Account__NotManager(address addr): вызывающий адрес или подписант не является менеджером
• Account__ApiWalletNotActive(address addr): подписант не является активным API-кошельком
• Account__ApiWalletAlreadyActive(address addr): API-кошелёк уже привязан к аккаунту
• Account__ApiWalletIsManager(): менеджер не может быть собственным API-кошельком
• Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce уже использован
• Account__LiquidationInProgress(): действие заблокировано на время ликвидации

Безопасность

1. Ключ менеджера: управляет API-кошельками, выводом средств и одобрением билдера. Храните его на аппаратном кошельке.
2. Ключи API-кошельков: позволяют только подписывать заявки и их отмену. Используйте отдельные ключи для каждой системы и регулярно их меняйте.
3. Nonce: у каждого подписанта своё пространство nonce. Используйте временные метки в миллисекундах и отслеживайте их на своей стороне.
4. Активация: перед торговлей перпами аккаунт должен быть активирован в HyperCore (депозит HYPE на сумму не менее $1).