Genesis Arbitrage

Genesis Arbitrage · · 15 min de leitura

API de funding rate: as taxas de todas as exchanges em uma requisição, mais o histórico de funding pago

Em resumo

  • Uma API de funding rate deve retornar, para cada exchange, a taxa por intervalo, o próprio intervalo, o horário do próximo funding, a taxa equivalente a 8 horas e o preço do futuro.
  • Binance, Bybit, OKX e Hyperliquid têm, cada uma, seus endpoints, suas unidades e sua forma de informar o intervalo. O Genesis API /funding/rates retorna as taxas de todas as exchanges em uma única requisição GET, em porcentagem e normalizadas para 8 horas.
  • O histórico de funding pago em 13 exchanges (somas, taxas médias, APR, um ano de somas diárias e um screener de combinações com net após as tarifas) está em /funding/analytics/* nos planos Pro e Max.

Uma API de funding rate retorna, para os futuros perpétuos de cada exchange, as taxas de financiamento: a taxa por intervalo, o próprio intervalo e o horário do próximo funding e, na versão completa, o histórico do funding pago. Cada exchange tem sua própria API, com caminhos, unidades e intervalos próprios; por isso, para compará-las, reúnem-se as taxas em uma única tabela, convertem-se para porcentagem e normalizam-se para um mesmo período, em geral 8 horas.

O que uma API de funding rate deve retornar

Uma taxa sem o seu intervalo não diz nada: 0,02% a cada 4 horas e 0,02% a cada 8 horas diferem por um fator de dois. Por isso, uma API de taxas de financiamento de criptomoedas útil retorna cinco valores para cada par moeda–exchange.

O que você precisaPara quêCampo de /funding/rates
Taxa por intervaloQuanto será o próximo pagamentofunding_pct
Intervalo de fundingSem ele não dá para comparar as taxasinterval
Horário do próximo fundingA posição precisa estar aberta até lánext_payout
Taxa em 8 horasComparar exchanges com intervalos diferentesfunding_8h_pct
Preço do futuroA diferença de preço entre as pernas muda a entradaprice

O pagamento é o tamanho da posição vezes a taxa: uma posição de $10.000 a 0,01% recebe ou paga $1 por liquidação.

Por que os intervalos diferem entre exchanges e como normalizar uma taxa para 8 horas

Cada exchange decide com que frequência liquida o funding e pode mudar o intervalo de um contrato específico. Na análise do Genesis API, os intervalos das CEX são de 8 e 4 horas, enquanto Hyperliquid e Lighter liquidam a cada hora. A Hyperliquid calcula a taxa como uma taxa de 8 horas e paga um oitavo dela a cada hora, como descrito nas regras de funding da Hyperliquid.

No exemplo da documentação do Genesis API, a MEXC cobra 0,02% sobre TON a cada 4 horas: 0,02 × 8 / 4 = 0,04% em 8 horas. Um exemplo hipotético com intervalo de uma hora: a exchange A paga 0,004% a cada hora, a exchange B paga 0,02% a cada 8 horas. Pelos números brutos, A paga um quinto, mas em 8 horas são 0,004 × 8 / 1 = 0,032% contra 0,02%, ou seja, 1,6 vez mais.

A normalização pressupõe que a taxa se mantém durante todo o período, e uma taxa horária pode mudar já na liquidação seguinte. Só o histórico mostra o que foi de fato pago.

O APR é calculado a partir da taxa de 8 horas: três liquidações por dia, 1.095 por ano. Para a exchange A, são 0,032 × 3 × 365 = 35,04% ao ano, enquanto a taxa se mantiver.

APIs de funding rate das exchanges: Binance, Bybit, OKX e Hyperliquid

Cada grande exchange tem sua própria API de funding rate: seus caminhos, campos e forma de informar o intervalo.

ExchangeTaxa atualHistóricoIntervalo
BinanceGET /fapi/v1/premiumIndexGET /fapi/v1/fundingRateGET /fapi/v1/fundingInfo
BybitGET /v5/market/tickersGET /v5/market/funding/historycampo fundingIntervalHour
OKXGET /api/v5/public/funding-rateGET /api/v5/public/funding-rate-historya partir de fundingTime e nextFundingTime
HyperliquidPOST /info, metaAndAssetCtxsPOST /info, fundingHistorya cada hora

A API de funding rate da Binance retorna a taxa e o horário do próximo funding nos campos lastFundingRate e nextFundingTime de premiumIndex (documentação da Binance), e o histórico de taxas da Binance vem de fundingRate, que aceita startTime e endTime (histórico de taxas de funding). fundingInfo retorna o intervalo apenas para os contratos cujo intervalo ou limite de taxa a exchange ajustou (descrição do endpoint).

A Bybit retorna fundingRate, nextFundingTime e fundingIntervalHour em uma única resposta de tickers com category=linear (tickers da Bybit), e sua requisição de histórico exige symbol (histórico de funding da Bybit). Como a documentação destaca, cada contrato tem seu próprio intervalo.

Na OKX, a documentação sugere deduzir o intervalo de um contrato pela diferença entre nextFundingTime e fundingTime (documentação da OKX).

A Hyperliquid recebe todas as consultas de dados em POST https://api.hyperliquid.xyz/info, e é o corpo JSON que define o que volta: {"type": "metaAndAssetCtxs"} retorna o funding atual de cada ativo, {"type": "fundingHistory", "coin": "ETH", "startTime": …} retorna o histórico de taxas (documentação da Hyperliquid).

Para juntar essas exchanges em uma única tabela, seu código precisa:

Todas as exchanges em uma requisição: /funding/rates

GET /funding/rates retorna, para cada moeda, a lista de exchanges com a taxa atual: Binance, OKX, Bybit, Bitget, MEXC, Gate, BingX, HTX, Hyperliquid e as demais exchanges cobertas pela Genesis Arbitrage, mais de 1000 moedas no total. Os filtros coin e exchange (separados por vírgula para várias exchanges) são opcionais; sem eles você recebe o conjunto completo.

curl --compressed \
  "https://api.genesisarbitrage.com/v1/funding/rates?coin=TON" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "coin": "TON",
  "exchanges": [
    {
      "exchange": "MEXC",
      "funding_pct": 0.02,
      "funding_8h_pct": 0.04,
      "next_payout": "00:00",
      "interval": "4h",
      "price": 2.184,
      "trade_url": "https://futures.mexc.com/exchange/TON_USDT"
    }
  ]
}

Este é um elemento do array data dentro do envelope que todas as respostas do Genesis API compartilham: success, data, meta. As taxas estão em porcentagem, next_payout é o horário do pagamento em HH:MM UTC, os valores vazios são null e a Hyperliquid aparece como Hyper. Todos os campos e o formulário Testar estão na seção Taxas de funding da documentação.

/funding/rates e /funding/spread estão em todos os planos, a partir do Trial a $20 por mês: 500 K chamadas, 1 requisição por segundo, 60 s de atualidade dos dados (preços do Genesis API).

Spread de funding: /funding/spread

O spread de funding é a diferença entre a maior e a menor taxa de uma moeda entre as exchanges, após normalizar para 8 horas. O short vai onde a taxa é maior e o long onde é menor: o short recebe a taxa da sua exchange, o long paga a sua (ou recebe, quando essa taxa é negativa), e a diferença é o que sobra.

GET /funding/spread retorna, para cada moeda, o melhor par de exchanges em best: exchange_1 e exchange_2, suas taxas no próprio intervalo (funding_1_pct, funding_2_pct), os intervalos, os horários de pagamento e os links do terminal. O spread do par está em spread_pct, as demais exchanges estão em others, e os filtros são coin e min_spread (documentação do Spread de funding). Os intervalos de um par costumam diferir, como 1h e 8h para BTC no exemplo da documentação; por isso, só compare as taxas de um par manualmente depois de normalizá-las para 8 horas.

Python: top 10 spreads de funding, anualizados

O script pega o conjunto completo de /funding/rates e, para cada moeda, encontra as exchanges com o maior e o menor funding_8h_pct: a diferença é o spread de 8 horas, anualizado como spread × 3 × 365. Em 429 e 503 ele espera Retry-After segundos, mas não mais que um minuto: quando a cota mensal se esgota, Retry-After dura até a cota ser renovada.

import os
import time
import requests

URL = "https://api.genesisarbitrage.com/v1/funding/rates"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}


def fetch_rates():
    for _ in range(3):
        r = requests.get(URL, headers=HEADERS, timeout=20)
        if r.status_code not in (429, 503):
            r.raise_for_status()
            return r.json()["data"]
        # 429 ou 503: esperar Retry-After, mas não mais que um minuto
        time.sleep(min(int(r.headers.get("Retry-After", "5")), 60))
    raise RuntimeError("A API não respondeu após três tentativas")


rows = []
for item in fetch_rates():
    ex = [e for e in item["exchanges"]
          if e["funding_8h_pct"] is not None]
    if len(ex) < 2:
        continue
    short = max(ex, key=lambda e: e["funding_8h_pct"])  # perna short
    long_ = min(ex, key=lambda e: e["funding_8h_pct"])  # perna long
    spread = short["funding_8h_pct"] - long_["funding_8h_pct"]
    rows.append((spread, item["coin"], short, long_))

rows.sort(key=lambda x: x[0], reverse=True)
for spread, coin, short, long_ in rows[:10]:
    apr = spread * 3 * 365  # APR simples sobre o nocional de uma perna
    print(f"{coin:<10} short {short['exchange']:<8} "
          f"long {long_['exchange']:<8} {spread:.4f}% em 8h  "
          f"APR {apr:.1f}%, sobre o capital {apr / 2:.1f}%")

O número anualizado aqui é sobre o nocional de uma perna. As duas pernas exigem dinheiro, então sobre o capital total sem alavancagem o rendimento é metade, como no campo de análise apr_capital. Um exemplo hipotético: short em uma exchange a 0,05% por 8 horas, long em outra a 0,01%. O spread é 0,05 − 0,01 = 0,04%, anualizado 0,04 × 3 × 365 = 43,8% por perna e 21,9% sobre o capital.

As tarifas não estão incluídas. Um exemplo hipotético: uma tarifa taker de 0,05% em cada uma das quatro operações (abrir e fechar as duas pernas) soma 4 × 0,05 = 0,2% do nocional de uma perna. Um spread de 0,04% recupera isso em 0,2 / 0,04 = 5 liquidações, ou 40 horas, se as taxas não mudarem.

Só uma resposta 200 conta na cota. Em um monitor, consulte no máximo uma vez a cada meta.freshness_sec segundos e envie o ETag anterior em If-None-Match: um conjunto completo inalterado volta como um 304 sem cobrança. Mais no guia de limites e na lição 4 do curso de API de criptomoedas, que monta um monitor de spreads e funding em Python.

Histórico de funding pago: /funding/analytics/*

A taxa atual mostra a próxima liquidação; o histórico mostra o que foi de fato pago. Ele vem de quatro endpoints de análise: 13 exchanges, taxas em porcentagem por período de liquidação, timestamps em segundos epoch UTC. Estão nos planos Pro ($100 por mês) e Max ($200); Trial e Start recebem 403 plan_restricted.

EndpointConteúdoSeção completa
/funding/analytics/summarySomas, taxas médias de 8 horas, APR e cobertura para 7 períodos, de 1 dia a um ano~600 KB gzip
/funding/analytics/recentTodos os pagamentos dos últimos 7 dias~1 MB gzip
/funding/analytics/dailySomas diárias de 365 diasaté ~12 MB gzip
/funding/analytics/topTop 50 pares moeda×exchange e top 50 combinações short/long por período—

Os downloads completos sem coin são limitados: summary e recent uma vez a cada 60 segundos, daily uma vez a cada 300 segundos por chave; uma requisição antes do fim da janela recebe 429 com Retry-After. Os recortes por coin e as respostas 304 não têm limite, então o histórico de uma moeda se obtém assim:

curl --compressed -G \
  "https://api.genesisarbitrage.com/v1/funding/analytics/summary" \
  -d coin=BTC \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

No summary, cada par moeda×exchange traz o intervalo interval_h, o início dos dados data_since, a última taxa de 8 horas last8h para comparar «agora versus o normal» e um array m com 14 métricas por período: sum, avg8h, apr, cov, flips e outras. Exemplo da documentação: BTC na Binance em 7 dias, 21 liquidações positivas, avg8h 0,006298%, apr 0,006298 × 3 × 365 ≈ 6,896%. A leitura de m, recent e daily é explicada no guia de endpoints de funding, e os campos na seção Análise de funding da documentação.

O screener de combinações top

/funding/analytics/top é um screener pronto, sem parâmetros. As pernas das combinações estão sempre em exchanges diferentes, com cobertura de pelo menos 0,9, e combinações com net ≤ 0 nunca entram nas listas.

gross é o funding bruto da combinação no período, fees são as tarifas de quatro operações da tabela taker_fees, e net = gross − fees. apr_net é anualizado sobre o nocional de uma perna, apr_capital é a metade disso, sobre o capital das duas pernas. win_rate é a parcela de dias lucrativos, max_dd a maior queda, e price_div a diferença de preço atual entre as pernas, que o net deixa de fora.

No exemplo da documentação, a combinação PEPE (short na HTX, long na Hyperliquid sob o ticker 1000PEPE) fez gross de 1,51504% com fees de 0,19 em 7 dias. Assim, net = 1,51504 − 0,19 = 1,32504%, apr_net é 69,09% e apr_capital 34,55%. Listas prontas: by_net_apr por rendimento líquido, by_stable para combinações estáveis, by_live para as que estão funcionando agora.

A taxa de funding como indicador de mercado

Com uma taxa positiva, os longs com alavancagem pagam aos shorts; com uma negativa, é o contrário. Uma pequena taxa positiva é normal (a Hyperliquid fixa o componente de juros em 0,01% por 8 horas), e a taxa vira sinal quando se afasta bastante do seu nível habitual.

Leia uma taxa alta junto com o open interest: quando os dois sobem, há muitas posições alavancadas empilhadas de um lado, e um movimento contrário dispara uma cascata de liquidações. /market/open-interest retorna o open interest por exchange (seção da documentação). Mais em A taxa de funding como indicador de mercado.

Riscos da arbitragem de funding

Uma combinação short/long entre duas exchanges quase não depende do preço, mas ainda é possível perder dinheiro com ela:

Sem código, as mesmas taxas estão na tabela de Arbitragem de funding (guia), a calculadora de spread calcula uma combinação com as tarifas, e a visão geral das APIs de criptomoedas compara as APIs de dados de mercado em geral.

Perguntas e respostas

Onde encontro o histórico de taxas de funding?

As exchanges guardam o histórico em formatos próprios: GET /fapi/v1/fundingRate na Binance, GET /v5/market/funding/history na Bybit, o tipo fundingHistory na Hyperliquid. O Genesis API retorna o histórico de 13 exchanges em um único formato: /funding/analytics/recent para os pagamentos de 7 dias, /funding/analytics/daily para as somas diárias de um ano e /funding/analytics/summary para os totais por período, nos planos Pro e Max.

Por que as taxas de funding diferem entre as exchanges?

Cada exchange tem seus próprios traders, liquidez, fórmula de taxa e limites, então o desequilíbrio de posições se acumula de forma diferente. Os intervalos também diferem: 8 ou 4 horas nas CEX, a cada hora na Hyperliquid. Compare as taxas depois de normalizá-las para um mesmo período; no Genesis API, esse é o campo funding_8h_pct.

Com que frequência as taxas de funding são atualizadas na API?

A taxa atual em uma exchange muda até a liquidação; a taxa liquidada fica fixada e vai para o histórico. A atualidade dos dados do Genesis API é de 60 s no Trial, 30 s no Start, 10 s no Pro e 5 s no Max; o ETag do summary de análise muda a cada 15 minutos aproximadamente, e as somas diárias são recalculadas a cada hora.

Existe uma API de funding rate gratuita?

O Genesis API não tem plano gratuito: as taxas de funding e o spread estão no Trial a $20 por mês, o histórico no Pro a $100 e no Max a $200. No site, as taxas de funding e os spreads aparecem sem plano em Arbitragem de funding.