Dados on-chain na Genesis API: transferências, fluxos, unlocks, swaps em DEX
Em resumo
- O endpoint /onchain/{section} retorna qualquer um dos nove feeds do Genesis OnChain, de grandes transferências a hacks, nos planos Start, Pro e Max. Uma requisição a /onchain sem seção retorna todos os feeds em um único objeto.
- Swaps grandes em DEX, a análise de 24 horas ou 7 dias e o resumo de 7 dias de uma moeda estão disponíveis nos planos Pro e Max.
- Os rótulos de endereços são atribuição, não garantia. Uma transferência para uma exchange nem sempre significa venda, e um registro de swap pode desaparecer após a verificação.
Os endpoints on-chain da Genesis API retornam os dados da seção Genesis OnChain: grandes transferências de tokens, depósitos e saques de exchanges, movimentações de carteiras de equipes, posições em DEX perpétuos, unlocks de tokens, claims e hacks, além de swaps grandes em DEX. Cada linha já traz os rótulos do remetente e do destinatário, o valor em USD e links do explorador. Isso basta para acompanhar baleias e monitorar fluxos de exchanges a partir do seu próprio código, sem um indexador de blockchain.
Endpoints e planos
| Endpoint | O que retorna | Planos da API |
|---|---|---|
/onchain/{section} | Uma das nove seções do Genesis OnChain | Start, Pro, Max |
/onchain | As nove seções em um único objeto | Start, Pro, Max |
/onchain/dex-swaps | Swaps grandes em DEX | Pro, Max |
/onchain/analytics | Análise OnChain de 24h ou 7d | Pro, Max |
/onchain/coin/{symbol} | Resumo de 7 dias de uma moeda | Pro, Max |
No Trial, todos os endpoints on-chain retornam 403 plan_restricted. A atualização é de 30 s no Start, 10 s no Pro e 5 s no Max, e o mesmo valor chega em meta.freshness_sec. A chave e a primeira requisição estão no início rápido, as cotas nos limites da Genesis API.
Nove seções de /onchain/{section}
section | O que contém | Bloco do painel |
|---|---|---|
large-transfers | Grandes transferências de tokens | Large Transfers |
cex-flows | Depósitos em exchanges e saques delas | CEX Deposits / Withdrawals |
mint-bridge | Mint de tokens e transferências por bridge | Mint / Bridge |
team-wallets | Movimentações de carteiras de equipes | Team Transfers |
perp-positions | Grandes posições em DEX perpétuos | Perp. DEX Positions |
unlocks | Unlocks de tokens | Unlocks |
claims | Claims | Claims |
coin-traffic | Série de transferências de uma moeda para um mesmo destino | Coin Traffic |
hacks | Hacks e exploits | Hacks / Exploits |
O que cada bloco mostra e quais sinais observar está no guia do painel Genesis OnChain, os parâmetros na documentação. Uma requisição a /onchain sem seção retorna em data um objeto: a chave é o nome da seção e o valor, suas linhas. Os filtros então valem para todas as seções.
| Parâmetro | Tipo | O que faz |
|---|---|---|
min_usd | number | Valor mínimo do evento, USD |
coin | string | Linhas de uma moeda; hacks não tem moeda, então a lista volta vazia |
when | string | Somente para unlocks: upcoming ou past |
section | string | Seção para uma requisição /onchain?section=… |
Qualquer outro valor de when retorna 400 bad_request. Abaixo, a seção coin-traffic, um item do array data:
curl "https://api.genesisarbitrage.com/v1/onchain/coin-traffic" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"ts": 1783802410,
"token": "LAB",
"direction": "deposit",
"target": "Gate-io",
"target_address": "0x8782163068c7cd74D2510768a61135C1e4Eb07b3",
"total_usd": 573796.98,
"count": 18,
"window_hours": 5.69,
"avg_usd": 31878,
"largest_usd": 59891.78,
"transfers": [
{
"ts": 1783788640,
"usd": 59891.78,
"from_name": "0xec01…d1a5",
"tx_hash": "0xbf44850a7dc16086c08cfb…",
"chain": "bsc",
…
}
]
}
Campos das seções
As seções large-transfers, cex-flows, mint-bridge, team-wallets e claims são formadas por transferências; as demais têm campos próprios.
| Campos | Onde | Significado |
|---|---|---|
ts, links | Todas as seções | Hora do evento em segundos unix e links prontos: text + url |
token / token_name | Transferências, coin-traffic | Ticker do token e nome completo |
chain / chain_name, usd / amount | Transferências | Rede, valor em USD e em tokens |
from_* / to_* | Transferências | Remetente e destinatário: rótulo, endereço, link do explorador |
tx_hash / explorer_url / arkham_url | Transferências | Hash da transação, links do explorador e da Arkham |
direction, target / target_address | coin-traffic | Sentido deposit, withdrawal ou transfer e destino do fluxo |
total_usd / count / window_hours, transfers[] | coin-traffic | Total da série, número de transferências, janela em horas e as maiores transferências |
side / size / price / platform | perp-positions | Long ou Short, tamanho, preço, plataforma |
unlock_percent / unlock_value_usd / hours_left / allocations | unlocks | Parcela e valor do unlock, horas restantes, alocações |
classification / technique / returned_funds | hacks | Classificação, técnica do ataque, fundos devolvidos |
Swaps em DEX: /onchain/dex-swaps
Planos Pro e Max. O endpoint retorna o feed de swaps grandes, como a tela Visão geral de DEX: cada swap mostra que parcela da liquidez do pool ele consumiu, que movimento de preço esperar e o que aconteceu após 30 segundos e 5 minutos. O esquema da resposta está na documentação.
| Parâmetro | Tipo | O que faz |
|---|---|---|
period | string | live — os últimos 15 minutos, padrão; 1h, 6h, 24h ou 7d |
chain | string | Rede |
side | string | buy ou sell |
dex | string | DEX; separadas por vírgula para várias |
min_usd | number | Valor mínimo do swap, USD |
min_impact | number | Impacto absoluto mínimo no pool, % |
final | boolean | true — somente swaps verificados |
token | string | Ticker do token |
q | string | Busca por token, nome, endereços, trader, hash, DEX e rede |
| Campo | Tipo | Significado |
|---|---|---|
id | string | Identificador estável: rede, transação, token |
tier | string | Nível pela liquidez do pool: de T1 (US$ 30.000–100.000) a T4 (acima de US$ 10 mi) |
pool_liquidity_usd / size_pct_liquidity / impact_est_pct | number ou null | Liquidez do pool, a parcela do swap nela e o impacto estimado no preço, % |
price_after_30s_usd / price_after_5m_usd / move_after_5m_pct | number ou null | Preço após 30 s e 5 min e a variação do preço nos 5 minutos seguintes ao swap |
facts | string | Status da verificação: pending, publish, 30s, final ou unavailable |
trader_name / trader_address | string ou null | Rótulo e endereço do trader |
No exemplo abaixo, um swap de US$ 412.500 em um pool com US$ 4.120.000 de liquidez consumiu 412.500 / 4.120.000 × 100 = 10,01% do pool. O impacto estimado é de 4,8% e, após 5 minutos, o preço havia se movido 1,9%.
curl -G "https://api.genesisarbitrage.com/v1/onchain/dex-swaps" \
-d period=1h -d min_usd=100000 -d final=true \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"id": "ethereum:0x5f3c…e1:0x6982…1933",
"ts": 1794675511,
"token": "PEPE",
"chain": "ethereum",
"side": "buy",
"usd": 412500,
"dex": "Uniswap",
"pool_label": "PEPE/WETH 0.3%",
"tier": "T3",
"pool_liquidity_usd": 4120000,
"size_pct_liquidity": 10.01,
"impact_est_pct": 4.8,
"move_after_5m_pct": 1.9,
"facts": "final",
"explorer_url": "https://etherscan.io/tx/0x5f3c…e1"
}
Análise OnChain: /onchain/analytics
Também para Pro e Max. Uma única chamada retorna a tela Análise do Genesis OnChain para period=24h (padrão) ou 7d, com totais, intervalos por hora, fluxos de exchanges, unlocks, hacks, moedas em foco e o feed de eventos. Todos os campos estão na documentação.
| Campo | Tipo | Significado |
|---|---|---|
kpi | object | Totais: events, usd, tokens, cex_in, cex_out, cex_net |
hourly | object | Intervalos com passo de 1 h para 24h e de 6 h para 7d |
exchange_flows | object | Por exchange: in_usd, out_usd, net |
tokens | array | Até 40 moedas em foco com o maior evento e o contexto CEX |
events | array | Feed de eventos do período, até 600 |
cex_net é depósitos menos saques: no exemplo, 312.456.789 − 287.654.321 = 24.802.468, ou seja, US$ 24,8 mi a mais entraram nas exchanges do que saíram.
curl -G "https://api.genesisarbitrage.com/v1/onchain/analytics" \
-d period=24h \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"period": "24h",
"kpi": {
"events": 1284,
"usd": 912345678,
"tokens": 211,
"cex_in": 312456789,
"cex_out": 287654321,
"cex_net": 24802468
},
"exchange_flows": {
"Binance": {
"in_usd": 98123456, "out_usd": 87654321, "net": 10469135
}
},
"tokens": [ … ],
"events": [ … ]
}
Moeda OnChain: /onchain/coin/{symbol}
Pro e Max também recebem um resumo de 7 dias de uma moeda, como a página da moeda: eventos on-chain, swaps em DEX, unlocks e contexto CEX. O ticker vai no caminho, de 1 a 32 caracteres, e a resposta é reconstruída no máximo uma vez a cada 10 segundos. Os campos estão na documentação.
| Campo | Tipo | Significado |
|---|---|---|
cex | object ou null | Preço, OI, funding de 8 horas, melhor spread, redes, depósito e saque; null se a moeda não está nas CEX compatíveis |
kpi | object | Totais de 7 dias: eventos, cex_in, cex_out, swaps, dex_buy, dex_sell |
by_section | object | Número de eventos por seção, com chaves como large_tx e cex_deposits |
events / swaps | array | Eventos e swaps, até 2000; totais completos em events_total e swaps_total |
unlocks.upcoming / unlocks.past | array | Unlocks futuros e passados |
curl "https://api.genesisarbitrage.com/v1/onchain/coin/PEPE" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"symbol": "PEPE",
"cex": {
"price": 0.00001,
"oi_usd": 412000000,
"funding_8h": 0.0081,
"best_spread": 0.42,
"deposit": true,
"withdraw": true,
"nets": ["ETH", "BSC"]
},
"kpi": {
"events": 38, "cex_in": 21000000,
"cex_out": 18500000, "swaps": 54
},
"events_total": 38,
"swaps_total": 54
}
Exemplo hipotético: depósitos de uma moeda em exchanges via cex-flows
O objetivo é saber quanto de uma moeda foi movido para exchanges na última hora e receber um aviso a cada depósito grande. Em cex-flows, o sentido aparece nos rótulos: uma exchange em to_name indica depósito, uma exchange em from_name indica saque.
Em uma hora, a ARB teve quatro depósitos: US$ 412.000, US$ 260.000, US$ 180.000 e US$ 148.000, somando US$ 412.000 + US$ 260.000 + US$ 180.000 + US$ 148.000 = US$ 1.000.000. Houve um saque de US$ 150.000. O fluxo líquido para as exchanges é US$ 1.000.000 − US$ 150.000 = US$ 850.000: entra mais do que sai. Assim fica a linha hipotética do primeiro depósito:
{
"ts": 1794675511,
"token": "ARB",
"chain": "arbitrum_one",
"usd": 412000,
"amount": 1030000,
"from_name": "0x7a2f…c31b",
"to_name": "Binance Deposit",
"tx_hash": "0x9c1e…",
"explorer_url": "https://arbiscan.io/tx/0x9c1e…"
}
Defina a moeda e o limite
coinemin_usdmantêm na resposta apenas as grandes transferências de uma moeda.Separe depósitos de saques
Uma exchange em
to_nameé depósito; emfrom_name, saque. Compare os rótulos por substring, sem diferenciar maiúsculas.Conte a janela e as transferências novas
Some as linhas da última hora por
tse avise apenas para novos valores detx_hash.Consulte na atualização do seu plano
Faça uma pausa de
meta.freshness_secentre as requisições; em429e503, aguardeRetry-Aftersegundos.
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
COIN, MIN_USD = "ARB", 100_000
CEX = ("binance", "okx", "bybit", "coinbase") # substrings dos rótulos
seen = set()
def is_cex(label):
return any(name in (label or "").lower() for name in CEX)
while True:
r = requests.get(f"{API}/onchain/cex-flows", headers=HEADERS,
params={"coin": COIN, "min_usd": MIN_USD},
timeout=15)
if r.status_code in (429, 503): # rate limit ou reconstrução
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
body = r.json()
hour_ago = time.time() - 3600
inflow = outflow = 0.0
for row in body["data"]:
if (row.get("ts") or 0) < hour_ago:
continue
usd = row.get("usd") or 0
if is_cex(row.get("to_name")): # depósito em uma exchange
inflow += usd
if row.get("tx_hash") not in seen:
seen.add(row.get("tx_hash"))
print(f"{COIN} → {row['to_name']}: ${usd:,.0f}")
elif is_cex(row.get("from_name")): # saque
outflow += usd
print(f"última hora: para exchanges ${inflow:,.0f}, "
f"fluxo líquido ${inflow - outflow:,.0f}")
time.sleep(body["meta"]["freshness_sec"])
O script apenas lê dados e imprime avisos; o que fazer com a moeda é decisão sua. Séries de pequenas transferências para uma mesma exchange são agrupadas na seção coin-traffic, em que o sentido já vem no campo direction. Os totais de todas as moedas vêm de /onchain/analytics em kpi.cex_in, kpi.cex_out e kpi.cex_net, e uma visão geral dos usos dos dados on-chain está no artigo sobre a API de dados on-chain.
Perguntas e respostas
De qual plano preciso para dados on-chain?
As nove seções de /onchain/{section} estão abertas em Start, Pro e Max. Swaps em DEX, análise e o resumo da moeda são só para Pro e Max, e no Trial os endpoints on-chain retornam 403 plan_restricted.
Existe histórico além de 7 dias?
As janelas mais longas são period=7d para swaps e análise e 7 dias no resumo da moeda; a Genesis API não tem um arquivo separado. Para um histórico longo, guarde os registros você mesmo a cada consulta.
Por que um swap sumiu da resposta?
A verificação encontrou uma reorganização de liquidez em vez de uma negociação, e o registro foi removido. Compare os swaps salvos por id ou peça somente final=true.
Como obtenho os próximos unlocks de tokens?
Peça /onchain/unlocks?when=upcoming. Cada linha traz unlock_percent e unlock_value_usd, a parcela e o valor do unlock, e hours_left, as horas restantes. min_usd define um limite de valor e coin escolhe uma moeda.