Guia completo da API de histórico de funding rate da Hyperliquid

Funding rate, ou taxa de financiamento, é um dos principais mecanismos de precificação nos mercados de contratos perpétuos. Ela influencia diretamente o custo de manter posições long ou short. Para pesquisadores de estratégias quantitativas, traders de arbitragem e equipes de gestão de risco, conseguir acessar rapidamente dados históricos de funding rate em lote é uma capacidade essencial.

A Hyperliquid oferece endpoints públicos de consulta de dados de mercado, sem necessidade de API Key. Neste guia, você verá como usar a API oficial da Hyperliquid para obter o histórico de funding rate, com exemplos em Python para começar de forma prática.

Por que o histórico de funding rate é importante

Dados históricos de funding rate são úteis para várias análises, incluindo:

• Identificar estruturas de mercado persistentemente enviesadas para long ou short, ajudando na leitura de tendência
• Calcular o retorno esperado histórico de estratégias de funding arbitrage
• Construir fatores quantitativos baseados em funding rate para seleção de ativos ou gestão de posição
• Fazer backtests de estratégias hedgeadas entre spot e perpétuos em diferentes ambientes de taxa

A arquitetura da Hyperliquid é baseada em um order book on-chain, e os dados de negociação e liquidação podem ser verificados on-chain. Isso aumenta a confiabilidade dos dados históricos usados em pesquisa e monitoramento.

Estrutura básica da API da Hyperliquid

A Hyperliquid oferece dois tipos principais de endpoint:

• Info Endpoint, somente leitura: usado para consultar dados de mercado, status de conta e históricos. Não exige assinatura.
• Exchange Endpoint: usado para operações como envio e cancelamento de ordens. Exige assinatura da carteira.

A consulta de histórico de funding rate é uma operação somente leitura e usa o Info Endpoint:

POST https://api.hyperliquid.xyz/info

Todas as requisições são feitas via POST, com body em JSON e Content-Type definido como application/json.

Estrutura da requisição para consultar funding rate histórico

Para obter o histórico de funding rate de um ativo específico, use o tipo fundingHistory:

{
  "type": "fundingHistory",
  "coin": "BTC",
  "startTime": 1700000000000,
  "endTime": 1700086400000
}

Campos principais:

• type: deve ser fundingHistory
• coin: ticker do ativo, como BTC, ETH ou SOL
• startTime: timestamp Unix em milissegundos
• endTime: timestamp Unix em milissegundos

Os timestamps precisam estar em milissegundos. Se endTime não for informado, a API retorna os dados a partir de startTime até o momento atual, respeitando possíveis limites de quantidade por resposta.

Formato da resposta

A API retorna um array. Cada item contém dados como:

[
  {
    "coin": "BTC",
    "fundingRate": "0.0001",
    "premium": "0.00012",
    "time": 1700000000000
  }
]

Na Hyperliquid, o funding rate é liquidado a cada hora. Para detalhes do mecanismo, consulte a seção de Perpetuals na documentação oficial da Hyperliquid.

Exemplo completo em Python

O código abaixo mostra como buscar o histórico de funding rate do BTC nos últimos 30 dias e calcular uma taxa anualizada simples:

import requests
import time
import pandas as pd

ENDPOINT = "https://api.hyperliquid.xyz/info"


def get_funding_history(coin: str, days: int = 30) -> pd.DataFrame:
    end_ms = int(time.time() * 1000)
    start_ms = end_ms - days * 24 * 3600 * 1000

    payload = {
        "type": "fundingHistory",
        "coin": coin,
        "startTime": start_ms,
        "endTime": end_ms,
    }

    resp = requests.post(ENDPOINT, json=payload, timeout=15)
    resp.raise_for_status()

    data = resp.json()
    df = pd.DataFrame(data)

    df["time"] = pd.to_datetime(df["time"], unit="ms", utc=True)
    df["fundingRate"] = df["fundingRate"].astype(float)
    df["annualized"] = df["fundingRate"] * 24 * 365  # liquidação horária

    return df.sort_values("time")


if __name__ == "__main__":
    df = get_funding_history("BTC", days=30)
    print(df.tail(10).to_string(index=False))
    print(f"\nFunding rate anualizado médio em 30 dias: {df['annualized'].mean():.2%}")

Observação: esse cálculo anualizado é apenas uma extrapolação linear simples. O resultado real de uma estratégia pode ser afetado por reinvestimento, slippage, custos de empréstimo, taxas de negociação, liquidez e execução.

Como buscar dados de vários ativos em lote

