Assinatura do livro de ofertas em tempo real da Hyperliquid
-
hyperliquid orderbook websocket
-
real time hyperliquid api
-
hyperliquid livro de ofertas em tempo real
-
hyperliquid websocket subscribe
-
hyperliquid l2 book
O livro de ofertas é uma das estruturas de dados mais importantes de uma exchange. Ele mostra, em tempo real, a distribuição de preços e quantidades das ordens de compra e venda ainda não executadas. Para bots de trading quantitativo, sistemas de arbitragem e painéis de análise de mercado, receber o estado mais recente do livro com latência de milissegundos pode ser decisivo para a qualidade da estratégia.
A Hyperliquid oferece uma interface WebSocket completa para receber snapshots e atualizações incrementais do livro L2 em tempo real. Neste artigo, vamos abordar o formato de assinatura, a estrutura das mensagens, a manutenção de um livro de ofertas local e cuidados de engenharia para produção, como reconexão após queda. Para quem não quer construir essa infraestrutura do zero, o OneKey Perps já integra visualização de mercado em tempo real e um fluxo de trading pronto para uso.
WebSocket vs. polling via REST
Antes dos detalhes técnicos, vale entender por que usar WebSocket em vez de consultar uma API REST repetidamente.
Para casos que exigem livro de ofertas em tempo real, polling via REST quase nunca substitui bem uma conexão WebSocket. Consulte a documentação oficial da Hyperliquid para ver a especificação completa da interface WebSocket.
Estabelecendo a conexão WebSocket
Endpoint
O endpoint WebSocket da Hyperliquid, conforme a documentação oficial no momento deste artigo, é:
wss://api.hyperliquid.xyz/ws
Código básico de conexão
import asyncio
import json
import websockets
WS_URL = "wss://api.hyperliquid.xyz/ws"
async def connect_and_subscribe():
async with websockets.connect(WS_URL) as ws:
# Envia a mensagem de assinatura
subscribe_msg = {
"method": "subscribe",
"subscription": {
"type": "l2Book",
"coin": "BTC"
}
}
await ws.send(json.dumps(subscribe_msg))
# Recebe mensagens continuamente
async for raw_msg in ws:
msg = json.loads(raw_msg)
handle_message(msg)
asyncio.run(connect_and_subscribe())
Formato da mensagem de assinatura
Assinatura do livro L2
Para assinar o livro L2 de BTC:
{
"method": "subscribe",
"subscription": {
"type": "l2Book",
"coin": "BTC"
}
}
A Hyperliquid permite assinar vários pares ao mesmo tempo. Basta enviar mensagens de assinatura separadas; cada mercado receberá suas próprias atualizações.
Cancelamento da assinatura
{
"method": "unsubscribe",
"subscription": {
"type": "l2Book",
"coin": "BTC"
}
}
Tipos de mensagem: snapshot e atualizações incrementais
Snapshot inicial
Após a assinatura, o servidor envia primeiro um snapshot completo do livro, com a liquidez disponível em todos os níveis de preço:
{
"channel": "l2Book",
"data": {
"coin": "BTC",
"time": 1714500000000,
"levels": [
[
[{"px": "64000.0", "sz": "0.5", "n": 3}],
[{"px": "64010.0", "sz": "0.3", "n": 2}]
]
]
}
}
px: preçosz: quantidade total naquele nível de preço; quando for0, indica que o nível foi esvaziadon: número de ordens naquele nível de preço
No exemplo, os bids, ou ordens de compra, vêm do maior para o menor preço. Os asks, ou ordens de venda, vêm do menor para o maior preço.
Atualização incremental, ou delta
Depois do snapshot, o servidor passa a enviar apenas os níveis de preço que mudaram:
{
"channel": "l2Book",
"data": {
"coin": "BTC",
"time": 1714500000100,
"levels": [
[
[{"px": "63990.0", "sz": "0.0", "n": 0}],
[{"px": "64010.0", "sz": "0.8", "n": 4}]
]
]
}
}
Quando sz for "0", "0.0" ou 0, significa que todas as ordens daquele nível foram executadas ou canceladas. Nesse caso, o nível deve ser removido do livro local.
Mantendo o estado local do livro de ofertas
Manter corretamente o livro local é o principal desafio ao consumir dados via WebSocket:
from sortedcontainers import SortedDict
class LocalOrderBook:
def __init__(self, coin):
self.coin = coin
self.bids = SortedDict(lambda x: -float(x)) # compras: maior preço primeiro
self.asks = SortedDict(lambda x: float(x)) # vendas: menor preço primeiro
self.last_time = None
def apply_snapshot(self, data):
self.bids.clear()
self.asks.clear()
levels = data["levels"][0]
for bid in levels[0]:
if float(bid["sz"]) > 0:
self.bids[bid["px"]] = float(bid["sz"])
for ask in levels[1]:
if float(ask["sz"]) > 0:
self.asks[ask["px"]] = float(ask["sz"])
self.last_time = data["time"]
def apply_delta(self, data):
levels = data["levels"][0]
for bid in levels[0]:
px, sz = bid["px"], float(bid["sz"])
if sz == 0:
self.bids.pop(px, None)
else:
self.bids[px] = sz
for ask in levels[1]:
px, sz = ask["px"], float(ask["sz"])
if sz == 0:
self.asks.pop(px, None)
else:
self.asks[px] = sz
self.last_time = data["time"]
@property
def best_bid(self):
return next(iter(self.bids.items()), None)
@property
def best_ask(self):
return next(iter(self.asks.items()), None)
@property
def mid_price(self):
bid = self.best_bid
ask = self.best_ask
if bid and ask:
return (float(bid[0]) + float(ask[0])) / 2
return None
@property
def spread(self):
bid = self.best_bid
ask = self.best_ask
if bid and ask:
return float(ask[0]) - float(bid[0])
return None
Lógica de processamento das mensagens
A lógica básica é identificar se a mensagem inicial deve ser tratada como snapshot e, depois disso, aplicar os deltas ao estado local:
order_book = LocalOrderBook("BTC")
is_initialized = False
def handle_message(msg):
global is_initialized
if msg.get("channel") != "l2Book":
return
data = msg["data"]
if not is_initialized:
order_book.apply_snapshot(data)
is_initialized = True
print(
f"Livro inicializado: {len(order_book.bids)} níveis de compra, "
f"{len(order_book.asks)} níveis de venda"
)
else:
order_book.apply_delta(data)
# Exibe informações do book
print(
f"Melhor compra: {order_book.best_bid}, "
f"melhor venda: {order_book.best_ask}, "
f"spread: {order_book.spread}"
)
Tratamento de quedas e reconexão
Conexões WebSocket podem cair por instabilidade de rede ou por encerramento do lado do servidor. Um sistema de produção precisa implementar reconexão automática:
import asyncio
import json
import websockets
async def subscribe_with_reconnect(coin, handle_fn, max_retries=None):
retries = 0
while max_retries is None or retries < max_retries:
try:
async with websockets.connect(
WS_URL,
ping_interval=20,
ping_timeout=10
) as ws:
retries = 0 # conexão bem-sucedida; reseta contador
is_initialized = False
await ws.send(json.dumps({
"method": "subscribe",
"subscription": {"type": "l2Book", "coin": coin}
}))
async for raw_msg in ws:
handle_fn(json.loads(raw_msg))
except (websockets.ConnectionClosed, ConnectionError, OSError) as e:
retries += 1
wait = min(2 ** retries, 60) # backoff exponencial, máximo de 60s
print(f"Conexão caiu ({e}); tentando de novo em {wait}s, tentativa {retries}")
is_initialized = False # na próxima conexão, aguarde novo snapshot
await asyncio.sleep(wait)
Ao reconectar, é importante resetar a flag is_initialized, porque o servidor deve enviar novamente um snapshot completo após a nova assinatura, não uma continuação dos deltas anteriores.
Sequência e ordem das mensagens
As mensagens WebSocket da Hyperliquid incluem um campo de timestamp, que pode ser usado para detectar mensagens fora de ordem. Em sistemas de produção, recomenda-se:
- Registrar o timestamp da última mensagem processada; se uma nova mensagem tiver timestamp anterior, trate-a como antiga e descarte.
- Se não houver mensagens por um período incomum, envie ping ou reconecte ativamente.
- Em estratégias de alta frequência, considerar infraestrutura com menor latência, como nós geograficamente mais próximos ou conectividade dedicada.
Assinando vários mercados ao mesmo tempo
Uma única conexão WebSocket pode assinar vários pares. Para isso, uma arquitetura assíncrona costuma ser mais simples de manter:
coins = ["BTC", "ETH", "SOL"]
order_books = {coin: LocalOrderBook(coin) for coin in coins}
async def multi_subscribe():
async with websockets.connect(WS_URL) as ws:
for coin in coins:
await ws.send(json.dumps({
"method": "subscribe",
"subscription": {"type": "l2Book", "coin": coin}
}))
async for raw_msg in ws:
msg = json.loads(raw_msg)
if msg.get("channel") == "l2Book":
coin = msg["data"]["coin"]
if coin in order_books:
order_books[coin].apply_delta(msg["data"])
Aplicações práticas
Dados de livro de ofertas em tempo real são usados em diversos cenários:
- Bots de trading: ajustar dinamicamente preços de ordens com base no spread e na profundidade do book.
- Sistemas de arbitragem: monitorar diferenças de preço entre Hyperliquid e outras plataformas, como dYdX e GMX.
- Dashboards de mercado: visualizar profundidade do livro, histórico de spread e distribuição de liquidez.
- Sistemas de risco: disparar alertas quando o spread aumenta de forma anormal ou a liquidez cai rapidamente.
OneKey Perps: sem precisar construir infraestrutura própria
Criar e manter um sistema próprio de livro de ofertas via WebSocket exige esforço de engenharia: reconexão, consistência do estado local, monitoramento, latência e tratamento de falhas.
Se o seu objetivo é operar contratos perpétuos, e não desenvolver uma infraestrutura quantitativa completa, o OneKey Perps oferece uma experiência prática com dados de mercado em tempo real e execução de trades em um fluxo integrado. Combinado à assinatura segura via carteira hardware OneKey, ele permite que você foque na tomada de decisão, mantendo uma separação mais clara entre custódia, assinatura e operação.
Para usuários que querem se conectar a aplicações descentralizadas via WalletConnect, a documentação do WalletConnect traz orientações de integração. A OneKey oferece suporte ao protocolo WalletConnect padrão, permitindo interagir com aplicações Web3 como a Hyperliquid de forma mais segura.
Se você busca um caminho direto para acompanhar o mercado e operar perps sem montar todo o backend de book, baixe ou experimente a OneKey e acesse o OneKey Perps pelo fluxo do aplicativo. Avalie o produto com calma, entenda os riscos e use apenas se ele fizer sentido para o seu perfil operacional.
Perguntas frequentes
Q1: A conexão WebSocket tem limite de concorrência?
Consulte a documentação oficial da Hyperliquid para ver limites de conexão. Em geral, evite abrir muitas conexões simultâneas a partir do mesmo IP. Para múltiplos mercados, prefira reutilizar uma única conexão sempre que possível.
Q2: Se eu perder uma mensagem incremental, o livro local fica incorreto?
Sim. Se um delta for perdido por problema de rede, o estado local pode divergir do estado real do servidor. A prática recomendada é fechar a conexão e assinar novamente quando houver suspeita de inconsistência, como spread anormal ou salto inesperado no melhor preço, para receber um novo snapshot.
Q3: Dados de livro de ofertas em tempo real servem para backtest?
Diretamente, não é o ideal. Backtest exige dados históricos, não apenas um fluxo em tempo real. Uma abordagem é armazenar os dados recebidos como tick data ao longo do tempo e, depois de acumular histórico suficiente, usá-los em pesquisas. Também é possível combinar com APIs de candles históricos da Hyperliquid para estudos iniciais.
Q4: Como saber se a conexão WebSocket está saudável?
Monitore indicadores simples: se a última mensagem recebida está dentro de um limite aceitável, como 5 segundos, e se a latência ping/pong está em uma faixa razoável. Caso algum indicador fique fora do esperado, acione reconexão ativa.
Q5: A carteira OneKey afeta a latência das ordens?
A assinatura com a carteira hardware OneKey normalmente leva centenas de milissegundos, o que é aceitável para a maioria das estratégias de trading. Para estratégias de frequência muito alta, como dezenas de ordens por segundo, pode ser mais adequado usar uma subconta API Agent com hot wallet para assinaturas frequentes, enquanto a conta principal e a gestão de fundos permanecem protegidas pela OneKey, separando responsabilidades.
Conclusão
A assinatura do livro de ofertas em tempo real é uma fonte de dados essencial para sistemas quantitativos de qualidade. A API WebSocket da Hyperliquid tem um desenho claro e, com uma boa estrutura de snapshot, delta, reconexão e validação de mensagens, desenvolvedores conseguem montar um book local confiável para bots de market making, arbitragem ou painéis de análise.
Para quem quer operar perps on-chain sem lidar com a camada de engenharia, o OneKey Perps é uma alternativa prática: combina visualização de mercado, fluxo de trading e assinatura segura com carteira hardware OneKey. Ainda assim, use com cautela, teste o fluxo antes e mantenha uma gestão de risco adequada.
Aviso de risco: dados de livro de ofertas em tempo real refletem apenas o estado do mercado em um momento específico e não devem ser usados como único critério de decisão. Estratégias automatizadas baseadas em book podem gerar perdas relevantes por volatilidade extrema, falhas técnicas ou erros de desenho da estratégia. Trading de contratos perpétuos envolve alto risco e pode resultar na perda total do capital. Este conteúdo é apenas uma referência técnica e não constitui recomendação de investimento, aconselhamento financeiro ou orientação legal. Opere somente depois de compreender os riscos.
