Limites de taxa da API da Hyperliquid e melhores práticas

• hyperliquid rate limit
• hyperliquid api limit
• Limites de taxa da API da Hyperliquid
• Melhores práticas de API

Para qualquer estratégia quantitativa ou ferramenta de dados que dependa da API da Hyperliquid, limites de taxa são um tema básico e inevitável. Acionar um rate limit não apenas interrompe a execução da estratégia, como também pode gerar atrasos inaceitáveis em momentos críticos — por exemplo, quando você precisa reduzir risco ou fechar uma posição com urgência.

Este artigo explica como pensar sobre os limites de taxa da API da Hyperliquid e reúne práticas usadas em ambientes de produção para construir clientes de API mais robustos, eficientes e seguros.

Por que limites de taxa importam tanto

Limites de taxa existem para proteger os recursos do servidor e evitar que um pequeno grupo de usuários com requisições muito frequentes prejudique a qualidade do serviço para todos. Em uma plataforma de trading on-chain como a Hyperliquid, a estabilidade da infraestrutura afeta diretamente a experiência de milhares de usuários simultâneos.

Do ponto de vista de quem desenvolve estratégias, o rate limit é uma restrição dura: ele define com que frequência você consegue buscar dados, atualizar estado e enviar ordens. Se a arquitetura da estratégia não considera esses limites desde o início, erros 429 em produção podem comprometer execução, monitoramento e resposta a eventos de mercado.

Limites de taxa do endpoint Info

O endpoint Info (/info) é usado para consultas somente leitura. Em geral, seus limites tendem a ser mais flexíveis do que os endpoints de escrita. Conforme a documentação oficial da Hyperliquid, os valores exatos devem ser sempre conferidos na versão mais recente da documentação; este artigo não cita números específicos não verificados.

A regra prática é: o endpoint Info deve atender necessidades razoáveis de monitoramento de mercado, mas polling agressivo — por exemplo, consultar o livro de ofertas dezenas de vezes por segundo — ainda pode acionar limites. Para dados em tempo real, assinaturas via WebSocket normalmente são uma alternativa melhor: reduzem pressão sobre a API REST e costumam oferecer menor latência.

Tipos comuns de consulta no Info e seus padrões de frequência:

• Estado da conta (clearinghouseState): adequado para polling de baixa frequência; em muitos casos, poucas vezes por segundo já é suficiente.
• Histórico de fills (userFills): ideal para buscas pontuais ou de baixa frequência, sem necessidade de chamadas constantes.
• Metadados de mercado (meta): normalmente basta carregar na inicialização e manter em cache local.
• Snapshot de livro L2: prefira WebSocket em vez de polling REST para uso em tempo real.

Limites de taxa do endpoint Exchange

O endpoint Exchange (/exchange) processa operações de escrita, incluindo envio, cancelamento e modificação de ordens. Seus limites costumam ser mais restritivos do que os do Info, o que faz sentido: uma frequência excessiva de ordens e cancelamentos consome mais recursos e pode afetar a experiência de execução de outros usuários.

Um ponto importante é que alguns padrões de estratégia — como modificar ordens com muita frequência — podem consumir mais recursos do que simplesmente enviar e cancelar ordens em menor volume. Antes de implementar uma lógica de market making, grid, rebalanceamento ou execução algorítmica, avalie se cada atualização de ordem é realmente necessária.

A documentação da Hyperliquid detalha os limites aplicáveis a diferentes operações de Exchange. Antes de colocar qualquer robô em produção, leia a documentação oficial e projete sua estratégia com uma margem de segurança.

Limites de conexão e assinatura via WebSocket

Os limites de WebSocket são diferentes dos limites REST. Eles geralmente envolvem dimensões como número de conexões simultâneas e quantidade de canais assinados por conexão.

Assinar muitos livros L2 de diferentes contratos pode consumir bastante recurso do servidor. Algumas boas práticas:

• Concentre múltiplas assinaturas no menor número possível de conexões WebSocket.
• Cancele assinaturas que não são mais necessárias.
• Evite abrir muitas conexões simultâneas para a mesma conta.
• Monitore reconexões e perda de mensagens para detectar problemas de rede ou sobrecarga no cliente.

Como lidar corretamente com erro 429

HTTP 429 (Too Many Requests) é o status padrão quando o servidor indica que você excedeu o limite de requisições. Ao receber um 429, o erro mais comum é tentar novamente imediatamente. Isso piora o problema: gera mais 429, aumenta a pressão sobre a API e pode resultar em bloqueios temporários mais longos.

