Como integrar a Hyperliquid a uma wallet: guia completo para desenvolvedores
Com a maturidade do mercado de derivativos descentralizados, cada vez mais equipes de desenvolvimento de wallets querem levar a negociação de perpétuos da Hyperliquid para dentro da própria interface da carteira, oferecendo uma experiência DeFi mais integrada. Este guia é voltado para desenvolvedores de wallets e resume os principais caminhos técnicos para integrar a Hyperliquid: modelo de contas, esquema de assinatura, uso de SDKs no front-end e pontos críticos de segurança.
Modelo de contas da Hyperliquid
A Hyperliquid usa um sistema de endereços compatível com EVM, no formato Ethereum. O usuário assina com uma chave privada ECDSA padrão. Na documentação oficial, as contas são normalmente divididas em duas categorias:
- Vault Address: endereço principal no nível do protocolo, responsável pela propriedade dos ativos.
- Agent Address: endereço de assinatura secundário que pode ser autorizado, usado para reduzir a fricção em operações frequentes.
Para integrações em wallets, o fluxo mais comum é usar o endereço principal do usuário como Vault Address e, opcionalmente, permitir a autorização de um Agent em uma hot wallet para operações de trading de alta frequência.
Formas de conexão: WalletConnect vs RPC direto
Opção 1: WalletConnect 2.0
WalletConnect é hoje um dos protocolos mais usados para conectar wallets a aplicações Web3. A aplicação web da Hyperliquid oferece suporte nativo ao WalletConnect 2.0. O fluxo geral de integração é:
- Implementar no app da wallet o tratamento de Session Proposal do WalletConnect 2.0.
- Permitir que o usuário autorize a conexão via QR Code ou Deep Link.
- Fazer a wallet escutar solicitações como
eth_sendTransactionepersonal_sign, retornando as assinaturas correspondentes.
A principal vantagem desse caminho é a baixa invasividade: a wallet não precisa entender todos os detalhes internos do protocolo da Hyperliquid. Basta oferecer uma interface de assinatura Ethereum padrão.
Opção 2: integração direta com SDK Python/JS da Hyperliquid
Se a ideia é oferecer uma experiência mais profunda dentro da própria wallet — por exemplo, consultar posições, exibir margem e enviar ordens diretamente — você pode usar SDKs disponíveis para Hyperliquid:
pip install hyperliquid-python-sdk
# ou
npm install @nktkas/hyperliquid
O SDK Python da Hyperliquid encapsula boa parte da lógica de assinatura e requisições, o que reduz erros de implementação e acelera o desenvolvimento.
Esquema de assinatura: EIP-712 estruturado
Todas as operações de escrita na Hyperliquid — como abrir ordens, cancelar ordens, depositar e sacar — usam assinatura estruturada EIP-712, e não uma assinatura simples via eth_sign. Isso tem impacto direto na experiência e na segurança do usuário.
Uma wallet com bom suporte a EIP-712 consegue exibir uma confirmação legível, por exemplo: “abrir long em BTC perp, tamanho 0,01, ordem limite a 65.000 USDC”.
Já uma wallet sem suporte adequado a EIP-712 pode acabar mostrando apenas bytes em hexadecimal, o que gera uma experiência ruim e aumenta o risco de o usuário assinar algo que não entende.
Para uma integração em wallet, o recomendado é priorizar a implementação de parsing e exibição clara de mensagens EIP-712, usando como referência o padrão signTypedData_v4 da especificação EIP-712.
Integração da API principal: fluxo de envio de ordem
Abaixo está um exemplo em JavaScript de como enviar uma ordem limite de compra por chamada direta à API:
import { ethers } from "ethers";
const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";
async function placeOrder(wallet, coin, isBuy, price, size) {
const nonce = Date.now();
const orderPayload = {
type: "order",
orders: [{
a: 0, // asset index (0 = BTC)
b: isBuy,
p: price.toString(),
s: size.toString(),
r: false, // reduce-only
t: { limit: { tif: "Gtc" } }
}],
grouping: "na"
};
// As definições completas de Domain e Types do EIP-712 estão na documentação oficial
const signature = await wallet._signTypedData(domain, types, orderPayload);
const body = {
action: orderPayload,
nonce,
signature,
};
const resp = await fetch(EXCHANGE_ENDPOINT, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
return resp.json();
}
As definições completas de Domain e Types devem ser consultadas na documentação oficial da Hyperliquid, na seção do Exchange Endpoint.
Consulta de saldo e posições
Consultas de saldo e posições são operações somente leitura e não exigem assinatura:
async function getAccountInfo(address) {
const resp = await fetch("https://api.hyperliquid.xyz/info", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
type: "clearinghouseState",
user: address,
}),
});
return resp.json();
}
A resposta inclui dados como:
marginSummary: margem disponível, valor total da conta e informações relacionadas.assetPositions: detalhes de cada posição aberta.crossMaintenanceMarginUsed: margem de manutenção usada no modo cross.
Esses campos podem ser usados para montar uma tela de portfólio, posições abertas, PnL não realizado e dados de risco dentro da wallet.
Pontos essenciais de segurança
Ao integrar protocolos de derivativos em uma wallet, segurança deve ser a prioridade. Alguns pontos importantes:
-
Isolamento da chave privada: assinaturas de trading devem acontecer em um Secure Enclave, ambiente seguro equivalente ou dispositivo de hardware. A chave privada nunca deve ser exposta ao código da aplicação. Para uma abordagem baseada em hardware wallet, vale estudar a arquitetura open source da OneKey.
-
Confirmação clara de valores: antes de enviar uma ordem, a interface deve mostrar uma tela de confirmação legível, com ativo, direção, tamanho, alavancagem e preço estimado de liquidação, quando aplicável.
-
Limitação de permissões do Agent: se a integração usar Agent Address, o usuário deve poder revogar a autorização a qualquer momento. A UI também deve exibir de forma clara quais Agents estão autorizados e seus respectivos endereços.
-
Proteção contra replay: use corretamente o mecanismo de
nonceda Hyperliquid para garantir que cada ordem tenha um nonce monotonicamente crescente, reduzindo o risco de ataques de replay.
Arquitetura recomendada: usar OneKey como referência
A OneKey Hardware Wallet oferece suporte nativo a assinaturas Ethereum EIP-712, e seu SDK open source fornece APIs de assinatura estruturada adequadas para integrações profundas com protocolos EVM, incluindo derivativos como a Hyperliquid.
Para equipes que querem oferecer perpétuos dentro de uma wallet, a experiência do OneKey Perps é uma boa referência prática: combinar segurança baseada em hardware com um fluxo de trading de derivativos fluido, sem trocar proteção por velocidade de forma irresponsável.
Se você está construindo ou avaliando uma integração, experimente baixar a OneKey e testar o fluxo do OneKey Perps. Também vale consultar o GitHub da OneKey para estudar implementações open source e adaptar boas práticas ao seu produto.
Perguntas frequentes
Q1: Quais formas de conexão a Hyperliquid suporta?
A Hyperliquid oferece suporte nativo a MetaMask, wallets compatíveis com WalletConnect 2.0 e acesso programático por assinatura direta com chave privada. Em teoria, qualquer wallet Ethereum capaz de assinar com ECDSA pode ser integrada.
Q2: Qual é a diferença entre Agent Address e endereço principal?
O Agent Address é um endereço secundário autorizado pelo endereço principal. Ele costuma ser usado por bots ou fluxos de trading automatizados. O Agent pode executar operações específicas, como enviar ordens, mas não pode sacar fundos. Isso reduz o impacto caso a chave do Agent seja comprometida. Para detalhes, consulte a documentação da Hyperliquid.
Q3: É preciso pedir permissão ou licença à equipe da Hyperliquid para integrar a API?
A Hyperliquid é um protocolo permissionless. O Info Endpoint é público. Para operações de escrita no Exchange Endpoint, basta enviar uma assinatura EIP-712 válida. Não é necessário solicitar whitelist ou aprovação prévia.
Q4: Como mostrar PnL não realizado na UI da wallet?
A resposta do endpoint clearinghouseState inclui assetPositions. Cada posição contém o campo unrealizedPnl, que pode ser exibido diretamente na interface. Esse valor é denominado em USDC.
Q5: Qual é o endpoint da testnet?
O endpoint da testnet da Hyperliquid é:
https://api.hyperliquid-testnet.xyz/
Ele pode ser usado durante o desenvolvimento para testar funcionalidades sem envolver fundos reais.
Aviso de risco
Este artigo é uma referência técnica de integração e não constitui recomendação de investimento, orientação financeira ou aconselhamento jurídico. A negociação de contratos perpétuos envolve riscos elevados, incluindo uso de alavancagem e possibilidade de liquidação. Desenvolvedores devem entender bem as regras do protocolo e implementar controles de segurança antes de colocar uma integração em produção.
