Genesis Arbitrage

Genesis Arbitrage · · 11 min de leitura

Endpoints de funding da Genesis API: taxas, spread e análise do histórico de funding

Em resumo

  • /funding/rates e /funding/spread estão em todos os planos da API: a taxa de cada exchange por intervalo e por 8 horas, o horário do próximo pagamento e o melhor par de exchanges por spread.
  • A análise do funding liquidado são quatro endpoints /funding/analytics/… com 13 exchanges e até um ano de histórico, nos planos Pro e Max.
  • Os downloads completos de summary, recent e daily pesam até ~12 MB em gzip e são permitidos uma vez a cada 60–300 segundos: peça um recorte por coin ou repita a requisição com If-None-Match.

A API de taxas de funding da Genesis API é um conjunto de endpoints com as taxas de funding dos contratos perpétuos em várias exchanges, o melhor par de exchanges por spread de funding e o histórico do funding liquidado. As taxas atuais e o spread estão em todos os planos da API; a análise histórica de 13 exchanges, em Pro e Max. O site mostra os mesmos dados no Funding Arbitrage, veja o guia.

Endpoints de funding e planos

EndpointO que retornaPlanos da API
/funding/ratesTaxas de cada exchange por moedaTrial, Start, Pro, Max
/funding/spreadO melhor par de exchanges por spread e as demais exchangesTrial, Start, Pro, Max
/funding/analytics/summaryResumo de períodos de 1 dia a um anoPro, Max
/funding/analytics/recentTodos os pagamentos de 7 diasPro, Max
/funding/analytics/dailySomas diárias de 365 diasPro, Max
/funding/analytics/topScreener de pares e combinações de exchangesPro, Max

Os parâmetros e campos estão nas seções da documentação Taxas de funding, Spread de funding e Funding analytics. Em Trial e Start, os endpoints de análise retornam 403 plan_restricted. Para uma visão geral das APIs de dados de funding, veja o artigo sobre a API de taxas de funding. Os exemplos de resposta abaixo mostram o campo data, abreviado.

Taxas e normalização para 8 horas

/funding/rates retorna, para cada moeda, uma lista de exchanges com a taxa atual. Os filtros coin e exchange (separados por vírgula para várias exchanges) são opcionais.

curl "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"
    }
  ]
}
CampoSignificado
funding_pctTaxa por intervalo de liquidação, %
funding_8h_pctTaxa normalizada para 8 horas, %
intervalIntervalo de liquidação, p. ex. 8h; null: sem dados
next_payoutHorário do próximo pagamento, HH:MM UTC; null: sem dados
price, trade_urlPreço e link para o terminal de trading da exchange

Um exemplo hipotético: uma taxa horária de 0,005% é 0,005 × 8 / 1 = 0,04% por 8 horas, igual à da MEXC, só que paga oito vezes e pode mudar já na hora seguinte.

Anualizada sem capitalização, a taxa de 8 horas × 3 × 365 dá o APR. Um exemplo hipotético: 0,01% a cada 8 horas dá 0,01 × 3 × 365 = 10,95% ao ano, enquanto a taxa se mantiver. O que a taxa diz sobre o mercado está em A taxa de funding como indicador de mercado.

Spread de funding: o melhor par de exchanges

/funding/spread retorna, para cada moeda, o melhor par de exchanges por spread de funding (best) e as demais exchanges (others). Filtros: coin e min_spread, o spread mínimo em %.

{
  "coin": "BTC",
  "spread_pct": 0.01,
  "best": {
    "exchange_1": "Hyper",
    "exchange_2": "CoinEx",
    "funding_1_pct": 0.0,
    "funding_2_pct": 0.0,
    "next_payout_1": null,
    "next_payout_2": "08:00",
    "interval_1": "1h",
    "interval_2": "8h",
    "trade_url_1": "https://app.hyperliquid.xyz/trade/BTC",
    "trade_url_2": "https://www.coinex.com/futures/BTC-usdt"
  },
  "others": [ … ]
}

spread_pct é o spread do melhor par, %. funding_1_pct e funding_2_pct são taxas pelo próprio intervalo (interval_1, interval_2): para compará-las à mão, normalize as duas para 8 horas. O short vai onde a taxa é maior, o long onde é menor. A Hyperliquid aparece como Hyper nas respostas.

