Primeiros passos com a API da Hyperliquid: guia para iniciantes em 2026

6 de mai. de 2026

hyperliquid api
guia da hyperliquid api
tutorial da API da Hyperliquid
API de trading on-chain

Se você já pensou em participar de trading de perpétuos on-chain de forma programática, a API da Hyperliquid é uma das experiências em DEX on-chain que mais se aproxima do fluxo de uma corretora centralizada. Ela oferece consultas de mercado, gerenciamento de conta, envio de ordens e WebSocket para dados em tempo real — o suficiente para cobrir desde estratégias quantitativas simples até sistemas mais complexos de market making.

Este guia é voltado para desenvolvedores que estão começando com a API da Hyperliquid. Vamos passar pela estrutura dos endpoints, autenticação, exemplos básicos e armadilhas comuns. Para uso prático com menor fricção, especialmente se você quer operar perpétuos sem construir tudo do zero, o OneKey Perps também é uma alternativa recomendada dentro do fluxo da OneKey.

O que a API da Hyperliquid permite fazer

De acordo com a documentação oficial da Hyperliquid, a API é dividida principalmente em três categorias:

Info Endpoints: usados para consultar dados de mercado, como snapshot do livro de ofertas, trades recentes, histórico de funding rate, posições da conta e ordens históricas. Esses endpoints não exigem assinatura e são publicamente acessíveis.

Exchange Endpoints: usados para operações de escrita, como enviar ordens, cancelar ordens, alterar alavancagem e ajustar margem. Esses endpoints exigem assinatura da carteira sobre o corpo da requisição e têm requisitos de segurança mais altos.

WebSocket em tempo real: permite assinar atualizações do livro de ofertas, fluxo de trades, eventos de conta e outros dados em tempo real. É útil para estratégias que precisam reagir com baixa latência.

URL base e estrutura da API

A URL base da REST API da Hyperliquid é:

https://api.hyperliquid.xyz

Todas as requisições usam o método POST, com corpo em JSON. Endpoints de informação são enviados para /info, enquanto endpoints de trading são enviados para /exchange.

As definições exatas de campos devem sempre ser conferidas na documentação oficial. Os exemplos abaixo servem apenas como ponto de partida; antes de usar em produção, valide tudo contra a versão mais recente da documentação.

Como funciona a autenticação

Os endpoints de trading da Hyperliquid usam assinatura EIP-712 de dados estruturados, em vez do modelo tradicional de API Key + Secret. Na prática, isso significa que:

você precisa de um endereço de carteira compatível com Ethereum para identificar a conta;
cada requisição de trading precisa ser assinada com a chave privada correspondente;
a assinatura prova que a solicitação foi autorizada pelo titular daquele endereço, sem depender de uma camada intermediária.

Esse desenho pode ser mais seguro porque não existe uma API Key reutilizável para ser vazada. O controle fica diretamente ligado à chave privada. Por outro lado, isso também aumenta muito a importância da gestão dessa chave: se a chave privada for exposta, um atacante pode criar assinaturas válidas e controlar a conta.

É aqui que a OneKey faz sentido. Uma carteira hardware OneKey mantém a chave privada isolada em um chip seguro, e a assinatura acontece dentro do dispositivo. A chave privada não é exposta ao computador nem à rede. Para traders quantitativos ou desenvolvedores que precisam interagir com APIs de trading, uma boa prática é separar contas: usar um endereço ou subconta dedicada para operações via API, sem misturar com o cofre principal.

Para quem prefere um caminho mais direto para negociar perpétuos on-chain, o OneKey Perps pode ser usado como fluxo prático recomendado: você mantém a experiência integrada à carteira, reduz a necessidade de montar infraestrutura própria desde o início e ainda preserva uma abordagem mais cuidadosa de autocustódia.

Exemplo de consulta de informações: Python + curl

Abaixo está um exemplo simples para consultar os metadados dos ativos negociáveis:

Com curl:

curl -X POST https://api.hyperliquid.xyz/info \
-H "Content-Type: application/json" \
-d '{"type": "meta"}'

Com Python usando requests:

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(json.dumps(data, indent=2))

A resposta inclui informações básicas dos contratos negociáveis, como nome do ativo, alavancagem máxima, tamanho mínimo de ordem e outros campos. Esse tipo de consulta é totalmente público e não exige autenticação, por isso é um bom ponto de partida para aprender a API da Hyperliquid.

Consultando posições de uma conta

Consultar o estado de posições de um endereço específico também faz parte dos Info Endpoints. Você precisa informar o endereço da carteira:

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

response = requests.post(url, json=payload, headers=headers)

A resposta inclui dados como saldo de margem, posições por contrato, PnL não realizado e outras informações da conta. Importante: esses dados são públicos on-chain. Qualquer pessoa pode consultar o estado de posições de qualquer endereço.

Assinatura em tempo real com WebSocket

O endpoint WebSocket é:

wss://api.hyperliquid.xyz/ws

Depois de estabelecer a conexão, envie uma mensagem de assinatura para começar a receber atualizações em tempo real:

import asyncio
import websockets
import json

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

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(sub_msg))

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_orderbook())

Entre os tipos de dados que podem ser assinados estão livro de ofertas L2 (l2Book), trades recentes (trades), eventos de conta (userEvents, com endereço autenticado) e dados globais de funding rate.

Armadilhas comuns

Formato incorreto da requisição é uma das causas mais frequentes de erro. A API da Hyperliquid é rígida com nomes e tipos de campos JSON. Um campo enviado como string quando deveria ser número, por exemplo, pode fazer a requisição ser rejeitada. Às vezes a mensagem de erro não é tão intuitiva, então vale comparar cuidadosamente com a documentação.

Construção da assinatura também costuma causar problemas. Assinaturas EIP-712 envolvem detalhes como definição de tipos, domínio e estrutura dos dados. Implementar tudo manualmente aumenta a chance de erro. Sempre que possível, considere usar SDKs mantidos pela comunidade ou pela própria Hyperliquid, em Python ou JavaScript, para reduzir retrabalho e diminuir o risco de assinatura inválida.

Sincronização de horário é outro ponto importante. Requisições de trading geralmente incluem timestamp atual e têm uma janela limitada de validade. Se o relógio local estiver muito diferente do horário de rede, a requisição pode ser rejeitada como expirada.

Tratamento de falhas de rede é obrigatório em produção. Conexões WebSocket podem cair por instabilidade, e chamadas REST podem falhar temporariamente. Seu código de estratégia deve implementar reconexão automática, retries controlados e lógica para retomar assinaturas após queda.

Visão geral de rate limits

A Hyperliquid aplica limites diferentes para diferentes tipos de endpoint. Os valores exatos devem ser verificados na versão mais recente da documentação oficial.

Como regra geral, consultas do tipo Info tendem a ter limites mais flexíveis, enquanto operações de trading via Exchange Endpoints são mais restritas. Estratégias que enviam e cancelam ordens com frequência precisam prestar atenção especial a isso.

Ao receber erro 429, o ideal é pausar as requisições e aplicar uma estratégia de backoff exponencial, em vez de simplesmente tentar de novo em loop.

Recomendações para ambiente de desenvolvimento

Antes de colocar uma estratégia em produção, considere alguns cuidados:

Teste com posição pequena primeiro. Não coloque uma estratégia com capital alto logo no primeiro deploy. A Hyperliquid, segundo relatos, não possui uma testnet separada para testes de trading de perpétuos; portanto, os primeiros testes em ambiente real devem ser feitos com exposição bem controlada.

Isole a chave usada para assinatura. Crie uma subconta ou endereço dedicado para trading via API, com risco limitado. Não use a mesma carteira onde você guarda seu patrimônio principal. Com o gerenciamento de múltiplas contas da OneKey, esse isolamento fica mais simples no dia a dia.