O fluxo recomendado é:

1. Pare imediatamente o mesmo tipo de requisição
   Ao receber 429, pause todas as requisições daquele tipo, não apenas a requisição atual.

2. Leia o cabeçalho Retry-After
   Se a resposta incluir Retry-After, esse valor indica por quantos segundos você deve esperar. Respeite-o estritamente.

3. Use backoff exponencial quando não houver Retry-After
   Comece com 1 segundo e dobre a espera a cada falha: 1s, 2s, 4s, 8s, até atingir um limite máximo, como 60 segundos.

4. Registre logs e dispare alertas
   Erros 429 não devem ser ignorados silenciosamente. Se eles acontecem com frequência, o padrão de requisições da estratégia precisa ser otimizado.

Exemplo conceitual em Python:

import time
import requests


def request_with_backoff(url, payload, max_retries=5):
    wait_time = 1

    for attempt in range(max_retries):
        response = requests.post(url, json=payload)

        if response.status_code == 200:
            return response.json()

        elif response.status_code == 429:
            retry_after = response.headers.get("Retry-After")
            sleep_duration = int(retry_after) if retry_after else wait_time

            print(f"Rate limited. Waiting {sleep_duration}s before retry.")
            time.sleep(sleep_duration)

            wait_time = min(wait_time * 2, 60)

        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

Estratégias de batching de requisições

Uma forma eficiente de reduzir frequência de chamadas é agrupar operações. Em vez de enviar várias requisições independentes, consolide o máximo possível.

Para consultas de dados, se você precisa buscar informações de múltiplas contas ou contratos, verifique se a API oferece parâmetros de consulta em lote. Uma única chamada para obter todos os dados necessários costuma ser melhor do que várias chamadas sequenciais.

Para operações de trading, a Hyperliquid oferece suporte a Batch Order, permitindo enviar múltiplas ordens em uma única requisição Exchange. Isso é útil para estratégias que precisam abrir ou ajustar várias posições ao mesmo tempo, reduzindo tanto a latência operacional quanto o número total de requisições. O formato exato deve ser conferido na documentação oficial.

Pool de conexões e controle de concorrência

Ao chamar a API da Hyperliquid em ambientes multithread ou assíncronos, implemente controle de concorrência no cliente. Sem isso, múltiplas tarefas podem disparar uma rajada de requisições em um curto intervalo e acionar rate limits.

Um exemplo com Semaphore em Python:

import asyncio
import aiohttp

# Limita o número máximo de requisições concorrentes a 10
semaphore = asyncio.Semaphore(10)


async def rate_limited_request(session, payload):
    async with semaphore:
        async with session.post(
            "https://api.hyperliquid.xyz/info",
            json=payload
        ) as response:
            return await response.json()

Reutilizar conexões HTTP também reduz latência e consumo de recursos. Em Python, use requests.Session ou aiohttp.ClientSession em vez de criar uma nova conexão para cada chamada. Isso aproveita HTTP Keep-Alive e diminui o custo de handshakes TCP.

Cache local

Nem todo dado precisa ser buscado da API em tempo real. Um cache local bem projetado reduz chamadas desnecessárias e melhora a estabilidade da estratégia.

Exemplos:

• Metadados de mercado: lista de contratos, parâmetros e alavancagem máxima mudam com baixa frequência; podem ser mantidos em memória por horas.
• Funding rates: podem ser armazenados até o próximo ciclo de liquidação relevante.
• Estado da conta: pode ser mantido localmente e atualizado por eventos via WebSocket, em vez de depender apenas de polling frequente.

O ponto central é definir uma política clara de expiração e validação. Cache demais pode gerar decisões com dados defasados; cache de menos aumenta a chance de rate limit.

Monitoramento da saúde da API

Em produção, monitore suas chamadas de API de forma sistemática:

• Taxa de sucesso por tipo de endpoint.
• Tempo de resposta médio e percentis, como p95 e p99.
• Frequência de erros 429.
• Número de reconexões WebSocket.
• Tamanho de filas internas de mensagens.
• Divergência entre dados em cache e dados retornados pela API.

Erros 429 devem ter limites de alerta claros. Se a estratégia começa a bater nesses limites com frequência, trate como problema de arquitetura, não como evento isolado.

Resumo de melhores práticas

Segurança de chave privada e o papel da OneKey

Ao otimizar performance e limites de API, não negligencie o ponto mais importante: segurança da chave privada. Cada requisição de trading enviada ao endpoint Exchange precisa ser assinada. Isso significa que o ambiente que roda a estratégia precisa ter algum tipo de acesso à capacidade de assinatura.

