Como usar o Hyperliquid SDK para trading programático

• Hyperliquid SDK

• Trading programático na Hyperliquid

• Hyperliquid Python SDK

• API da Hyperliquid para trading programático

• Bot de perpétuos on-chain

O trading programático deixou de ser uma ferramenta exclusiva de instituições e passou a estar ao alcance de qualquer trader com noções de programação. A Hyperliquid, uma exchange on-chain de contratos perpétuos, oferece interfaces REST e WebSocket completas, além de SDKs mantidos pela equipe oficial e pela comunidade em várias linguagens. Com poucas dezenas de linhas de código, você consegue enviar ordens, consultar posições, tratar erros e montar fluxos básicos de automação.

Neste artigo, vamos partir da preparação do ambiente e mostrar como usar SDKs em Python ou JavaScript para construir um fluxo de trading programático mais confiável. Também explicamos por que, em produção, usar uma carteira hardware OneKey como camada de assinatura é uma etapa importante para proteger seus fundos.

Por que escolher a Hyperliquid para trading programático

Em comparação com exchanges centralizadas, a Hyperliquid tem algumas vantagens relevantes: a liquidação das negociações acontece on-chain, os fundos não precisam ficar custodiados por terceiros; o livro de ofertas usa uma arquitetura híbrida, com matching off-chain e liquidação on-chain, equilibrando velocidade e transparência; e as APIs são relativamente simples, com documentação atualizada e uma comunidade ativa.

Para traders quantitativos, isso significa poder manter a soberania da autocustódia enquanto acessa uma experiência de trading próxima à de uma exchange centralizada.

Preparação do ambiente e instalação do SDK

Ambiente Python

Até o momento deste artigo, o SDK Python mantido pela comunidade pode ser instalado via pip. O ideal é trabalhar em um ambiente virtual para evitar conflitos de dependências:

python -m venv hl_env
source hl_env/bin/activate
pip install hyperliquid-python-sdk

O código-fonte do SDK pode ser encontrado em repositórios do ecossistema, incluindo organizações ligadas à OneKey e à Hyperliquid. Consulte sempre a documentação oficial para obter o endereço mais recente do repositório.

Ambiente JavaScript/TypeScript

Para quem prefere Node.js:

npm install @nktkas/hyperliquid

# ou use o pacote mantido oficialmente, conforme a versão mais recente no npm registry

Usuários de TypeScript podem importar diretamente as definições de tipos, o que melhora bastante a experiência de autocomplete na IDE.

Conectando à API e inicializando o cliente

Autenticação

A Hyperliquid usa assinatura com chave privada para autenticar solicitações de trading. Cada ordem precisa ser assinada pela chave privada da carteira usando assinatura estruturada EIP-712, garantindo que a solicitação não possa ser falsificada.

Exemplo em Python, em pseudocódigo:

import os
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account

# Leia a chave privada de uma variável de ambiente. Nunca faça hardcode.
private_key = os.environ["HL_PRIVATE_KEY"]

account = Account.from_key(private_key)

info = Info(base_url="https://api.hyperliquid.xyz")
exchange = Exchange(account, base_url="https://api.hyperliquid.xyz")

Em ambiente de produção, é altamente recomendável substituir a chave privada em software por uma carteira hardware OneKey. A chave privada nunca sai do chip seguro do dispositivo; mesmo que o servidor seja comprometido, a chave não pode ser exportada. Voltaremos a esse ponto mais adiante.

Consultando dados de mercado e status da conta

Obter snapshot de mercado

# Obtém metadados de todos os perpétuos e preços atuais
meta_and_asset_ctx = info.meta_and_asset_ctxs()

# O retorno inclui campos como markPx, funding, entre outros

Consultar posições e saldo

user_state = info.user_state(account.address)

# user_state inclui marginSummary e assetPositions
for pos in user_state["assetPositions"]:
    print(pos["position"]["coin"], pos["position"]["szi"])  # Par e tamanho da posição

