Onboarding para Portfolio Margin

O Portfolio Margin (PM) está ativo em produção e aberto a todas as contas. Ele calcula a margem das suas opções e dos seus perpétuos da Hyperliquid em conjunto, com base no risco de pior cenário do portfólio. Assim, um book com hedge precisa de muito menos colateral do que no Standard Margin. Esta página mostra como entrar no PM. Para saber como a margem em si é calculada, veja Portfolio Margin.

Resumindo: use uma nova carteira manager, crie a conta Hypercall dela, ative o modo de conta unificada (unified account) da HyperCore, mude para o modo Portfolio e só então deposite.

Por que você começa com uma carteira nova

Uma conta Standard Margin (SM) com saldo ou com book aberto não pode ser convertida diretamente para Portfolio Margin. A Hypercall só aceita a mudança para o modo Portfolio quando todas estas condições valem para a carteira manager:

Requisito	O que significa
Exatamente uma conta Hypercall	O manager controla um único contrato Account. Nenhum, ou mais de um, é rejeitado.
Saldo Standard zerado	O saldo em caixa Standard Margin da carteira é zero. Qualquer saldo sacável bloqueia a mudança.
Zerado (flat)	Nenhuma posição aberta e nenhuma ordem aberta, nem na carteira manager nem na sua Account.

Essas regras existem porque os dois modos são tipos diferentes de conta, não uma mesma conta com uma configuração:

• Seu colateral é custodiado de forma diferente. Passar de Standard para Portfolio Margin significa mover seus fundos, não apertar um botão.
• As posições têm margem calculada por regras diferentes. Uma posição aberta teria que ter a margem recalculada de um conjunto de regras para o outro.
• Por isso a mudança acontece a partir de uma conta vazia. Fazer as duas coisas com segurança em um único passo não é suportado, e é por isso que a conta precisa estar zerada e vazia antes.

O modo de margem é definido por carteira manager, então uma carteira não pode operar os dois modos. O caminho mais simples é uma carteira manager nova para o PM, o que permite que sua conta SM atual continue cotando enquanto você configura. Você também pode esvaziar a carteira atual (fechar tudo, cancelar todas as ordens, sacar todo o caixa Standard) e mudar o modo dela, mas não poderá manter esse book SM operando nesse meio-tempo.

Antes de começar

• Uma nova carteira manager (uma EOA que você controla, de preferência em uma hardware wallet ou com chave protegida de outra forma).
• HYPE na HyperEVM nessa carteira, para o depósito de criação da conta mais gas.
• O USDC que você pretende usar como colateral.

Passos de configuração

Siga nesta ordem. O passo 4 precisa vir antes do passo 5.

1. Crie uma nova carteira manager. Não reutilize seu manager SM, uma carteira de API ou uma chave de agente.

2. Crie sua conta Hypercall. A partir da carteira manager, chame createAccount(salt) no contrato Factory com o depósito de criação em HYPE. Isso faz o deploy do seu contrato Account e o ativa na HyperCore. Veja Onboarding (contratos). Crie apenas uma conta para esse manager.

3. Ative o modo de conta unificada da HyperCore para a Account. Envie a ação hl_set_abstraction, assinada pela carteira manager, com user definido como o endereço da sua Account e abstraction definido como 2 (conta unificada). POST /v1/actions/hl_set_abstraction/typed-data retorna os typed data exatos a serem assinados, e POST /v1/actions/hl_set_abstraction os envia. Aguarde até a HyperCore reportar a Account como unifiedAccount. Os outros modos de conta da Hyperliquid, incluindo o próprio modo de portfolio margin dela, não são suportados.

4. Mude para o modo Portfolio. Envie POST /margin-mode com wallet definido como o endereço do seu manager e margin_mode definido como portfolio, assinado pela carteira manager (veja Autenticação). A resposta retorna o endereço da sua Account como a carteira PM. Faça isso antes de depositar: enquanto uma carteira ainda está no modo Standard, um depósito na Hypercall é creditado como caixa Standard, e esse saldo passa a bloquear a mudança até você sacá-lo de novo.

5. Deposite USDC na sua Account. Deposite pelo app, que roteia de acordo com o modo de margem, ou envie USDC na HyperCore para o endereço da sua Account. Os fundos passam a contar para a margem assim que o próximo snapshot da HyperCore feito pela Hypercall os mostrar.

6. Configure suas chaves de assinatura. As aprovações da sua carteira SM antiga não são transferidas.

   • Opções (REST): aprove sua chave de trading para a nova carteira manager com POST /approve-agent. Veja Autorização de agentes.
   • Perpétuos (diretivas on-chain): registre uma carteira de API na sua Account com a ação hc_update_api_wallet assinada pelo manager. Uma carteira de API só pode estar ativa em uma Account. Veja Assinatura EIP-712.

7. Opere. Continue enviando o endereço do seu manager como wallet nas requisições de opções; a Hypercall as roteia para sua conta PM. Tipos de ordem, a API de ordens e a assinatura são os mesmos do Standard Margin. Para perpétuos da Hyperliquid pelo app, veja Perpétuos na Hypercall.

No app, escolher Portfolio em Settings > Margin Mode executa os passos 2 a 4 para você: cria a conta se você não tiver uma, ativa o modo de conta unificada e muda o modo.

Se você pular o modo de conta unificada

A Hypercall avalia uma conta PM pelo seu equity na HyperCore, que a HyperCore só publica para Accounts no modo de conta unificada. Se a Account não estiver nesse modo, o passo 4 é recusado com 400 pm_account_not_unified. Conclua o passo 3, aguarde a HyperCore confirmar o modo e tente de novo.

Se uma Account sair do modo de conta unificada depois, as leituras de portfólio retornam 503 pm_account_equity_pending (ou 409 pm_account_not_unified se a HyperCore nunca tiver publicado o equity dela), e as ordens falham com um erro como missing HyperCore account equity for PM wallet 0x.... Reative o modo de conta unificada para corrigir. Veja Erros e motivos de rejeição.

Perguntas frequentes

Posso manter minha conta Standard Margin funcionando? Sim. Faça o onboarding no PM com uma nova carteira manager e deixe sua conta SM como está.

Por que minha mudança de modo de margem foi rejeitada? O erro indica a regra: a carteira não tem Account (ou tem mais de uma), tem saldo Standard, tem posições ou ordens abertas, ou a Account ainda não está no modo de conta unificada da HyperCore (pm_account_not_unified). Veja Por que você começa com uma carteira nova.

Depositei antes de mudar o modo. E agora? O depósito foi creditado como caixa Standard. Saque-o, depois mude para o modo Portfolio e deposite na sua Account.

Preciso de novas chaves de API? Você precisa de novas aprovações. As aprovações de agente para opções são vinculadas à carteira manager, então aprove sua chave de novo para a nova carteira. Uma carteira de API de perpétuos só pode estar ativa em uma Account, então use uma chave nova ou remova-a da sua Account antiga primeiro (passo 6).

Onde aprendo como funcionam a margem, a liquidação e o settlement no PM? Veja Portfolio Margin, Exemplos práticos de margem PM, Piso de margem, Liquidação e Settlement.