API de dados on-chain: transferências de baleias, fluxos de exchanges e unlocks de tokens
Em resumo
- Uma API de dados on-chain devolve eventos da blockchain já decodificados: qual token se moveu, de quem, para quem e por quantos dólares. Os dados brutos vêm dos nós, os indexadores os transformam em tabelas e os rótulos de endereços continuam sendo uma atribuição que pode estar errada.
- Os traders acompanham depósitos e saques em exchanges, grandes transferências, movimentos de carteiras de equipes, posições em DEX de perpétuos, unlocks, claims, hacks e grandes swaps em DEX. Um depósito em uma exchange nem sempre termina em venda.
- Na Genesis API, as nove seções on-chain estão disponíveis a partir do plano Start, enquanto os swaps em DEX, a análise e o resumo da moeda exigem Pro ou Max. Seu código calcula a janela e os totais de fluxo, porque as seções não têm parâmetro de tempo.
Uma API de dados on-chain é uma interface HTTP para eventos da blockchain que já foram coletados, convertidos em dólares e rotulados: qual token se moveu, de qual endereço, para qual endereço e em qual transação. Com uma API assim, você pode acompanhar transferências de baleias, entradas em exchanges, unlocks de tokens e grandes swaps em uma DEX sem manter seu próprio nó nem indexador. Aqui, uma baleia é um endereço que detém tanto de uma moeda que suas transferências podem mexer com o mercado.
De onde vêm os dados on-chain
Os dados passam por três camadas: um nó armazena os blocos, um indexador os transforma em linhas de eventos e uma base de rótulos dá nome aos endereços.
Nó: blocos e logs
Um nó de blockchain armazena blocos e os serve por JSON-RPC. No Ethereum e em redes compatíveis, uma transferência de token ERC-20 é gravada no log da transação como o evento Transfer(address indexed _from, address indexed _to, uint256 _value), e o padrão recomenda emitir o mesmo evento com 0x0 como remetente quando novos tokens são criados (EIP-20).
O método eth_getLogs devolve os logs que correspondem a um filtro: um intervalo de blocos fromBlock e toBlock, um contrato address e os topics do evento (Ethereum JSON-RPC). Um log contém endereços, o número do bloco, o hash da transação e o valor nas menores unidades do token. O bloco não tem preço em dólares, nome do proprietário nem marca de exchange.
Indexador: dos logs às tabelas
Um indexador lê os blocos em ordem, decodifica os eventos e os distribui em tabelas: transferências, swaps, mudanças nos pools. Ele divide o valor por 10 elevado aos decimals do token (com oito casas decimais, isso significa dividir por 100.000.000) e multiplica pelo preço no momento do bloco, o que dá o valor em dólares.
Depois vêm os limites: o feed mantém as transferências acima de um valor definido, e séries de pequenas transferências para um mesmo endereço são mescladas em uma só linha. Manter um pipeline desses para várias redes é um projeto à parte, e uma API de dados on-chain devolve o resultado em uma única requisição.
Rótulos de endereços: quem está por trás de um endereço
Um rótulo é um nome associado a um endereço: «Binance», «tesouraria do projeto», «market maker». Ele é atribuído a partir de indícios: o endereço encaminha moedas para uma carteira conhecida de uma exchange, o projeto publicou seus próprios endereços, o endereço recebeu tokens de um contrato de vesting. O proprietário não confirma nada disso, então um rótulo pode estar desatualizado ou simplesmente errado.
Um endereço sem indícios fica sem nome: nos exemplos da documentação da Genesis API, um remetente assim aparece com o endereço abreviado, 0xec01…d1a5.
Quais eventos on-chain importam para os traders
Um exemplo hipotético: em uma única manhã, US$ 2.000.000 da moeda de um projeto foram para exchanges e US$ 500.000 saíram da carteira da equipe para o endereço de um market maker. Cada evento sozinho diz pouco; juntos, são um motivo para conferir o preço, o open interest e o calendário de unlocks.
| Evento | O que você vê | Como costuma ser interpretado |
|---|---|---|
| Depósito em exchange | As moedas chegam a um endereço de exchange | Possível venda, garantia ou uma reorganização |
| Saque de exchange | As moedas saem para um endereço externo | Custódia, DeFi ou outra exchange |
| Grande transferência | Uma transferência acima do limite entre endereços | Uma baleia move sua posição |
| Carteira da equipe | Movimentos de endereços da fundação, da tesouraria ou dos fundadores | Um depósito em exchange pesa mais que um movimento interno |
| Posição em DEX de perpétuos | Long ou short: tamanho, preço, plataforma | A aposta de uma baleia e o risco de liquidação |
| Unlock | Data, parcela e valor da liberação | Nova oferta da moeda |
| Claim | Tokens de airdrop, vesting ou recompensas | Os destinatários podem vender de imediato |
| Mint e bridge | Emissão de tokens, movimentos entre redes | Mint de stablecoins significa entrada de dinheiro |
| Hack | Protocolo, perdas, técnica do ataque | Risco para o token e para as redes conectadas |
| Swap em DEX | Lado, valor, parcela do pool, movimento do preço | Mudança de preço antes de as exchanges reagirem |
As posições em exchanges descentralizadas de contratos perpétuos, as DEX de perpétuos, são visíveis porque essas plataformas mantêm seus dados abertos. Na Hyperliquid, o endpoint info POST https://api.hyperliquid.xyz/info com uma requisição clearinghouseState devolve as posições abertas e a margem de qualquer endereço, sem chave (documentação da Hyperliquid). As CEX não publicam as posições de outros traders; elas dão números agregados, como o open interest.
Um unlock é a liberação de tokens da equipe, de investidores ou da fundação conforme um cronograma de vesting, que os entrega em parcelas em datas definidas. A data é conhecida com antecedência, então o mercado pode precificar a venda antes do evento.
Um swap em uma DEX move o preço do pool no mesmo bloco. Um exemplo hipotético: uma compra de US$ 150.000 em um pool com US$ 1.200.000 de liquidez toma 150.000 / 1.200.000 × 100 = 12,5% do pool. O preço do pool se move de forma notável, enquanto nas exchanges o movimento aparece mais tarde ou nem aparece. Os preços de DEX e CEX são comparados no artigo sobre a API de DEX.
Um hack aparece on-chain como transferências de saída do contrato de um protocolo. As bridges são atacadas com mais frequência que outros protocolos porque seus contratos guardam grandes somas: os casos notáveis estão no artigo sobre pontes blockchain, e um roubo a uma exchange, na análise do hack da Bybit.
Latência e confirmação
Passam-se de segundos a minutos entre uma transação e uma linha no seu código; é a latência dos dados. Ela quase não importa para um resumo diário de fluxos, mas decide o resultado quando você reage a um grande depósito ou swap.
Confirmação da rede
No Ethereum, um novo bloco pode aparecer a cada slot, a cada 12 segundos, e se torna final após cerca de 15 minutos (ethereum.org). Um bloco finalizado não pode ser alterado sem a perda de uma quantidade enorme de ETH. Um indexador que precisa apenas do quadro consolidado pode ler blocos até a tag finalized, que é como um nó chama o último bloco finalizado.
Uma exchange credita um depósito quando a transação atinge um número mínimo de confirmações da rede, e na Binance, por exemplo, esse mínimo é diferente para cada moeda (FAQ da Binance). Assim, um depósito em uma exchange é visível on-chain antes de o proprietário poder vender essas moedas.
Atraso dos dados
No exemplo de swap da documentação da Genesis API, ts = 1794675511 é a hora do swap e published_at = 1794675523 é a hora da publicação: 1794675523 − 1794675511 = 12 segundos de diferença. Somam-se a isso a atualidade dos dados do seu plano em meta.freshness_sec (30 segundos no Start, 10 no Pro, 5 no Max) e o seu intervalo de polling.
| Etapa | Quanto leva | O que significa |
|---|---|---|
| Bloco do Ethereum | slot de 12 s | A transação é visível, mas não é final |
| Finalidade do Ethereum | cerca de 15 min | O bloco não vai mais mudar |
| Crédito na exchange | o mínimo de confirmações da exchange | Diferente para cada moeda |
| Publicação do swap | 12 s no exemplo | O registro ainda não é final |
Status final | não antes de 5 min após o swap | O preço após 30 s e 5 min é conhecido |
| Entrega da Genesis API | 30, 10 ou 5 s | Planos Start, Pro e Max |
Para os swaps, o feed period=live com registros não verificados é mais rápido, mas um registro pode desaparecer se o swap se revelar uma reorganização de liquidez. O parâmetro final=true mantém apenas os swaps verificados, que chegam pelo menos 5 minutos depois.
Dados on-chain na Genesis API
A Genesis API devolve os feeds da seção Genesis OnChain: as linhas de transferências já trazem os rótulos do remetente e do destinatário, o valor em dólares e em tokens, o hash da transação e um link para o explorador. As requisições são HTTP GET com a chave no cabeçalho X-API-Key, e a resposta é JSON com um campo data e um bloco meta.
| Endpoint | O que devolve | Planos |
|---|---|---|
/onchain/{section} | Uma das 9 seções on-chain | Start, Pro, Max |
/onchain | As 9 seções em um único objeto | Start, Pro, Max |
/onchain/dex-swaps | Grandes swaps em DEX | Pro, Max |
/onchain/analytics | Totais de 24h ou 7d | Pro, Max |
/onchain/coin/{symbol} | Um resumo de 7 dias de uma moeda | Pro, Max |
As seções têm o nome dos feeds: large-transfers, cex-flows, mint-bridge, team-wallets, perp-positions, unlocks, claims, hacks e coin-traffic, que contém séries de transferências de uma moeda para um mesmo destino. Os filtros são min_usd e coin, além de when com upcoming ou past para os unlocks. Não há parâmetro de tempo, então a janela é calculada a partir do campo ts.
Uma requisição dos próximos unlocks de tokens acima de US$ 1.000.000:
curl -G "https://api.genesisarbitrage.com/v1/onchain/unlocks" \
-d when=upcoming -d min_usd=1000000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
Uma linha de unlock tem unlock_percent e unlock_value_usd (parcela e valor), hours_left (horas até o evento) e allocations (divisão por destinatário).
Pro e Max acrescentam três endpoints. /onchain/dex-swaps devolve grandes swaps com a parcela de liquidez do pool, o impacto estimado no preço e o movimento do preço após 30 segundos e 5 minutos (visão geral de DEX na documentação). /onchain/analytics calcula totais para 24h ou 7d: kpi.cex_in, kpi.cex_out, kpi.cex_net e fluxos por exchange (análise OnChain). /onchain/coin/{symbol} reúne os eventos, swaps e unlocks de uma moeda em 7 dias junto com seu preço CEX, OI e funding (moeda OnChain).
Só uma resposta 200 consome a cota, e no Trial os endpoints on-chain devolvem 403 plan_restricted. O Start custa US$ 50 por mês por 2 M de chamadas, o Pro US$ 100 por 5 M e o Max US$ 200 por 10 M (preços da Genesis API). Todos os parâmetros e campos, com exemplos de resposta, estão no guia de endpoints on-chain.
Sem código, os mesmos feeds estão no painel do Genesis OnChain, os swaps na visão geral de DEX, e os totais diários e semanais na análise OnChain.
Python: depósitos de uma moeda em exchanges ao longo de uma janela
Um exemplo hipotético: em 6 horas, cinco transferências de ARB chegaram a exchanges, de US$ 640.000, US$ 520.000, US$ 410.000, US$ 330.000 e US$ 150.000. O total é 640.000 + 520.000 + 410.000 + 330.000 + 150.000 = 2.050.000, então o limite de US$ 2.000.000 é ultrapassado. Quando a primeira transferência passa de 6 horas, ela sai da janela: 2.050.000 − 640.000 = 1.410.000, e o total volta a ficar abaixo do limite.
cex-flows não tem um campo direction, então o sentido vem dos rótulos: uma exchange em to_name é um depósito, uma exchange em from_name é um saque. A resposta é o feed atual da seção, então o script mantém os depósitos por tx_hash e descarta os antigos por conta própria. Assim, o total da janela não é contado duas vezes entre um polling e outro.
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", 50_000
WINDOW = 6 * 3600 # janela, segundos
ALERT_USD = 2_000_000 # total de depósitos que dispara um alerta
CEX = ("binance", "okx", "bybit", "coinbase", "kraken")
deposits = {} # tx_hash -> (ts, usd)
alerted = False
def to_exchange(row):
label = (row.get("to_name") or "").lower()
return any(name in label 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()
for row in body["data"]:
if row.get("tx_hash") and to_exchange(row):
deposits[row["tx_hash"]] = (row.get("ts") or 0,
row.get("usd") or 0)
start = time.time() - WINDOW
deposits = {h: v for h, v in deposits.items() if v[0] >= start}
total = sum(usd for _, usd in deposits.values())
print(f"{COIN}: para exchanges em 6 h ${total:,.0f}, "
f"transferências {len(deposits)}")
if total >= ALERT_USD and not alerted:
print("Limite ultrapassado: confira preço, OI e funding")
alerted = total >= ALERT_USD
time.sleep(body["meta"]["freshness_sec"])
A tupla CEX contém substrings de rótulos; adicione as exchanges em que a moeda é negociada. O script apenas conta e imprime: a Genesis API não envia ordens, e a decisão de operar continua sendo sua.
Uma resposta a uma requisição com coin e min_usd vem sem ETag, então cada polling consome uma chamada. No Start a pausa é de 30 segundos, o que dá 2.592.000 / 30 = 86.400 chamadas em 30 dias, ou 4,32% da cota de 2 M. Para uma dúzia de moedas, busque o feed /onchain/cex-flows sem filtros e separe você mesmo: o conjunto completo vem com um ETag, e uma repetição com If-None-Match sobre dados inalterados devolve 304 sem consumir cota.
As transferências abaixo de min_usd não serão contadas: séries de pequenas transferências de uma moeda para uma exchange são agrupadas em coin-traffic, com os campos direction, total_usd, count e window_hours.
Como ler um depósito em exchange
Os mesmos US$ 2.050.000 em ARB que chegaram a exchanges em 6 horas podem ser a preparação de uma venda, garantia para futuros ou um movimento entre contas do próprio proprietário. Uma linha do feed não dirá qual deles.
| Cenário | O que mais você vê | Como verificar |
|---|---|---|
| Preparação para vender | Vendas em DEX, o preço enfraquece | /onchain/dex-swaps com side=sell |
| Garantia para futuros | O open interest cresce, o funding muda | /market/open-interest, /funding/rates |
| Reorganização interna | Um saque correspondente da mesma exchange | from_name em cex-flows, o explorador |
| Venda da equipe ou de um fundo | O remetente é uma carteira da equipe | team-wallets, unlocks |
Vários eventos de uma mesma moeda pesam mais que um só: um depósito em exchange, uma transferência da carteira da equipe e um unlock próximo. Você pode vê-los em uma única resposta de /onchain/coin/{symbol}, onde os eventos ficam ao lado do bloco cex com oi_usd e funding_8h. Os endpoints /market/open-interest e /funding/rates da tabela estão disponíveis a partir do Trial.
Outros dados de mercado e como escolher uma fonte para cada tarefa estão na visão geral da API de criptomoedas.
Perguntas e respostas
Qual é a precisão dos rótulos de endereços nos dados on-chain?
Os rótulos são atribuídos a partir de indícios e o dono do endereço não os confirma, então a precisão total não é possível. Quanto mais transferências ligam um endereço a uma carteira conhecida, mais confiável é a conclusão, e endereços novos ficam sem nome com mais frequência. Confira qualquer grande evento pelo link do explorador.
A Genesis API tem histórico on-chain?
Não há um arquivo profundo. As janelas mais longas são de 7 dias: period=7d para swaps e análise e o resumo de moeda de 7 dias, enquanto os unlocks passados vêm de when=past. Monte você mesmo um histórico longo salvando os registros a cada polling por tx_hash ou id.
O que significam os status pending e final nos swaps de DEX?
É o campo facts, o status de verificação do registro. pending significa que o swap foi publicado e o preço depois dele ainda é aguardado; publish e 30s são etapas intermediárias; final significa que o registro foi verificado e o preço após 30 segundos e 5 minutos é conhecido; unavailable significa que os facts não puderam ser coletados. Até o status ser final, um registro pode desaparecer, então guarde os swaps por id ou peça final=true.
Posso acompanhar baleias com uma API de graça?
Você pode pegar dados brutos do seu próprio nó ou de um endpoint público por JSON-RPC, mas aí os rótulos, os valores em dólares e os limites ficam por sua conta. A Genesis API não tem plano gratuito: as seções on-chain começam no plano Start a US$ 50 por mês, e os swaps em DEX e a análise, no Pro a US$ 100.