Enviando ordens

Ordem a mercado

order_result = exchange.market_open(
    coin="BTC",
    is_buy=True,
    sz=0.001,      # Quantidade da ordem
    slippage=0.01  # Slippage máximo permitido: 1%
)

print(order_result)

Ordem limitada

order_result = exchange.order(
    coin="ETH",
    is_buy=False,
    sz=0.1,
    limit_px=3200.0,  # Preço limite
    order_type={"limit": {"tif": "Gtc"}}  # Good Till Cancel
)

O campo tif aceita opções como Gtc — válida até ser cancelada —, Ioc — executa imediatamente ou cancela — e Alo — apenas maker/post-only. Escolha de acordo com as necessidades da sua estratégia.

Envio de ordens em lote

Estratégias de market making ou grid trading normalmente precisam enviar várias ordens ao mesmo tempo. O SDK oferece interfaces em lote para reduzir idas e vindas de rede:

orders = [
    {"coin": "BTC", "is_buy": True,  "sz": 0.001, "limit_px": 60000, "order_type": {"limit": {"tif": "Gtc"}}},
    {"coin": "BTC", "is_buy": False, "sz": 0.001, "limit_px": 61000, "order_type": {"limit": {"tif": "Gtc"}}},
]

result = exchange.bulk_orders(orders)

Cancelando e modificando ordens

# Para cancelar, informe coin e oid, o ID da ordem
cancel_result = exchange.cancel(coin="BTC", oid=123456789)

# Modificar ordem: cancel + replace
modify_result = exchange.modify_order(
    oid=123456789,
    coin="BTC",
    is_buy=True,
    sz=0.002,
    limit_px=59500,
    order_type={"limit": {"tif": "Gtc"}}
)

Boas práticas de tratamento de erros

Em trading programático, tratamento de erros robusto é tão importante quanto a lógica da estratégia. Erros comuns podem envolver falhas de rede, timeouts, limites de frequência, rejeições por margem insuficiente, parâmetros inválidos ou mudanças inesperadas no estado da conta.

Um padrão básico de retry com backoff exponencial pode ser estruturado assim:

import time


