Onboarding

Esta página describe el ciclo de vida on-chain de la Account, el fondeo y la gestión de API wallets. Las direcciones figuran en Contratos, y GET /exchange-info devuelve las direcciones vigentes del Exchange, la Factory y el router de depósitos.

Descripción general

Hypercall utiliza un modelo de manager y API wallet:

• Manager: la EOA que crea y es propietaria de la Account (normalmente su wallet principal).
• Account: un contrato BeaconProxy que mantiene sus saldos y posiciones en HyperCore y ejecuta directivas firmadas.
• API wallet: una EOA que el manager autoriza en la Account para firmar órdenes y cancelaciones.

Las Accounts se crean mediante la Factory. El secuenciador de Hypercall envía las directivas firmadas al Exchange: usted firma y Hypercall las envía.

Ciclo de vida de la Account

1. Consultar Accounts existentes

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

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

2. Crear una 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);

Requisitos:

• msg.value >= getCreationDeposit(). La Factory fija el depósito de creación en USD y lo convierte a HYPE al precio spot de HyperCore, redondeando hacia arriba. En mainnet es actualmente de $1.50.
• Si hay un filtro de creación configurado, este debe permitir a msg.sender.

Comportamiento:

• Despliega la Account con CREATE2 a partir de la dirección del manager y el salt, por lo que la dirección se conoce de antemano mediante predictAccount.
• Registra la Account en el Exchange y establece a msg.sender como manager.
• Transfiere cualquier msg.value a la Account en HyperCore como HYPE. Un depósito de al menos $1 activa la Account en 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. Cambios de manager

No existe una función de transferencia de manager. El manager solo puede cambiar cuando se resuelve una subasta de liquidación on-chain, y en mainnet no hay ningún subastador configurado. Cuando se produce un cambio, el Exchange emite AccountTransferred(account, oldManager, newManager) y la Account emite ManagerSet(oldManager, newManager).

Gestión de API wallets

Las API wallets se almacenan en la Account, indexadas por un nombre bytes32. Firman directivas en el dominio EIP-712 HypercallApiSign. Consulte Firma EIP-712.

Agregar, reemplazar o eliminar

Envíe una directiva hc_update_api_wallet firmada por el manager en el dominio HypercallManagerSign:

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

• Un name nuevo agrega una wallet. Un name existente reemplaza su wallet.
• addr = 0x0 elimina la wallet asociada a name.
• La API wallet no puede ser el manager ni estar ya activa en la Account.

Envíela a POST /v1/actions/hc_update_api_wallet con account, nonce, action ({ "name": "0x...", "addr": "0x..." }) y signature. POST /v1/actions/hc_update_api_wallet/typed-data devuelve los datos tipados exactos que debe firmar. Consulte GET /v1/directives/{directive_id} para obtener el resultado on-chain. La Account emite ApiWalletUpdated(name, addr).

Consultas

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

Fondeo y depósitos

Depósito de USDC en Hypercall

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

depositUsdcFor es la vía directa de fondeo en HyperEVM para el efectivo de Hypercall. Toma USDC nativo de HyperEVM desde msg.sender hacia el Exchange y luego lo deposita en el saldo de HyperCore del Exchange mediante el CoreDepositWallet de Circle.

Quién puede llamarla:

• Cualquier wallet, router, solver o contrato zap.
• msg.sender paga los USDC.
• account es la cuenta o wallet de Hypercall que se acreditará. No deduzca la cuenta acreditada a partir de msg.sender.

Requisitos:

• account != address(0) y amount > 0
• msg.sender ha aprobado al Exchange por amount USDC

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

Hypercall acredita el efectivo solo después de cotejar este evento con el depósito observado en HyperCore. La cuenta acreditada es la del campo account.

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

La función deposit(account, token, amount, isPerp) del Router es el helper general que usa la app para USDC, tokens spot y tokens de opciones.

Depósito de tokens de opciones

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

• account debe ser una Account de Hypercall registrada.
• token debe ser una opción admitida en el Option Registry.
• Quema amount desde msg.sender (apruebe primero al Exchange) y emite Deposit(account, msg.sender, token, amount), que el motor acredita.

Transferencias desde la Account

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

Mueve HYPE nativo (token = 0x0) o un ERC20 que la Account mantiene en HyperEVM hacia recipient. Úsela para completar transferencias de HyperCore a HyperEVM o para vaciar la Account. No está disponible mientras la Account está en liquidación.

Aprobación del builder para perpetuos

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

Aprueba un builder de Hyperliquid para la Account con una comisión máxima del 0%. Toda orden de perpetuos de Hypercall lleva el código de builder de Hypercall, así que llame a esta función una vez con el hl_builder_address de GET /exchange-info antes de la primera orden de perpetuos. La app lo hace en su paso Habilitar trading.

Eventos

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

Errores

• Factory__CreationDepositNotMet(uint256 expected): msg.value es inferior al depósito de creación
• Factory__CreationNotAllowed(): bloqueado por el filtro de creación
• Exchange__AccountDoesNotExist(address account): no es una Account registrada
• Exchange__TokenNotSupported(address token): no es un token de opción admitido
• Account__NotManager(address addr): quien llama o firma no es el manager
• Account__ApiWalletNotActive(address addr): el firmante no es una API wallet activa
• Account__ApiWalletAlreadyActive(address addr): la API wallet ya está en la Account
• Account__ApiWalletIsManager(): el manager no puede ser su propia API wallet
• Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce reutilizado
• Account__LiquidationInProgress(): acción bloqueada durante la liquidación

Consideraciones de seguridad

1. Clave del manager: controla las API wallets, las transferencias de salida y la aprobación del builder. Use una hardware wallet.
2. Claves de API wallets: solo firman órdenes y cancelaciones. Use claves separadas para cada sistema y rótelas.
3. Nonces: cada firmante tiene su propio espacio de nonces. Use timestamps en milisegundos y regístrelos off-chain.
4. Activación: la Account debe estar activada en HyperCore (con al menos $1 de HYPE depositado) antes de poder operar perpetuos.