Onboarding

Diese Seite behandelt den On-Chain-Lebenszyklus eines Accounts, die Finanzierung und die Verwaltung von API-Wallets. Die Adressen finden Sie unter Contracts, und GET /exchange-info liefert die aktuellen Adressen von Exchange, Factory und Deposit-Router.

Überblick

Hypercall verwendet ein Modell aus Manager und API-Wallet:

• Manager: das EOA, das den Account erstellt und besitzt (in der Regel Ihre Haupt-Wallet).
• Account: ein BeaconProxy-Contract, der Ihre HyperCore-Guthaben und -Positionen hält und signierte Direktiven ausführt.
• API-Wallet: ein EOA, das der Manager auf dem Account autorisiert, um Orders und Stornierungen zu signieren.

Accounts werden von der Factory erstellt. Signierte Direktiven reicht der Sequencer von Hypercall bei der Exchange ein: Sie signieren, Hypercall reicht ein.

Lebenszyklus eines Accounts

1. Bestehende Accounts prüfen

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

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

2. Account erstellen

// 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);

Voraussetzungen:

• msg.value >= getCreationDeposit(). Die Factory legt die Erstellungseinlage in USD fest und rechnet sie zum HyperCore-Spotpreis in HYPE um, aufgerundet. Im Mainnet beträgt sie derzeit 1,50 $.
• Ist ein Erstellungsfilter konfiguriert, muss er msg.sender zulassen.

Verhalten:

• Deployt den Account per CREATE2 aus der Manager-Adresse und salt, sodass die Adresse über predictAccount vorab bekannt ist.
• Registriert den Account bei der Exchange und setzt msg.sender als Manager.
• Überträgt den gesamten msg.value als HYPE per Bridge an den Account auf HyperCore. Eine Einzahlung im Wert von mindestens 1 $ aktiviert den Account auf 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. Wechsel des Managers

Es gibt keine Funktion zur Übertragung des Managers. Der Manager kann sich nur ändern, wenn eine On-Chain-Liquidationsauktion abgeschlossen wird, und im Mainnet ist kein Auktionator konfiguriert. Bei einem Wechsel emittiert die Exchange AccountTransferred(account, oldManager, newManager) und der Account emittiert ManagerSet(oldManager, newManager).

Verwaltung von API-Wallets

API-Wallets werden auf dem Account gespeichert, adressiert über einen bytes32-Namen. Sie signieren Direktiven in der EIP-712-Domain HypercallApiSign. Siehe EIP-712-Signierung.

Hinzufügen, Ersetzen oder Entfernen

Reichen Sie eine hc_update_api_wallet-Direktive ein, die der Manager in der Domain HypercallManagerSign signiert hat:

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

• Ein neuer name fügt eine Wallet hinzu. Ein bestehender name ersetzt dessen Wallet.
• addr = 0x0 entfernt die Wallet unter name.
• Die API-Wallet darf nicht der Manager sein und darf nicht bereits auf dem Account aktiv sein.

Senden Sie sie an POST /v1/actions/hc_update_api_wallet mit account, nonce, action ({ "name": "0x...", "addr": "0x..." }) und signature. POST /v1/actions/hc_update_api_wallet/typed-data liefert die exakten Typed Data zum Signieren. Fragen Sie GET /v1/directives/{directive_id} ab, um das On-Chain-Ergebnis zu erhalten. Der Account emittiert ApiWalletUpdated(name, addr).

Abfrage

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

Finanzierung und Einzahlungen

USDC-Einzahlung bei Hypercall

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

depositUsdcFor ist der direkte HyperEVM-Finanzierungsweg für Hypercall-Guthaben. Die Funktion zieht natives HyperEVM-USDC von msg.sender in die Exchange und zahlt es anschließend über Circles CoreDepositWallet in das HyperCore-Guthaben der Exchange ein.

Wer sie aufrufen darf:

• Jede Wallet, jeder Router, Solver oder Zap-Contract.
• msg.sender bezahlt das USDC.
• account ist der Hypercall-Account oder die Wallet, die gutgeschrieben wird. Leiten Sie den gutgeschriebenen Account nicht aus msg.sender ab.

Voraussetzungen:

• account != address(0) und amount > 0
• msg.sender hat die Exchange für amount USDC freigegeben (Approve)

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

Hypercall schreibt Guthaben erst gut, nachdem dieses Event der beobachteten HyperCore-Einzahlung zugeordnet wurde. Gutgeschrieben wird der Account im Feld account.

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

deposit(account, token, amount, isPerp) des Routers ist der allgemeine Helfer, den die App für USDC, Spot-Token und Options-Token verwendet.

Einzahlung von Options-Token

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

• account muss ein registrierter Hypercall-Account sein.
• token muss eine unterstützte Option in der Option Registry sein.
• Verbrennt amount von msg.sender (geben Sie zuvor die Exchange frei) und emittiert Deposit(account, msg.sender, token, amount), das die Engine gutschreibt.

Übertragung aus dem Account

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

Überträgt natives HYPE (token = 0x0) oder einen ERC20-Token, den der Account auf HyperEVM hält, an recipient. Verwenden Sie dies, um Übertragungen von HyperCore zu HyperEVM abzuschließen oder den Account zu leeren. Nicht verfügbar, während sich der Account in Liquidation befindet.

Builder-Freigabe für Perps

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

Gibt einen Hyperliquid-Builder für den Account mit einer maximalen Gebühr von 0 % frei. Jede Perp-Order von Hypercall trägt den Hypercall-Builder-Code. Rufen Sie diese Funktion daher vor der ersten Perp-Order einmal mit der hl_builder_address aus GET /exchange-info auf. Die App erledigt dies im Schritt Enable trading.

Events

// 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);

Fehler

• Factory__CreationDepositNotMet(uint256 expected): msg.value liegt unter der Erstellungseinlage
• Factory__CreationNotAllowed(): durch den Erstellungsfilter blockiert
• Exchange__AccountDoesNotExist(address account): kein registrierter Account
• Exchange__TokenNotSupported(address token): kein unterstützter Options-Token
• Account__NotManager(address addr): Aufrufer oder Unterzeichner ist nicht der Manager
• Account__ApiWalletNotActive(address addr): Unterzeichner ist keine aktive API-Wallet
• Account__ApiWalletAlreadyActive(address addr): API-Wallet ist bereits auf dem Account vorhanden
• Account__ApiWalletIsManager(): der Manager kann nicht seine eigene API-Wallet sein
• Account__NonceAlreadyUsed(address signer, uint256 nonce): Nonce wurde wiederverwendet
• Account__LiquidationInProgress(): Aktion während der Liquidation blockiert

Sicherheitshinweise

1. Manager-Schlüssel: kontrolliert API-Wallets, Übertragungen aus dem Account und die Builder-Freigabe. Verwenden Sie eine Hardware-Wallet.
2. API-Wallet-Schlüssel: signieren ausschließlich Orders und Stornierungen. Verwenden Sie pro System separate Schlüssel und rotieren Sie diese.
3. Nonces: Jeder Unterzeichner hat seinen eigenen Nonce-Bereich. Verwenden Sie Zeitstempel in Millisekunden und verfolgen Sie diese off-chain.
4. Aktivierung: Der Account muss auf HyperCore aktiviert sein (mindestens 1 $ in HYPE eingezahlt), bevor er Perps handeln kann.