def place_with_retry(exchange, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return exchange.order(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise

            wait = 2 ** attempt  # Backoff exponencial: 1s, 2s, 4s
            time.sleep(wait)

Além disso, registre logs detalhados, monitore respostas da API e trate separadamente erros recuperáveis e erros críticos. Em produção, o bot não deve continuar enviando ordens indefinidamente quando há inconsistência de saldo, posição ou preço.

Usando WebSocket para acompanhar execuções em tempo real

Polling via REST funciona para estratégias de baixa frequência. Para cenários mais sensíveis a latência, use WebSocket:

from hyperliquid.websocket_manager import WebsocketManager


def on_fill(data):
    print("Callback de execução:", data)


ws = WebsocketManager(base_url="wss://api.hyperliquid.xyz")

ws.subscribe(
    {"type": "userFills", "user": account.address},
    callback=on_fill
)

ws.start()

Consulte a documentação oficial da Hyperliquid para o formato completo das inscrições WebSocket.

Protegendo bots em produção com carteira hardware OneKey

Carteiras em software — hot wallets — armazenam a chave privada em memória ou em disco. Se o servidor for atacado, os fundos podem ser drenados rapidamente. Para bots de produção que gerenciam capital real, uma arquitetura mais segura é:

1. Conectar uma carteira hardware OneKey a um servidor de assinatura.
2. Fazer a lógica do bot gerar a mensagem de transação a ser assinada.
3. Enviar a mensagem para a OneKey, onde a assinatura acontece dentro do elemento seguro do hardware.
4. Retornar a assinatura ao bot e transmitir a ordem para a Hyperliquid.

Nesse modelo, a chave privada permanece sempre dentro do hardware e não pode ser exportada por software. O padrão EIP-712 de assinatura estruturada também permite que a OneKey exiba no dispositivo os detalhes da mensagem a ser assinada, possibilitando revisão manual quando necessário.

Também é recomendável configurar uma carteira API Agent dedicada para o bot — a Hyperliquid oferece suporte a contas/agentes autorizados — limitando a atuação a uma conta específica e reduzindo a exposição operacional.

Ferramentas e recursos úteis

• Documentação oficial da Hyperliquid: especificações de API e descrição de campos.
• Site oficial da OneKey: informações sobre carteiras hardware e produtos.
• Documentação do WalletConnect: útil caso você precise fazer ponte de assinatura via protocolo WalletConnect.

Perguntas frequentes

Q1: Qual é a diferença entre usar o SDK e chamar a REST API diretamente?

O SDK encapsula a lógica de assinatura, formatação de requisições e parte do tratamento de erros comuns, reduzindo código repetitivo. Chamar a REST API diretamente oferece mais flexibilidade, mas exige implementar a assinatura EIP-712 por conta própria. Para iniciantes, o SDK costuma ser o melhor ponto de partida; depois, você pode migrar partes específicas para chamadas HTTP nativas se fizer sentido.

Q2: Trading programático na Hyperliquid exige KYC?

A Hyperliquid é um protocolo descentralizado e, até o momento deste artigo, não exige KYC para operar com um endereço de carteira. Ainda assim, você deve acompanhar as regras aplicáveis à sua jurisdição. Questões regulatórias e de conformidade são responsabilidade do usuário.

Q3: Como evitar que o bot tenha perdas excessivas em condições extremas de mercado?

Implemente proteções na camada da estratégia, como: limite máximo de perda, pausa automática de novas ordens ao atingir esse limite, monitoramento da relação entre prejuízo não realizado e patrimônio da conta, uso de ordens de stop loss — como o tipo Sl — e verificação periódica de que as posições reais estão alinhadas com o estado esperado.

Q4: Como integrar uma carteira hardware OneKey a scripts automatizados?

Você pode usar o SDK oficial da OneKey para chamar interfaces de assinatura do hardware ou combinar conexão USB/Bluetooth com interfaces como eth_sign, dependendo da arquitetura. Em produção, normalmente o serviço de assinatura fica separado da lógica de trading, reduzindo a superfície de ataque.

Q5: A interface de ordens em lote tem limite de frequência?

Consulte a documentação oficial para a política de rate limit mais recente. Em geral, é prudente inserir pequenos intervalos entre requisições e implementar algoritmos como token bucket ou janela deslizante para controlar a frequência, evitando falhas por excesso de chamadas.

Conclusão: do script ao sistema de produção

O Hyperliquid SDK reduz bastante a barreira de entrada para trading programático. Mas sair de um “script que roda” para um sistema de produção confiável exige atenção séria a assinatura segura, tratamento de erros e gestão de risco.

Se você quer experimentar trading de perpétuos on-chain sem escrever código, o OneKey Perps oferece um fluxo visual e direto dentro do ecossistema OneKey, combinando uma experiência prática de trading com a segurança da autocustódia. Para equipes com capacidade de desenvolvimento, usar a OneKey como backend de assinatura para bots é uma das abordagens mais robustas de gestão de chaves no trading on-chain.

Para começar de forma mais simples, baixe ou experimente a OneKey, conecte sua carteira e acesse o OneKey Perps para operar com mais controle sobre a custódia dos seus ativos.

Aviso de risco: trading programático envolve riscos técnicos e de mercado elevados. Contratos perpétuos têm alavancagem e podem gerar perdas superiores ao valor inicialmente alocado. Este artigo é apenas uma referência técnica e não constitui recomendação de investimento, aconselhamento financeiro ou orientação jurídica. Avalie os riscos com cuidado e tome decisões de acordo com sua própria tolerância a risco. O mercado de criptoativos é altamente volátil, e desempenho passado não garante resultados futuros.