Como buscar dados históricos da Hyperliquid via API
-
hyperliquid historical data
-
hyperliquid data api
-
hyperliquid dados históricos
-
hyperliquid dados de candles
-
hyperliquid histórico de funding rate
Dados são a base de qualquer pesquisa quantitativa. Seja para fazer backtest de estratégias, analisar padrões de funding rate ou estudar microestrutura de mercado, você precisa de dados históricos confiáveis e completos. A Hyperliquid, uma exchange on-chain de contratos perpétuos, oferece por meio de sua REST API vários endpoints de dados históricos, incluindo candles OHLCV, funding rates, trades, preenchimentos de ordens e eventos de liquidação.
Neste guia, vamos organizar os principais métodos para buscar esses dados, explicar parâmetros, estratégias de paginação e boas práticas de armazenamento local. Em cenários que envolvem endpoints autenticados, a carteira de hardware OneKey pode ajudar a assinar requisições com mais segurança, mantendo a chave privada fora dos scripts de coleta.
Visão geral da API de dados históricos da Hyperliquid
Segundo a documentação oficial da Hyperliquid, os dados históricos são acessados principalmente pelo endpoint POST /info. O campo type no corpo da requisição define qual tipo de dado será consultado.
Todos os timestamps usam o formato Unix em milissegundos, ou seja, inteiros de 13 dígitos.
Como obter dados de candles OHLCV
Formato da requisição
import requests
BASE_URL = "https://api.hyperliquid.xyz"
def fetch_candles(coin, interval, start_ms, end_ms):
"""
coin : par/mercado, por exemplo "BTC"
interval : granularidade, por exemplo "1m", "5m", "1h", "1d"
start_ms : horário inicial em timestamp de milissegundos
end_ms : horário final em timestamp de milissegundos
"""
payload = {
"type": "candleSnapshot",
"req": {
"coin": coin,
"interval": interval,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
# Exemplo: buscar candles de 1 hora do BTC nos últimos 7 dias
import time
end_ms = int(time.time() * 1000)
start_ms = end_ms - 7 * 24 * 3600 * 1000
candles = fetch_candles("BTC", "1h", start_ms, end_ms)
Campos retornados
Cada candle contém campos como os abaixo, sempre considerando a documentação oficial como referência final:
t: horário de abertura do candle, em timestamp de milissegundoso: preço de abertura, ou openh: máxima, ou highl: mínima, ou lowc: fechamento, ou closev: volumen: número de trades
Estratégia de paginação
Uma única requisição normalmente tem limite de quantidade de registros retornados. Para intervalos longos, o ideal é dividir o período em blocos menores, buscar cada bloco e depois consolidar os resultados.
import time
def fetch_candles_paginated(coin, interval, start_ms, end_ms, page_size_ms):
"""
Divide o intervalo total em partes menores, busca cada parte e junta os resultados.
page_size_ms: tamanho de cada bloco em milissegundos, ajustado conforme o interval.
"""
all_candles = []
cursor = start_ms
while cursor < end_ms:
batch_end = min(cursor + page_size_ms, end_ms)
batch = fetch_candles(coin, interval, cursor, batch_end)
all_candles.extend(batch)
if not batch:
break
# A próxima página começa no timestamp do último candle + 1 ms
cursor = batch[-1]["t"] + 1
time.sleep(0.2) # ajuda a evitar rate limit
return all_candles
Histórico de funding rate
O funding rate é um mecanismo central dos contratos perpétuos. O histórico de funding pode ser útil para estudar sentimento de mercado, custo de carregamento de posições e possíveis estratégias de arbitragem, sempre considerando riscos e custos operacionais.
def fetch_funding_history(coin, start_ms, end_ms):
payload = {
"type": "fundingHistory",
"req": {
"coin": coin,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
Os dados retornados incluem o valor do funding rate em cada período de liquidação e o respectivo timestamp. Esse histórico pode ser usado para:
- analisar mudanças no viés entre comprados e vendidos;
- identificar momentos de sentimento extremo;
- estimar custo de manter posições alavancadas ao longo do tempo.
Trades do usuário e histórico de ordens
Endpoints que envolvem dados privados do usuário exigem o endereço da carteira e, em alguns casos, autenticação por assinatura. A carteira de hardware OneKey pode ser usada para assinar esse tipo de requisição com segurança: a chave privada permanece no elemento seguro do dispositivo e não fica exposta ao servidor ou ao script de coleta.
def fetch_user_fills(address, start_ms, end_ms):
payload = {
"type": "userFills",
"req": {
"user": address,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
Os fills normalmente incluem campos como ID da ordem, lado da operação, preço de execução, quantidade preenchida e taxas. Esses dados são essenciais para calcular PnL realizado, medir slippage e avaliar a qualidade de execução de uma estratégia.
Registros de liquidação
Dados de liquidação em nível de mercado ajudam a estudar estrutura de mercado e comportamento em períodos de volatilidade extrema.
def fetch_liquidations(start_ms, end_ms):
payload = {
"type": "liquidations",
"req": {
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
Armazenamento dos dados: CSV e banco de dados
Salvando em CSV
Na fase de prototipagem, CSV costuma ser a forma mais simples de persistir os dados.
import csv
def save_candles_to_csv(candles, filepath):
if not candles:
return
fieldnames = ["t", "o", "h", "l", "c", "v", "n"]
with open(filepath, "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fieldnames)
writer.writeheader()
for candle in candles:
writer.writerow({k: candle.get(k, "") for k in fieldnames})
Salvando em banco de dados
Para volumes maiores ou consultas frequentes, considere SQLite para uso local e PostgreSQL para ambientes de produção.
import sqlite3
def init_db(db_path):
conn = sqlite3.connect(db_path)
conn.execute("""
CREATE TABLE IF NOT EXISTS candles (
coin TEXT,
interval TEXT,
t INTEGER,
o REAL,
h REAL,
l REAL,
c REAL,
v REAL,
n INTEGER,
PRIMARY KEY (coin, interval, t)
)
""")
conn.commit()
return conn
def insert_candles(conn, coin, interval, candles):
rows = [
(coin, interval, c["t"], c["o"], c["h"], c["l"], c["c"], c["v"], c["n"])
for c in candles
]
conn.executemany(
"INSERT OR IGNORE INTO candles VALUES (?,?,?,?,?,?,?,?,?)",
rows
)
conn.commit()
A chave primária PRIMARY KEY (coin, interval, t) evita duplicidade quando você refaz uma coleta ou executa atualizações incrementais.
Rate limit e cuidados práticos
A API da Hyperliquid possui limites de frequência de requisições. Consulte sempre a documentação oficial atualizada. Na prática, algumas boas medidas são:
- adicionar pausas entre requisições em loop, por exemplo de 200 ms a 500 ms;
- implementar retry com backoff exponencial;
- ao receber HTTP 429, aguardar antes de tentar novamente;
- fazer grandes coletas históricas fora de períodos de pico, quando possível;
- manter cache local para não solicitar repetidamente os mesmos intervalos.
Comparação com outras fontes de dados
A vantagem da API nativa da Hyperliquid é que os dados vêm diretamente da fonte, com maior proximidade do ambiente de negociação. Para pesquisas que exigem dados de múltiplas exchanges ou protocolos, você pode combinar essa fonte com outras. As documentações da dYdX e da GMX também oferecem APIs de dados históricos, com estilos de interface diferentes, mas conceitos semelhantes.
Perguntas frequentes
Q1: Qual é a menor granularidade dos candles?
Consulte a seção candleSnapshot na documentação oficial da Hyperliquid. Até o momento considerado neste artigo, há suporte a múltiplas granularidades, incluindo minutos, horas e dias. Os valores exatos aceitos em interval devem ser verificados na documentação, e a API retorna erro quando o parâmetro é inválido.
Q2: Até onde os dados históricos retrocedem?
Em princípio, os dados disponíveis desde o lançamento de cada mercado podem ser consultados pela API. Na prática, o período acessível depende de quando aquele mercado específico começou a negociar. Se não houver dados para determinado intervalo, a API pode retornar um array vazio.
Q3: Quanto tempo leva para baixar um histórico grande?
Depende do intervalo total, da granularidade e da estratégia de paginação. Para candles de 1 hora em um histórico completo, levando em conta rate limits, a coleta pode levar de alguns minutos a dezenas de minutos. O ideal é salvar os dados em banco e depois fazer apenas atualizações incrementais.
Q4: Qual é o papel da OneKey na coleta de dados?
Dados públicos de mercado, como candles e funding rates, podem ser acessados sem autenticação. Já endpoints com dados privados do usuário, como histórico de fills e ordens, podem exigir assinatura. A carteira de hardware OneKey pode fornecer essa assinatura de forma segura, ajudando a evitar que a chave privada fique exposta ao ambiente onde o script roda.
Q5: Como lidar com lacunas nos dados?
Falhas de rede, limites de API ou indisponibilidades temporárias podem deixar buracos no histórico. Registre os intervalos coletados, faça verificações periódicas em busca de gaps e execute novas coletas apenas nos trechos faltantes. Para backtests, essa validação é importante, pois lacunas podem distorcer sinais e resultados.
Conclusão
A API de dados históricos da Hyperliquid oferece uma base sólida para pesquisa quantitativa em perps on-chain. Com poucas dezenas de linhas em Python, é possível montar um pipeline para coletar candles, funding rates, fills de usuário e liquidações. Para fluxos que exigem assinatura, a OneKey ajuda a proteger a chave privada enquanto você trabalha com dados e automações.
Se você quer transformar análise em execução de forma mais prática, experimente baixar o app da OneKey e usar o OneKey Perps como fluxo operacional para negociar contratos perpétuos com mais controle sobre sua carteira e suas assinaturas.
Aviso de risco: dados históricos refletem apenas condições passadas de mercado e não indicam desempenho futuro. Estratégias quantitativas baseadas em backtests podem sofrer overfitting, e resultados em conta real podem diferir bastante dos testes. A negociação de contratos perpétuos envolve alto risco e pode causar perdas. Este conteúdo é apenas para fins técnicos e educacionais, não constituindo aconselhamento financeiro, jurídico ou de investimento.
