Endpoints de funding da Genesis API: taxas, spread e análise do histórico de funding
Em resumo
/funding/ratese/funding/spreadestã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
coinou repita a requisição comIf-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
| Endpoint | O que retorna | Planos da API |
|---|---|---|
/funding/rates | Taxas de cada exchange por moeda | Trial, Start, Pro, Max |
/funding/spread | O melhor par de exchanges por spread e as demais exchanges | Trial, Start, Pro, Max |
/funding/analytics/summary | Resumo de períodos de 1 dia a um ano | Pro, Max |
/funding/analytics/recent | Todos os pagamentos de 7 dias | Pro, Max |
/funding/analytics/daily | Somas diárias de 365 dias | Pro, Max |
/funding/analytics/top | Screener de pares e combinações de exchanges | Pro, 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"
}
]
}
| Campo | Significado |
|---|---|
funding_pct | Taxa por intervalo de liquidação, % |
funding_8h_pct | Taxa normalizada para 8 horas, % |
interval | Intervalo de liquidação, p. ex. 8h; null: sem dados |
next_payout | Horário do próximo pagamento, HH:MM UTC; null: sem dados |
price, trade_url | Preç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.
| Endpoint | Conteúdo | Seção completa | Sem coin, no máximo |
|---|---|---|---|
/funding/analytics/summary | Somas, taxas médias, APR e cobertura de 7 períodos | ~600 KB gzip | uma vez a cada 60 s |
/funding/analytics/recent | Todos os pagamentos de 7 dias | ~1 MB gzip | uma vez a cada 60 s |
/funding/analytics/daily | Somas diárias de 365 dias | até ~12 MB gzip | uma vez a cada 300 s |
/funding/analytics/top | Top 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 | Índice | Significado |
|---|---|---|
sum | 0 | Acumulado no período, % |
avg8h | 1 | Taxa média em termos de 8 horas, % |
apr | 2 | Anualizado, % |
n | 3 | Número de liquidações |
pos, neg, zero | 4–6 | Liquidações positivas, negativas e nulas |
min, max | 7–8 | Menor e maior liquidação, % |
cov | 9 | Cobertura do período de 0 a 1 |
med8h | 10 | Mediana em termos de 8 horas, % |
pos_streak, neg_streak | 11–12 | Dias seguidos positivos e negativos |
flips | 13 | Trocas 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:
data_since: quando os dados começam; não desenhe zeros antes dessa data.last8h: a última taxa em termos de 8 horas, para comparar «agora versus o normal».interval_h: intervalo de liquidação: 8 ou 4 horas nas CEX, 1 hora na Hyperliquid e na Lighter.canonemult: o nome que une variantes do ticker (1000PEPE→PEPE) e o multiplicador do contrato;multnunca se aplica às taxas.
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.
by_net_apr: por rendimento líquido.by_stable:win_rate≥ 0,7 e um drawdown de no máximo metade do bruto.by_live:live_8h> 0 etrend_1d> 0.by_sum_pos,by_sum_neg: tops de uma única exchange por funding acumulado, somente comcov≥ 0,5.
| Campo da combinação | Significado |
|---|---|
gross, fees, net | Funding bruto, as taxas de quatro operações segundo taker_fees e net = gross − fees |
apr_net, apr_capital | Anualizado sobre o nocional de uma perna, e apr_net / 2 sobre o capital das duas pernas |
win_rate, max_dd | Proporção de dias com ganho (0..1) e o drawdown máximo do resultado acumulado |
worst_streak, risk_days | A maior sequência de dias com perda e os dias em que o risco foi medido, máx. 90 |
live_8h, trend_1d, trend_7d | A diferença atual de taxas em 8 horas e o spread bruto do último dia e da última semana |
price_div | A diferença de preço atual entre as pernas; null quando não há preços |
short_sym, long_sym | Tickers 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
Encontre candidatas
Peça
/funding/spreadcommin_spread(qualquer plano da API) e ordene porspread_pct.Confira taxas e pagamentos
Peça
/funding/ratescomcoin:interval,next_payoutefunding_8h_pctnas duas exchanges. A posição precisa estar aberta no horário da liquidação.Veja o histórico
Em Pro e Max, peça
/funding/analytics/summarycomcoin:sum,apr,coveflipsde 7d e 30d mostram se a diferença de taxas se sustenta.Avalie a combinação como um todo
Em
/funding/analytics/top, comparenet,apr_capital,win_rate,max_dde oprice_divatual.Abra as posições por conta própria
Os links
trade_urllevam 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.