A plataforma Hyperliquid se destaca como uma exchange descentralizada de alto desempenho para futuros perpétuos, oferecendo negociação de baixa latência e recursos avançados para desenvolvedores. Desenvolvedores frequentemente recorrem à API da Hyperliquid para automatizar negociações, monitorar mercados e construir aplicações personalizadas.
Você começa compreendendo os componentes centrais da API da Hyperliquid. A API se divide em categorias principais: a API de Informações (Info API) para consultar dados de mercado, a API de Exchange (Exchange API) para ações de negociação e o WebSocket para atualizações em tempo real. Além disso, SDKs em linguagens como Python e Node.js simplificam as interações. À medida que você avança, verá como pequenos ajustes nos parâmetros de requisição levam a melhorias significativas na eficiência da execução.
O Que É a API da Hyperliquid?
A API da Hyperliquid permite acesso programático à exchange descentralizada de futuros perpétuos da Hyperliquid. Ela suporta operações em ambientes mainnet e testnet. Você se conecta à mainnet e à testnet. A API usa JSON para requisições e respostas, dependendo de HTTP POST para a maioria das ações e WebSocket para assinaturas.
Você se autentica usando chaves privadas em vez de chaves de API tradicionais em alguns casos, mas a Hyperliquid também oferece carteiras de API para delegação segura. Essas carteiras agem em nome de sua conta principal sem permissões de saque, aumentando a segurança para negociações automatizadas. Por exemplo, você gera uma carteira de API através do aplicativo Hyperliquid, a autoriza e usa sua chave privada em seus scripts.
Em seguida, considere os tipos de dados. A API emprega structs e enums específicos. Os ativos são identificados por índices da lista do universo, os lados da ordem usam booleanos (true para compra, false para venda), e as opções de tempo em vigor (time-in-force) incluem 'Gtc' para 'good 'til canceled' (válida até ser cancelada). Você recupera esses detalhes dos endpoints de metadados para garantir a precisão em suas requisições.
Com esta base, você passa para a configuração do seu ambiente de desenvolvimento. Uma configuração adequada evita erros comuns e acelera a iteração.
Configurando Seu Ambiente para a API da Hyperliquid
Você inicia a configuração escolhendo sua linguagem de programação e instalando o SDK relevante. Para usuários de Python, o hyperliquid-python-sdk oferece um ponto de partida robusto. Instale-o via pip com o comando pip install hyperliquid-python-sdk. Este SDK lida com conexões, autenticação e operações comuns.
Em seguida, você configura suas credenciais. Crie um arquivo config.json com o endereço da sua conta (chave pública) e a chave secreta (chave privada). Para segurança, você gera uma carteira de API dedicada. Navegue até o aplicativo Hyperliquid, selecione "Mais > API", insira um nome para a chave, cole o endereço da sua carteira e clique em "Gerar". Autorize a carteira de API e copie sua chave privada para sua configuração.
O SDK importa constantes para URLs, como constants.TESTNET_API_URL para testes. Você inicializa clientes assim:
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
Esta configuração ignora o WebSocket inicialmente, focando em HTTP. Você testa a conexão consultando o estado do usuário:
user_state = info.user_state("your_account_address")
print(user_state)
Se a resposta mostrar os detalhes da sua conta, seu ambiente está funcionando corretamente. No entanto, se você encontrar erros, verifique sua chave privada e a seleção de rede.
Para Node.js, você usa o pacote @nktkas/hyperliquid. Instale-o com npm, então configure transportes e clientes usando ethers para gerenciamento de carteira. Você especifica isTestnet: true para evitar fundos reais durante o desenvolvimento.
Ferramentas como o Apidog complementam esta configuração. Você importa as especificações da API da Hyperliquid para o Apidog, autentica com suas chaves e simula requisições. Essa abordagem revela rapidamente as estruturas de resposta, economizando tempo na codificação manual.
Uma vez configurado, você avança para os métodos de autenticação. A autenticação adequada garante que suas ações sejam executadas com segurança.
Autenticando com a API da Hyperliquid
Você se autentica principalmente através da assinatura de chave privada, já que a Hyperliquid opera em um sistema baseado em blockchain. Os SDKs lidam com a assinatura automaticamente quando você fornece uma instância de carteira.
Para chamadas diretas à API sem SDKs, você assina os payloads usando sua chave privada. O corpo da requisição inclui um nonce para proteção contra replay, e você faz POST para os endpoints /exchange ou /info.
As carteiras de API adicionam flexibilidade. Você cria uma nomeando-a, vinculando-a ao endereço da sua carteira principal, gerando a chave e autorizando-a. Esta carteira realiza negociações, mas não pode sacar fundos, reduzindo o risco para bots. No código, você usa a chave privada da carteira de API enquanto especifica o endereço da conta principal.
Você testa a autenticação enviando uma requisição de informações simples. Se não autorizado, a API retorna um erro como "User or API Wallet does not exist." Para corrigir isso, certifique-se de que sua carteira possua garantia mínima, como USDC para futuros perpétuos.
A segurança permanece primordial. Você armazena chaves em variáveis de ambiente ou cofres seguros, as rotaciona periodicamente e monitora atividades incomuns. Com a autenticação configurada, você explora os endpoints da API de Informações.
Explorando os Endpoints da API de Informações
A API de Informações fornece acesso somente leitura a dados de mercado e de conta. Você a usa para buscar metadados, preços, ordens e muito mais, sem autenticação para dados públicos.
Você começa com o endpoint meta, que retorna o universo de ativos e contextos. Em Node.js:
const [meta] = await infoClient.metaAndAssetCtxs();
Isso retorna um array de ativos com nomes, índices e especificações como alavancagem máxima. Você usa o índice do ativo em requisições de negociação.
Em seguida, você consulta os preços médios com allMids, que retorna os pontos médios atuais para todos os pares. Ordens abertas vêm de openOrders, exigindo seu endereço.
Outros endpoints incluem:
- userState: Recupera posições, margens e saldos.
- fundingHistory: Mostra as taxas de financiamento ao longo do tempo.
- l2Book: Fornece o livro de ordens de nível 2 para uma moeda.
Você envia requisições POST com corpos JSON como {"type": "meta"} para /info. As respostas usam estruturas consistentes, com "data" contendo os resultados.
O Apidog ajuda aqui — você configura uma coleção para a API de Informações, adiciona requisições para cada tipo e parametriza moedas ou endereços. Essa visualização auxilia na compreensão do fluxo de dados.
À medida que você coleta dados, você transita para a API de Exchange para executar negociações.
Usando os Endpoints da API de Exchange para Negociação
A API de Exchange lida com ações como fazer ordens, cancelar e modificar. Você autentica todas as requisições com payloads assinados.
Você coloca ordens definindo parâmetros: índice do ativo, lado, preço, tamanho, flag de 'reduce-only' e tipo (limit ou market). Para uma venda a limite:
Em Elixir (da documentação do SDK):
Hyperliquid.Api.Exchange.place_order(order)
Onde order é um mapa com a: ativo, b: false (venda), p: "100", s: "0.1", r: false, t: {limit: {tif: "Gtc"}}.
A resposta inclui status e ID da ordem se bem-sucedida.
Você cancela ordens usando o ativo e oid (ID da ordem):
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
Para lotes, você usa cancel_orders com uma lista.
As modificações seguem de forma semelhante: especifique oid e novos parâmetros.
Outras ações incluem a atualização da alavancagem:
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
E transferências, como spot_perp_transfer para mover fundos entre contas.
Você lida com erros verificando o status da resposta — "ok" para sucesso, caso contrário, detalhes como margem insuficiente.
Exemplos demonstram uso prático. Por exemplo, você constrói um bot que coloca uma ordem de compra quando o preço cai abaixo de um limite, usando a API de informações para verificações de preço e a API de exchange para o posicionamento.
Além disso, você integra o WebSocket para atualizações em tempo real para aumentar a responsividade.
Integrando WebSocket para Dados em Tempo Real
Você se conecta ao WebSocket para streams ao vivo. Use wss://api.hyperliquid.xyz/ws para a mainnet ou o equivalente da testnet.
Você se inscreve enviando JSON: {"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}.
O servidor responde com confirmação, então envia atualizações como novas negociações.
Você lida com tópicos como livro de ordens (orderbook), eventos de usuário e notificações. No SDK Python, defina skip_ws=False para habilitar.
Essa capacidade em tempo real permite que você reaja instantaneamente às mudanças do mercado, como ajustar ordens em preenchimentos.
Com os endpoints abordados, você examina o SDK Python em profundidade.
Aproveitando o SDK Python da Hyperliquid
O SDK Python abstrai as chamadas de API em classes. Você importa Info para consultas e Exchange para ações.
Você coloca uma ordem básica assim (dos exemplos):
Primeiro, carregue a configuração:
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
Em seguida, inicialize a Exchange:
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
Coloque a ordem:
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
Isso compra 0.02 BTC a $30.000 a limite.
Você estende isso para recursos avançados, como ordens em lote ou cancelamentos.
O SDK também suporta endereços de vault para contas gerenciadas.
Exemplos no repositório cobrem basic_order, user_state e mais, demonstrando fluxos de trabalho completos.
À medida que você constrói, você incorpora as melhores práticas para otimizar o desempenho.
Melhores Práticas para o Uso da API da Hyperliquid
Você monitora os limites de taxa para evitar o estrangulamento (throttling) — a Hyperliquid impõe limites por IP e por conta.
Você usa a testnet para todo o desenvolvimento para evitar perdas financeiras.
O tratamento de erros envolve o registro de detalhes e a nova tentativa de falhas transitórias com backoff.
Para escalabilidade, você agrupa requisições quando possível, como múltiplos cancelamentos.
A segurança se estende ao uso de carteiras de API e princípios de privilégio mínimo.
Você também versiona seu código com as atualizações do SDK, já que a Hyperliquid segue o versionamento semântico.
Ferramentas como o Apidog auxiliam na simulação (mocking) de respostas para testes de unidade.
A solução de problemas (troubleshooting) vem em seguida quando surgem problemas.
Solução de Problemas Comuns da API da Hyperliquid
Você encontra "Insufficient margin" (margem insuficiente) quando a garantia está baixa — deposite USDC para resolver.
Se "Asset not found" (ativo não encontrado), verifique os índices do meta.
Erros de autenticação resultam de chaves inválidas — regenere e autorize as carteiras de API.
Problemas de rede exigem a verificação de URLs e o uso de proxies, se necessário.
Você depura com o Apidog reproduzindo requisições falhas.
Logs dos SDKs fornecem timestamps e payloads para análise.
Com essas dicas, você mantém integrações confiáveis.
Casos de Uso Avançados com a API da Hyperliquid
Você constrói bots de negociação que monitoram o l2Book e colocam ordens em desequilíbrios.
Estratégias envolvem taxas de financiamento do histórico para oportunidades de arbitragem.
Subcontas permitem negociação segregada: crie com nome, transfira fundos e negocie separadamente.
Transferências de vault suportam pools de liquidez compartilhada.
Você simula com dados históricos da API para backtest.
A integração com o Apidog permite depuração colaborativa em equipes.
Finalmente, você conclui considerando futuras melhorias.
Conclusão: Dominando a API da Hyperliquid para Negociação Descentralizada
Você agora possui o conhecimento para usar eficazmente a API da Hyperliquid. Desde a configuração e autenticação até os endpoints e SDKs, este guia o equipa para construir aplicações sofisticadas. Lembre-se, refinamentos incrementais em seu código resultam em ganhos substanciais de desempenho. Experimente na testnet, aproveite ferramentas como o Apidog e mantenha-se atualizado com a documentação da Hyperliquid. À medida que a plataforma evolui, suas habilidades o posicionam para capitalizar em novos recursos.