Intégration

Cette page couvre le cycle de vie du compte (Account) on-chain, son approvisionnement et la gestion des portefeuilles API. Les adresses figurent sur la page Contrats, et GET /exchange-info renvoie les adresses en vigueur de l'Exchange, de la Factory et du routeur de dépôt.

Vue d'ensemble

Hypercall repose sur un modèle gestionnaire (manager) et portefeuille API :

• Manager : l'EOA qui crée l'Account et en est propriétaire (généralement votre portefeuille principal).
• Account : un contrat BeaconProxy qui détient vos soldes et positions HyperCore et exécute les directives signées.
• Portefeuille API : une EOA que le manager autorise sur l'Account à signer des ordres et des annulations.

Les Accounts sont créés par la Factory. Les directives signées sont soumises à l'Exchange par le séquenceur d'Hypercall : vous signez, Hypercall soumet.

Cycle de vie de l'Account

1. Vérifier les Accounts existants

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

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

2. Créer un Account

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

Conditions :

• msg.value >= getCreationDeposit(). La Factory fixe le dépôt de création en USD et le convertit en HYPE au prix spot HyperCore, arrondi à la hausse. Sur le réseau principal, il s'élève actuellement à 1,50 $.
• Si un filtre de création est configuré, il doit autoriser msg.sender.

Comportement :

• Déploie l'Account avec CREATE2 à partir de l'adresse du manager et de salt, de sorte que l'adresse est connue à l'avance via predictAccount.
• Enregistre l'Account auprès de l'Exchange et définit msg.sender comme manager.
• Transfère tout msg.value vers l'Account sur HyperCore sous forme de HYPE. Un dépôt d'au moins 1 $ active l'Account sur 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. Changements de manager

Il n'existe aucune fonction de transfert du manager. Le manager ne peut changer que lors du dénouement d'une enchère de liquidation on-chain, et aucun commissaire-priseur (auctioneer) n'est configuré sur le réseau principal. Lors d'un changement, l'Exchange émet AccountTransferred(account, oldManager, newManager) et l'Account émet ManagerSet(oldManager, newManager).

Gestion des portefeuilles API

Les portefeuilles API sont stockés sur l'Account, indexés par un nom bytes32. Ils signent les directives dans le domaine EIP-712 HypercallApiSign. Voir Signature EIP-712.

Ajouter, remplacer ou supprimer

Soumettez une directive hc_update_api_wallet signée par le manager dans le domaine HypercallManagerSign :

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

• Un nouveau name ajoute un portefeuille. Un name existant remplace son portefeuille.
• addr = 0x0 supprime le portefeuille associé à name.
• Le portefeuille API ne peut pas être le manager et ne peut pas déjà être actif sur l'Account.

Envoyez-la à POST /v1/actions/hc_update_api_wallet avec account, nonce, action ({ "name": "0x...", "addr": "0x..." }) et signature. POST /v1/actions/hc_update_api_wallet/typed-data renvoie les données typées exactes à signer. Interrogez GET /v1/directives/{directive_id} pour obtenir le résultat on-chain. L'Account émet ApiWalletUpdated(name, addr).

Consultation

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

Approvisionnement et dépôts

Dépôt d'USDC sur Hypercall

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

depositUsdcFor est le chemin d'approvisionnement direct depuis HyperEVM pour le cash Hypercall. Il prélève l'USDC natif HyperEVM de msg.sender vers l'Exchange, puis le dépose sur le solde HyperCore de l'Exchange via le CoreDepositWallet de Circle.

Qui peut l'appeler :

• N'importe quel portefeuille, routeur, solveur ou contrat zap.
• msg.sender paie l'USDC.
• account est le compte ou portefeuille Hypercall à créditer. Ne déduisez pas le compte crédité de msg.sender.

Conditions :

• account != address(0) et amount > 0
• msg.sender a approuvé l'Exchange pour amount USDC

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

Hypercall ne crédite le cash qu'après avoir rapproché cet événement du dépôt HyperCore observé. Le compte crédité est celui du champ account.

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

La fonction deposit(account, token, amount, isPerp) du Router est l'utilitaire générique employé par l'application pour l'USDC, les tokens spot et les tokens d'options.

Dépôt de tokens d'options

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

• account doit être un Account Hypercall enregistré.
• token doit être une option prise en charge dans l'Option Registry.
• Brûle amount depuis msg.sender (approuvez d'abord l'Exchange) et émet Deposit(account, msg.sender, token, amount), que le moteur crédite.

Transfert hors de l'Account

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

Transfère le HYPE natif (token = 0x0) ou un ERC20 détenu par l'Account sur HyperEVM vers recipient. Utilisez-la pour finaliser les transferts de HyperCore vers HyperEVM ou pour vider l'Account. Indisponible tant que l'Account est en liquidation.

Approbation du builder pour les perpétuels

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

Approuve un builder Hyperliquid pour l'Account avec des frais maximaux de 0 %. Chaque ordre perpétuel Hypercall porte le code builder Hypercall : appelez donc cette fonction une fois avec le hl_builder_address renvoyé par GET /exchange-info avant le premier ordre perpétuel. L'application s'en charge lors de son étape Enable trading.

Événements

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

Erreurs

• Factory__CreationDepositNotMet(uint256 expected) : msg.value inférieur au dépôt de création
• Factory__CreationNotAllowed() : bloqué par le filtre de création
• Exchange__AccountDoesNotExist(address account) : pas un Account enregistré
• Exchange__TokenNotSupported(address token) : pas un token d'option pris en charge
• Account__NotManager(address addr) : l'appelant ou le signataire n'est pas le manager
• Account__ApiWalletNotActive(address addr) : le signataire n'est pas un portefeuille API actif
• Account__ApiWalletAlreadyActive(address addr) : portefeuille API déjà présent sur l'Account
• Account__ApiWalletIsManager() : le manager ne peut pas être son propre portefeuille API
• Account__NonceAlreadyUsed(address signer, uint256 nonce) : nonce réutilisé
• Account__LiquidationInProgress() : action bloquée pendant la liquidation

Considérations de sécurité

1. Clé du manager : contrôle les portefeuilles API, les transferts sortants et l'approbation du builder. Utilisez un portefeuille matériel.
2. Clés des portefeuilles API : signent uniquement les ordres et les annulations. Utilisez des clés distinctes pour chaque système et renouvelez-les régulièrement.
3. Nonces : chaque signataire dispose de son propre espace de nonces. Utilisez des horodatages en millisecondes et suivez-les off-chain.
4. Activation : l'Account doit être activé sur HyperCore (au moins 1 $ de HYPE déposé) avant de pouvoir négocier des perpétuels.