O script em Python mostra as dez moedas com maior spread_pct (a partir de 0,05%) e os intervalos de liquidação do par. Em 429 e 503 ele espera Retry-After segundos; em um loop, repita a requisição no máximo uma vez por meta.freshness_sec.

import os
import time
import requests

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

for _ in range(3):
    r = requests.get(URL, headers=HEADERS,
                     params={"min_spread": 0.05}, timeout=15)
    if r.status_code not in (429, 503):
        break
    # limite de requisições ou dados em reconstrução: espere e tente de novo
    time.sleep(int(r.headers.get("Retry-After", "5")))
r.raise_for_status()

rows = sorted(r.json()["data"], key=lambda x: x["spread_pct"],
              reverse=True)
for row in rows[:10]:
    b = row["best"]
    print(f'{row["coin"]:<10} {row["spread_pct"]:>8.4f}%  '
          f'{b["exchange_1"]} {b["interval_1"]} / '
          f'{b["exchange_2"]} {b["interval_2"]}')

Análise do funding liquidado

Quatro endpoints /funding/analytics/… retornam o histórico do funding liquidado de 13 exchanges, os mesmos dados da aba Análise do Funding Arbitrage. As taxas são porcentagens por período de liquidação e os carimbos de tempo são segundos epoch UTC.

EndpointConteúdoSeção completaSem coin, no máximo
/funding/analytics/summarySomas, taxas médias, APR e cobertura de 7 períodos~600 KB gzipuma vez a cada 60 s
/funding/analytics/recentTodos os pagamentos de 7 dias~1 MB gzipuma vez a cada 60 s
/funding/analytics/dailySomas diárias de 365 diasaté ~12 MB gzipuma vez a cada 300 s
/funding/analytics/topTop 50 de pares e top 50 de combinações por período—sem limite

Um download completo antes do fim da janela recebe 429 com Retry-After. As regras de ETag e compressão estão no guia formato de resposta e erros.

curl --compressed -i \
  "https://api.genesisarbitrage.com/v1/funding/analytics/summary" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H "If-None-Match: <ETag from the previous response>"

--compressed pede uma resposta comprimida e a descomprime, e -i imprime os cabeçalhos, entre eles ETag. Envie a primeira requisição sem If-None-Match.

O summary e o array m

Cada par moeda×exchange no summary tem m: a chave é um período (1d, 3d, 7d, 30d, 90d, 180d, 365d) e o valor são 14 números na ordem de metric_order. Um período não aparece em m quando não há dados para ele.

{
  "metric_order": ["sum", "avg8h", "apr", "n", "pos", "neg", "zero",
                   "min", "max", "cov", "med8h", "pos_streak",
                   "neg_streak", "flips"],
  "coins": {
    "BTC": {
      "canon": "BTC",
      "mult": 1,
      "exchanges": {
        "Binance": {
          "interval_h": 8.0,
          "data_since": 1568102400,
          "last8h": 0.004123,
          "m": {
            "7d": [0.12802, 0.006298, 6.896, 21, 21, 0, 0,
                   0.000125, 0.01, 1.0, 0.00588, 7, 0, 0]
          }
        }
      }
    }
  }
}
MétricaÍndiceSignificado
sum0Acumulado no período, %
avg8h1Taxa média em termos de 8 horas, %
apr2Anualizado, %
n3Número de liquidações
pos, neg, zero4–6Liquidações positivas, negativas e nulas
min, max7–8Menor e maior liquidação, %
cov9Cobertura do período de 0 a 1
med8h10Mediana em termos de 8 horas, %
pos_streak, neg_streak11–12Dias seguidos positivos e negativos
flips13Trocas de sinal

Os índices 10–13 são null nos períodos 1d e 3d. Com cov < 0,9, os dados cobrem só parte do período, então sinalize esses valores. No exemplo, BTC na Binance em 7 dias: 21 liquidações, todas positivas, cov 1,0, e apr é igual a avg8h × 3 × 365: 0,006298 × 1095 ≈ 6,896.