Uma abordagem mais equilibrada entre segurança e praticidade é usar a OneKey para gerar e gerenciar chaves dedicadas à assinatura de API, separando-as dos fundos principais sempre que possível. Com carteira hardware, a chave privada não precisa aparecer em texto claro no ambiente de software, reduzindo o impacto caso o servidor da estratégia seja comprometido.

A OneKey também oferece suporte a fluxos padronizados de conexão com dApps, como WalletConnect, o que facilita integrações mais seguras entre carteira, aplicações e ferramentas de trading.

Para quem opera perps na Hyperliquid, o fluxo prático recomendado é usar OneKey Perps como interface e base operacional para negociar com uma camada adicional de controle de chave. Isso não elimina riscos de mercado, liquidação, falhas técnicas ou erros de estratégia, mas ajuda a reduzir a superfície de exposição da chave privada.

Se você está construindo sua primeira estratégia on-chain ou quer melhorar a segurança do seu setup atual, baixe o app da OneKey pelo site oficial e teste o OneKey Perps com uma abordagem conservadora, começando com valores pequenos e limites de risco claros.

FAQ

Q1: Se eu acionar o rate limit, minha conta será banida?

Em geral, um acionamento pontual de rate limit resulta em requisições recusadas com erro 429, não em banimento imediato. Porém, comportamento abusivo e persistente pode levar a consequências mais severas. A política exata deve ser verificada na documentação oficial da Hyperliquid. Uma boa gestão de limite de taxa é tanto uma necessidade técnica quanto parte do uso responsável da plataforma.

Q2: O que fazer se meu cliente WebSocket não consegue processar as mensagens rápido o suficiente?

Quando o consumo não acompanha o ritmo das mensagens, filas internas crescem e seus dados ficam cada vez mais atrasados. Possíveis soluções incluem otimizar o processamento, separar recebimento e processamento em etapas diferentes, reduzir canais assinados e descartar dados obsoletos quando apropriado. Se mesmo assim o sistema não acompanha, talvez a estratégia precise ser redesenhada.

Q3: Como compartilhar limite de taxa entre várias instâncias de estratégia?

Quando múltiplas instâncias rodam ao mesmo tempo, o ideal é usar um proxy de requisições ou middleware centralizado de rate limiting. Assim, cada instância não calcula o limite isoladamente e o sistema evita ultrapassar o total permitido. Redis ou outro banco em memória pode ser usado para implementar contadores distribuídos em cenários com múltiplos processos ou máquinas.

Q4: Como saber se um 429 veio de rate limit ou de outro problema?

Uma resposta 429 normalmente inclui uma mensagem explicando o motivo e, em alguns casos, o cabeçalho Retry-After. Se a resposta indicar claramente limite de taxa, aplique backoff. Se o erro estiver ligado a outro problema — como parâmetros inválidos, saldo insuficiente ou falha de validação — corrija a causa específica em vez de simplesmente repetir a requisição.

Q5: Os limites dos endpoints Info e Exchange são calculados separadamente?

De acordo com a documentação oficial, os limites dessas categorias são tratados separadamente. Isso significa que consultas de dados em alta frequência não devem consumir diretamente a cota de envio de ordens, e vice-versa. Ainda assim, é recomendável planejar orçamentos de requisição separados para leitura e escrita.

Conclusão

Gerenciar limites de taxa é uma parte essencial do desenvolvimento com a API da Hyperliquid. Escolher o tipo certo de interface, trocar polling por WebSocket quando apropriado, implementar backoff exponencial, usar batching, controlar concorrência e manter cache local são medidas que afetam diretamente a estabilidade da estratégia.

Além da eficiência técnica, segurança de chave privada deve ser tratada como requisito básico. O OneKey Perps combina uma experiência prática para operar perps com uma abordagem mais cuidadosa de gerenciamento de chaves. Para explorar esse fluxo, baixe a OneKey pelo site oficial e teste o OneKey Perps com gestão de risco disciplinada.

Disclaimer

Este conteúdo é apenas para referência técnica e educacional. Não constitui recomendação de investimento, aconselhamento financeiro, jurídico ou tributário. Trading via API envolve riscos de falhas técnicas, interrupções de rede, bugs de código e perdas inesperadas. Contratos perpétuos envolvem alto risco, especialmente com alavancagem. Participe apenas se compreender os riscos e use capital compatível com sua tolerância a perdas.