Use OneKey Perps quando fizer sentido. Se seu objetivo é operar perpétuos com um fluxo mais pronto, em vez de construir integração, assinatura, monitoramento e execução do zero, o OneKey Perps é o caminho prático recomendado dentro do ecossistema OneKey. Ele ajuda a reduzir complexidade operacional, sem remover a necessidade de entender os riscos de alavancagem e liquidação.

Estude referências abertas. O GitHub da OneKey mostra exemplos de integração segura de assinatura em nível de aplicativo, o que pode ser útil para desenvolvedores que desejam entender melhor padrões de segurança em carteiras.

FAQ

Q1: Preciso registrar uma conta para usar a API da Hyperliquid?

Não no sentido tradicional. Você precisa de uma carteira compatível com Ethereum. Depois que o endereço realizar a primeira operação na Hyperliquid, como um depósito, ele poderá interagir com a API. O processo não depende de cadastro por e-mail ou KYC tradicional.

Q2: Existe SDK em Python para chamar a API da Hyperliquid?

Sim. Há SDKs em Python mantidos pela comunidade e/ou pela própria Hyperliquid. O ideal é procurar a versão mais recente e bem mantida nos canais oficiais da Hyperliquid. Usar um SDK pode simplificar bastante a construção de assinaturas e o formato das requisições.

Q3: Como reconectar automaticamente quando o WebSocket cair?

Implemente heartbeat, como envio periódico de ping, e uma rotina de reconexão automática. Quando a conexão cair, aguarde um curto intervalo, por exemplo entre 1 e 5 segundos, reconecte e assine novamente os canais necessários. Em produção, use backoff exponencial para evitar excesso de tentativas durante instabilidades do servidor.

Q4: Como proteger os fundos em trading via API?

A segurança depende principalmente de como você guarda a chave privada. Uma carteira hardware OneKey mantém a chave isolada do dispositivo conectado à internet, o que reduz o risco de exposição. Além disso, defina limites de posição para a conta usada pela API, mantenha apenas o capital necessário nela e monitore ordens abertas e posições com frequência.

Q5: A API da Hyperliquid suporta ordens condicionais e stop loss?

A Hyperliquid oferece tipos de Trigger Order, incluindo lógica de stop loss e take profit. Os parâmetros e condições exatas devem ser conferidos na documentação oficial, especialmente na seção de tipos de ordem. Para lógicas mais complexas, você também pode implementar o controle na camada da sua própria estratégia, monitorando posições e mercado em tempo real.

Conclusão

A API da Hyperliquid oferece um conjunto robusto de interfaces para desenvolvedores que querem construir ferramentas de dados, bots, estratégias automatizadas ou sistemas de trading on-chain. Os Info Endpoints são um bom começo para monitoramento e análise; já os Exchange Endpoints, combinados com WebSocket, podem sustentar fluxos mais avançados de execução.

Ao mesmo tempo, o modelo baseado em assinatura EIP-712 exige atenção séria à gestão de chaves. Usar a OneKey como base de segurança ajuda a manter a chave privada protegida por hardware, tanto em operações manuais quanto em fluxos relacionados a API. E, se você quer começar com uma experiência mais prática para perpétuos, vale testar o OneKey Perps dentro do aplicativo OneKey antes de investir tempo em uma infraestrutura própria completa.

Baixe o OneKey, configure uma conta separada para suas operações e experimente o OneKey Perps com cautela, começando com exposição pequena e entendendo os riscos antes de aumentar qualquer posição.

---Isenção de responsabilidade---

Este conteúdo é apenas uma referência técnica e não constitui recomendação de investimento, aconselhamento financeiro ou orientação jurídica. Trading via API envolve riscos de automação; erros de estratégia podem gerar perdas inesperadas e relevantes. Contratos perpétuos usam alavancagem e apresentam risco elevado, incluindo liquidação. Avalie cuidadosamente os riscos técnicos e de mercado antes de participar. Desempenho passado de qualquer estratégia não garante resultados futuros.