Se avg8h está bem acima de med8h, um pico inflou a média: a mediana, pos_streak e flips mostram melhor a estabilidade. Os demais campos do par:

Pagamentos de 7 dias e somas diárias

Em /funding/analytics/recent, cada exchange tem uma string s no formato ts:rate;ts:rate;… em ordem crescente de tempo e um intervalo i em horas. Em /funding/analytics/daily, a string day_ts:sum:pos:neg;… traz a meia-noite UTC, a soma do dia e o número de liquidações positivas e negativas.

def parse_recent(s):
    # "ts:rate;ts:rate;…" → [(ts, rate), …]
    return [(int(t), float(v)) for t, v in
            (p.split(":") for p in s.split(";") if p)]


def parse_daily(s):
    # "day_ts:sum:pos:neg;…" → [(day, sum, positive, negative), …]
    out = []
    for p in filter(None, s.split(";")):
        d, total, pos, neg = p.split(":")
        out.append((int(d), float(total), int(pos), int(neg)))
    return out

Screener de combinações

/funding/analytics/top é um screener pronto e sem parâmetros: para cada período, o top 50 de pares moeda×exchange por funding acumulado e o top 50 de combinações short/long. As pernas de uma combinação ficam sempre em exchanges diferentes, com cobertura de pelo menos 0,9, e linhas com net ≤ 0 nunca aparecem.

Campo da combinaçãoSignificado
gross, fees, netFunding bruto, as taxas de quatro operações segundo taker_fees e net = gross − fees
apr_net, apr_capitalAnualizado sobre o nocional de uma perna, e apr_net / 2 sobre o capital das duas pernas
win_rate, max_ddProporção de dias com ganho (0..1) e o drawdown máximo do resultado acumulado
worst_streak, risk_daysA maior sequência de dias com perda e os dias em que o risco foi medido, máx. 90
live_8h, trend_1d, trend_7dA diferença atual de taxas em 8 horas e o spread bruto do último dia e da última semana
price_divA diferença de preço atual entre as pernas; null quando não há preços
short_sym, long_symTickers reais das pernas nas exchanges, que podem diferir: PEPE e 1000PEPE

No exemplo da documentação, a combinação de PEPE, short na HTX e long na Hyperliquid, obteve um gross de 1,51504% em 7 dias. As taxas são 0,05% para abrir e para fechar na HTX e 0,045% para cada uma na Hyperliquid: 0,05 × 2 + 0,045 × 2 = 0,19.

Assim, net = 1,51504 − 0,19 = 1,32504%, apr_net = 1,32504 × 365 / 7 ≈ 69,09%, apr_capital = 69,09 / 2 ≈ 34,55%. A diferença de preço entre as pernas, o slippage e a margem não estão incluídos.

Como montar um monitor de funding

  1. Encontre candidatas

    Peça /funding/spread com min_spread (qualquer plano da API) e ordene por spread_pct.

  2. Confira taxas e pagamentos

    Peça /funding/rates com coin: interval, next_payout e funding_8h_pct nas duas exchanges. A posição precisa estar aberta no horário da liquidação.

  3. Veja o histórico

    Em Pro e Max, peça /funding/analytics/summary com coin: sum, apr, cov e flips de 7d e 30d mostram se a diferença de taxas se sustenta.

  4. Avalie a combinação como um todo

    Em /funding/analytics/top, compare net, apr_capital, win_rate, max_dd e o price_div atual.

  5. Abra as posições por conta própria

    Os links trade_url levam aos terminais das exchanges; calcule a combinação com taxas na calculadora de spread.

Perguntas e respostas

Como normalizo uma taxa de funding para 8 horas?

Multiplique a taxa por intervalo por 8 e divida pela duração do intervalo em horas. /funding/rates faz isso por você no campo funding_8h_pct.

Onde encontro o histórico de taxas de funding?

/funding/analytics/recent tem todos os pagamentos de 7 dias, /funding/analytics/daily as somas diárias de um ano e /funding/analytics/summary os totais por período. Os três estão nos planos Pro e Max da API.

Por que uma seção completa de análise retorna 429?

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. Recortes por moeda e respostas 304 a If-None-Match não têm limite.