Hyperliquid REST vs WebSocket: quando usar cada um

Muitos desenvolvedores que integram a API da Hyperliquid chegam à mesma dúvida: minha estratégia deve usar REST ou WebSocket? As duas interfaces funcionam de formas bem diferentes e atendem a casos de uso distintos. Escolher errado pode significar desperdício de banda, maior complexidade operacional e, em estratégias sensíveis a tempo, execução pior do que o esperado.

Este artigo explica como REST e WebSocket funcionam na Hyperliquid, quando usar cada um, quais são as diferenças de latência, os principais cuidados de implementação e como combinar isso com um fluxo mais seguro usando OneKey e OneKey Perps.

REST API: modelo de requisição e resposta

REST, ou Representational State Transfer, é o modelo clássico de API sobre HTTP: o cliente envia uma requisição, o servidor retorna uma resposta, e a interação termina ali. É um fluxo de “pergunta e resposta”.

Na Hyperliquid, os endpoints REST normalmente se dividem em duas categorias principais.

Os endpoints de Info (/info) lidam com consultas somente leitura, como metadados de mercado, trades históricos, snapshots de posições e dados de conta. Essas chamadas não exigem assinatura e podem ser feitas por qualquer cliente.

Os endpoints de Exchange (/exchange) lidam com operações de escrita, como enviar ordens, cancelar ordens, alterar alavancagem e ajustar margem. Essas chamadas exigem assinatura estruturada EIP-712. O servidor valida se a assinatura corresponde ao endereço da conta antes de executar a operação.

Quando REST faz mais sentido

REST é ideal para consultas pontuais. Por exemplo: buscar o estado atual das posições quando a estratégia inicia, checar saldo periodicamente ou consultar o histórico de funding de um contrato específico. Nesses casos, você não precisa de atualização em tempo real; basta fazer uma requisição e receber uma resposta.

Envio e cancelamento de ordens também passam por REST. Mesmo que a sua estratégia use dados em tempo real via WebSocket, a instrução de trade em si precisa ser enviada ao endpoint Exchange por REST. Esse é um requisito da arquitetura da API.

REST também funciona bem para baixar dados históricos em lote. Em um backtest, por exemplo, você pode paginar chamadas ao endpoint Info para obter trades históricos ou candles. Não é o fluxo mais “instantâneo”, mas é adequado para esse tipo de tarefa.

Limitações do REST

A principal limitação do REST é o modelo de “pull”: você só recebe dados quando pergunta. O problema é que o mercado não muda em intervalos previsíveis.

Se você tentar consultar o livro de ordens a cada 100 ms, pode esbarrar em limites de taxa e aumentar a carga desnecessariamente. Se reduzir a frequência para uma vez por segundo, sua estratégia pode ficar atrasada em momentos de volatilidade. Para estratégias que precisam reagir rapidamente a mudanças de mercado, polling frequente via REST tende a ser ineficiente e menos confiável.

WebSocket: conexão persistente e dados em tempo real

WebSocket é um protocolo full-duplex: depois que a conexão é aberta, o servidor pode enviar atualizações continuamente para o cliente, sem que o cliente precise ficar repetindo requisições.

O endpoint WebSocket da Hyperliquid é:

wss://api.hyperliquid.xyz/ws

Depois de conectar, o cliente envia uma mensagem de inscrição indicando quais dados deseja receber. A partir daí, o servidor passa a enviar eventos daquele tipo até que a conexão caia ou a inscrição seja cancelada.

Quando WebSocket faz mais sentido

Monitoramento do livro de ordens em tempo real é um dos usos mais comuns. Ao assinar o canal l2Book, a estratégia recebe atualizações sempre que o livro muda, permitindo acompanhar profundidade e liquidez com latência muito menor do que em polling via REST.

O fluxo de trades em tempo real, pelo canal trades, é útil para observar agressão de mercado, ritmo de execução e possíveis mudanças de sentimento no curto prazo.