Se você precisar consultar o funding rate de vários ativos, é possível fazer chamadas concorrentes:

import concurrent.futures

COINS = ["BTC", "ETH", "SOL", "ARB", "DOGE"]

with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    futures = {executor.submit(get_funding_history, c, 7): c for c in COINS}
    results = {}

    for future in concurrent.futures.as_completed(futures):
        coin = futures[future]
        results[coin] = future.result()

# Combinar em um único DataFrame
combined = pd.concat(results.values(), ignore_index=True)

pivot = combined.pivot_table(
    index="time",
    columns="coin",
    values="fundingRate",
    aggfunc="mean"
)

Esse formato facilita análises comparativas, como identificar quais mercados apresentam funding rate persistentemente alto ou baixo em determinado período.

Sugestões de armazenamento de dados

Para uso frequente, é recomendável armazenar o histórico em um banco de dados local, como SQLite ou TimescaleDB, em vez de requisitar os mesmos dados repetidamente:

import sqlite3

conn = sqlite3.connect("funding_rates.db")
df.to_sql("funding_history", conn, if_exists="append", index=False)
conn.close()

Também vale considerar uma lógica de deduplicação por coin e time, principalmente se você executar coletas recorrentes.

A Hyperliquid mantém um SDK oficial em Python no GitHub, que encapsula fluxos de autenticação e assinatura. Ele é mais adequado para desenvolvedores que também precisam executar operações de trading, não apenas consultar dados públicos.

Como gerenciar ativos da Hyperliquid com a OneKey

Analisar dados é apenas a primeira etapa. Para executar estratégias com capital real, a segurança operacional da carteira é igualmente importante.

A carteira hardware OneKey permite interagir com a Hyperliquid mantendo as chaves privadas protegidas em um dispositivo offline. Isso reduz riscos ligados a vazamento de API Key, phishing, malware e assinaturas indevidas em ambientes menos seguros.

Quando sua análise indicar uma possível oportunidade de arbitragem de funding rate ou uma estratégia hedgeada entre spot e perpétuos, você pode usar o OneKey Perps como fluxo prático para acessar a Hyperliquid com proteção de chave privada em nível hardware e uma experiência mais fluida para negociação de perpétuos.

Baixe e experimente a OneKey para organizar sua rotina de análise, custódia e execução. Use o OneKey Perps com gestão de risco clara, sem assumir que funding rates passados garantem resultados futuros.

Perguntas frequentes

Q1: A API de funding rate da Hyperliquid exige cadastro?

Não. O Info Endpoint é público e não exige API Key nem conta. Qualquer pessoa pode fazer chamadas para consultar dados históricos de funding rate disponíveis publicamente.

Q2: Quantos registros uma única requisição pode retornar?

A documentação oficial da Hyperliquid não especifica claramente um limite único para todas as consultas. Na prática, requisições com janelas muito longas podem ser truncadas. Uma abordagem mais robusta é consultar por blocos, por exemplo em intervalos de 7 dias, e implementar lógica de paginação ou repetição no código.

Q3: O funding rate costuma ser positivo ou negativo?

Quando o funding rate é positivo, longs pagam shorts. Quando é negativo, shorts pagam longs. Em mercados de alta ou com maior apetite por risco, funding rates positivos tendem a aparecer com mais frequência, refletindo um prêmio agregado do lado comprado.

Q4: Como usar o histórico de funding rate para avaliar arbitragem?

Uma forma comum é calcular média, desvio padrão e percentis históricos. Quando a taxa atual está significativamente acima da média histórica, por exemplo mais de um desvio padrão, uma estratégia teórica poderia envolver short no perpétuo e long no spot como hedge. Ainda assim, isso não é recomendação financeira. Custos, slippage, liquidez, execução, risco de base e mudanças rápidas de mercado podem alterar completamente o resultado.

Q5: Qual é a diferença entre premium e fundingRate?

premium representa o prêmio entre o preço de marcação e o índice spot, sendo um dos insumos usados no cálculo do próximo funding rate. Já fundingRate é a taxa efetivamente liquidada no período, determinada pelo prêmio médio e pela referência de juros, entre outros componentes do mecanismo.

Aviso de risco

Este artigo é apenas para fins educacionais e técnicos. Não constitui aconselhamento financeiro, jurídico ou de investimento. A negociação de contratos perpétuos envolve alto risco, incluindo possibilidade de perdas substanciais. O desempenho histórico de funding rate não indica nem garante retornos futuros. Avalie cuidadosamente os riscos antes de tomar qualquer decisão.