Онбординг

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

Огляд

Hypercall використовує модель «менеджер і API-гаманець»:

• Менеджер: EOA, що створює акаунт (Account) і володіє ним (зазвичай це ваш основний гаманець).
• Акаунт (Account): контракт 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. Функція списує нативний HyperEVM USDC з msg.sender на Exchange, а потім вносить його на баланс Exchange у HyperCore через CoreDepositWallet від Circle.

Хто може викликати:

• Будь-який гаманець, роутер, солвер або zap-контракт.
• msg.sender сплачує USDC.
• 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);

Функція Router deposit(account, token, amount, isPerp) є загальним помічником, який застосунок використовує для USDC, спотових токенів і опціонних токенів.

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

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

• account має бути зареєстрованим акаунтом Hypercall.
• token має бути підтримуваним опціоном в Option Registry.
• Спалює amount з msg.sender (спершу надайте дозвіл 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), перш ніж він зможе торгувати перпами.