Eventos de conta, pelo canal userEvents, permitem acompanhar preenchimentos, notificações relevantes e mudanças relacionadas à conta sem precisar consultar o estado repetidamente via REST.

Acompanhamento de funding em tempo real também pode ser relevante para estratégias de arbitragem. Em vez de esperar a próxima consulta periódica, o WebSocket permite reagir quando novas informações chegam.

Cuidados ao usar WebSocket

A estabilidade da conexão é o ponto central. Oscilações de rede, reinícios do servidor ou longos períodos de inatividade podem derrubar a conexão. Em produção, você deve implementar heartbeat, ping/pong quando aplicável, reconexão automática e reinscrição de todos os canais após reconectar.

Também é importante lidar com dados possivelmente perdidos durante a desconexão. Em muitos casos, o padrão mais seguro é: reconectar, buscar um snapshot atual via REST e usar esse novo estado como base.

Outro cuidado é a pressão de processamento. Canais de alta frequência, como o livro L2 de mercados líquidos, podem gerar muitas mensagens. Se o seu parser ou motor de estratégia não processar os eventos rápido o suficiente, a fila começa a acumular e o sistema passa a operar com dados atrasados — justamente o oposto do objetivo de usar WebSocket.

Comparação rápida

Exemplo de código: REST vs WebSocket

Consulta de snapshot do livro de ordens via REST em Python:

import requests

response = requests.post(
    "https://api.hyperliquid.xyz/info",
    json={"type": "l2Book", "coin": "ETH"}
)

book = response.json()

# Você recebe o snapshot daquele momento.
# Ele não será atualizado automaticamente.

Assinatura de atualizações do livro de ordens via WebSocket em Python:

import asyncio
import websockets
import json

async def stream_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "ETH"}
        }))

        # Recebe atualizações continuamente enquanto a conexão estiver aberta.
        async for message in ws:
            data = json.loads(message)
            print(data)

asyncio.run(stream_orderbook())

A diferença é direta: REST entrega um snapshot e termina; WebSocket mantém a conexão aberta e envia novas mensagens conforme o mercado muda.

Assinatura de ordens e integração com OneKey

Seja em uma arquitetura que usa REST para enviar ordens, seja em uma que usa WebSocket para acompanhar eventos da conta, qualquer operação de escrita exige assinatura EIP-712. A segurança da chave que assina essas operações define uma parte crítica do risco da conta.

A carteira OneKey oferece isolamento de assinatura em nível de hardware: a chave privada fica protegida no dispositivo, e as assinaturas são realizadas internamente. O código rodando no computador não precisa acessar a chave privada bruta.

Para traders quantitativos e desenvolvedores, isso reduz um risco importante: mesmo que um script, servidor ou ambiente local seja comprometido, o atacante não obtém automaticamente a chave privada. Ainda assim, automação de trading continua exigindo controles operacionais rigorosos.

Um fluxo prático pode ser:

1. A estratégia monta o payload da ordem a ser assinada.
2. O pedido de assinatura é enviado à OneKey via WalletConnect ou fluxo compatível.
3. Você confere e aprova a assinatura no dispositivo.
4. A assinatura retorna ao código da estratégia.
5. A ordem é enviada ao endpoint /exchange da Hyperliquid.

Esse modelo funciona melhor para estratégias de baixa ou média frequência, porque adiciona uma etapa de confirmação. Para estratégias totalmente automatizadas e de alta frequência, você deve avaliar com cuidado a separação entre hot wallets dedicadas, limites de exposição, contas segregadas e controles de risco.

Na prática, para a maioria dos usuários que querem acessar a liquidez da Hyperliquid sem montar toda a infraestrutura por conta própria, o caminho mais simples é usar OneKey Perps dentro do ecossistema OneKey. Ele oferece uma experiência mais direta para operar perps, mantendo a autocustódia como parte central do fluxo.

Arquitetura híbrida: a melhor prática comum

Em produção, REST e WebSocket raramente competem entre si. Na maior parte das arquiteturas robustas, eles são complementares.

Um desenho típico pode ser:

