Onboarding

Esta página cobre o ciclo de vida da Account on-chain, o financiamento e o gerenciamento de carteiras de API. Os endereços estão em Contratos, e GET /exchange-info retorna os endereços ativos da Exchange, da Factory e do roteador de depósitos.

Visão geral

A Hypercall usa um modelo de manager e carteira de API:

• Manager: a EOA que cria e é dona da Account (geralmente sua carteira principal).
• Account: um contrato BeaconProxy que mantém seus saldos e posições na HyperCore e executa diretivas assinadas.
• Carteira de API: uma EOA que o manager autoriza na Account para assinar ordens e cancelamentos.

As Accounts são criadas pela Factory. As diretivas assinadas são enviadas à Exchange pelo sequenciador da Hypercall. Você assina e a Hypercall envia.

Ciclo de vida da Account

1. Verificar 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. Criar 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(). A Factory define o depósito de criação em USD e o converte para HYPE pelo preço spot da HyperCore, arredondando para cima. Na mainnet, ele é atualmente de $1,50.
• Se houver um filtro de criação configurado, ele precisa permitir msg.sender.

Comportamento:

• Implanta a Account com CREATE2 a partir do endereço do manager e do salt, de modo que o endereço é conhecido antecipadamente por meio de predictAccount.
• Registra a Account na Exchange e define msg.sender como manager.
• Faz a ponte de qualquer msg.value para a Account na HyperCore como HYPE. Um depósito de pelo menos $1 ativa a Account na 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. Mudanças de manager

Não existe função de transferência de manager. O manager só pode mudar quando um leilão de liquidação on-chain é resolvido, e não há leiloeiro configurado na mainnet. Em uma mudança, a Exchange emite AccountTransferred(account, oldManager, newManager) e a Account emite ManagerSet(oldManager, newManager).

Gerenciamento de carteiras de API

As carteiras de API ficam armazenadas na Account, indexadas por um nome bytes32. Elas assinam diretivas no domínio EIP-712 HypercallApiSign. Veja Assinatura EIP-712.

Adicionar, substituir ou remover

Envie uma diretiva hc_update_api_wallet assinada pelo manager no domínio HypercallManagerSign:

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

• Um name novo adiciona uma carteira. Um name existente substitui a carteira correspondente.
• addr = 0x0 remove a carteira registrada sob name.
• A carteira de API não pode ser o manager e não pode já estar ativa na Account.

Envie para POST /v1/actions/hc_update_api_wallet com account, nonce, action ({ "name": "0x...", "addr": "0x..." }) e signature. POST /v1/actions/hc_update_api_wallet/typed-data retorna exatamente os dados tipados a serem assinados. Consulte GET /v1/directives/{directive_id} para obter o resultado on-chain. A Account emite ApiWalletUpdated(name, addr).

Consulta

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

Financiamento e depósitos

Depósito de USDC na Hypercall

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

depositUsdcFor é o caminho direto de financiamento via HyperEVM para o saldo em caixa da Hypercall. Ele puxa USDC nativo da HyperEVM de msg.sender para a Exchange e depois o deposita no saldo da Exchange na HyperCore por meio do CoreDepositWallet da Circle.

Quem pode chamar:

• Qualquer carteira, roteador, solver ou contrato de zap.
• msg.sender paga o USDC.
• account é a conta ou carteira da Hypercall a ser creditada. Não deduza a conta creditada a partir de msg.sender.

Requisitos:

• account != address(0) e amount > 0
• msg.sender aprovou a Exchange para amount USDC

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

A Hypercall só credita o saldo depois de casar esse evento com o depósito observado na HyperCore. A conta creditada é a do campo account.

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

O deposit(account, token, amount, isPerp) do Router é o helper genérico usado pelo app para USDC, tokens spot e tokens de opção.

Depósito de token de opção

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

• account precisa ser uma Account registrada na Hypercall.
• token precisa ser uma opção suportada no Option Registry.
• Queima amount de msg.sender (aprove a Exchange antes) e emite Deposit(account, msg.sender, token, amount), que o engine credita.

Transferência para fora da Account

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

Move HYPE nativo (token = 0x0) ou um ERC20 mantido pela Account na HyperEVM para recipient. Use para concluir transferências da HyperCore para a HyperEVM ou para esvaziar a Account. Não está disponível enquanto a Account estiver em liquidação.

Aprovação de builder para perpétuos

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

Aprova um builder da Hyperliquid para a Account com taxa máxima de 0%. Toda ordem de perpétuo da Hypercall carrega o builder code da Hypercall, então chame esta função uma vez com o hl_builder_address retornado por GET /exchange-info antes da primeira ordem de perpétuo. O app faz isso na etapa Enable 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);

Erros

• Factory__CreationDepositNotMet(uint256 expected): msg.value abaixo do depósito de criação
• Factory__CreationNotAllowed(): bloqueado pelo filtro de criação
• Exchange__AccountDoesNotExist(address account): não é uma Account registrada
• Exchange__TokenNotSupported(address token): não é um token de opção suportado
• Account__NotManager(address addr): o chamador ou signatário não é o manager
• Account__ApiWalletNotActive(address addr): o signatário não é uma carteira de API ativa
• Account__ApiWalletAlreadyActive(address addr): a carteira de API já está na Account
• Account__ApiWalletIsManager(): o manager não pode ser sua própria carteira de API
• Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce reutilizado
• Account__LiquidationInProgress(): ação bloqueada durante a liquidação

Considerações de segurança

1. Chave do manager: controla as carteiras de API, as transferências para fora e a aprovação de builder. Use uma carteira de hardware.
2. Chaves das carteiras de API: assinam apenas ordens e cancelamentos. Use chaves separadas para cada sistema e faça a rotação delas.
3. Nonces: cada signatário tem seu próprio espaço de nonces. Use timestamps em milissegundos e acompanhe-os off-chain.
4. Ativação: a Account precisa estar ativada na HyperCore (pelo menos $1 em HYPE depositado) antes de poder operar perpétuos.