• WebSocket mantém uma conexão aberta para dados de mercado em tempo real, como l2Book, trades e userEvents.
• REST envia ordens, cancela ordens e executa outras ações de escrita.
• Ao iniciar, a estratégia usa REST para carregar estado inicial da conta, posições e parâmetros importantes.
• Periodicamente, a estratégia usa REST para reconciliar o estado completo e corrigir possíveis divergências causadas por desconexões do WebSocket.
• Após uma reconexão, a estratégia busca snapshots via REST antes de voltar a confiar nos eventos incrementais.

Esse modelo aproveita o melhor de cada interface: REST para estado confiável sob demanda e operações de escrita; WebSocket para eventos contínuos e resposta rápida a mudanças.

FAQ

Q1: Se eu só faço uma estratégia simples de ordens programadas, preciso de WebSocket?

Não necessariamente. Se a lógica é apenas disparar ordens em horários ou condições simples, REST pode ser suficiente. Você consulta preço e estado da conta quando necessário, monta a ordem, assina e envia ao endpoint Exchange. WebSocket pode adicionar complexidade sem trazer muito benefício nesse caso.

Q2: Como saber quais dados perdi durante uma desconexão do WebSocket?

Esse é um problema clássico de WebSocket. Uma abordagem comum é reconectar e imediatamente buscar o estado atual completo via REST, como snapshot do livro de ordens e posições da conta. Esse snapshot passa a ser a nova base. Para trades históricos, você pode consultar o período da desconexão e preencher parte da lacuna quando a API permitir.

Q3: Qual é a latência entre enviar uma ordem via REST e receber o retorno de execução?

A resposta da ordem via REST normalmente confirma que a requisição foi aceita ou processada em determinado nível, mas o preenchimento efetivo pode ser acompanhado pelo canal userEvents no WebSocket ou por nova consulta ao estado da conta. A latência depende das condições de rede, do estado da infraestrutura e da dinâmica da Hyperliquid. Em condições normais, costuma ser curta, mas eventos extremos de mercado podem gerar atrasos.

Q4: Quantas conexões WebSocket devo abrir?

Em geral, é melhor concentrar as assinaturas de uma mesma conta em poucas conexões, evitando excesso de conexões concorrentes e possíveis limites. O limite exato deve ser verificado na documentação oficial mais recente da Hyperliquid. Se você roda várias estratégias internas, pode ser mais eficiente compartilhar uma conexão WebSocket por meio de um barramento de mensagens interno.

Q5: Há algum cuidado ao testar WebSocket no Jupyter Notebook?

Sim. O event loop padrão do Jupyter pode conflitar com asyncio.run(). Uma solução comum é usar a biblioteca nest_asyncio e chamar nest_asyncio.apply() no início do notebook. Outra opção é mover o código WebSocket para um script Python separado, o que costuma ser mais parecido com o ambiente de produção.

Conclusão

REST e WebSocket não são rivais; eles resolvem problemas diferentes. Uma regra simples é: use REST quando precisar de um dado “naquele momento” ou quando for enviar uma operação; use WebSocket quando precisar acompanhar mudanças em tempo real.

Ao entender essa divisão, você passa a enxergar melhor a arquitetura da API da Hyperliquid. Para um fluxo mais seguro e prático, considere usar OneKey como base de assinatura e OneKey Perps como forma direta de acessar perps com a liquidez da Hyperliquid.

Se você quer testar esse fluxo sem montar tudo do zero, baixe o app da OneKey, conecte sua carteira com atenção aos riscos e experimente o OneKey Perps de forma gradual, começando com valores pequenos e limites claros.

Disclaimer: este conteúdo é apenas para fins educacionais e técnicos. Não constitui recomendação de investimento, aconselhamento financeiro ou orientação jurídica. Estratégias automatizadas podem falhar por bugs, problemas de rede, erros de configuração ou eventos extremos de mercado. Operar contratos perpétuos com alavancagem envolve alto risco e pode causar perdas significativas. Avalie sua capacidade técnica e tolerância a risco antes de participar.