Genesis Arbitrage

Genesis Arbitrage · · 15 min de leitura

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.

EventoO que você vêComo costuma ser interpretado
Depósito em exchangeAs moedas chegam a um endereço de exchangePossível venda, garantia ou uma reorganização
Saque de exchangeAs moedas saem para um endereço externoCustódia, DeFi ou outra exchange
Grande transferênciaUma transferência acima do limite entre endereçosUma baleia move sua posição
Carteira da equipeMovimentos de endereços da fundação, da tesouraria ou dos fundadoresUm depósito em exchange pesa mais que um movimento interno
Posição em DEX de perpétuosLong ou short: tamanho, preço, plataformaA aposta de uma baleia e o risco de liquidação
UnlockData, parcela e valor da liberaçãoNova oferta da moeda
ClaimTokens de airdrop, vesting ou recompensasOs destinatários podem vender de imediato
Mint e bridgeEmissão de tokens, movimentos entre redesMint de stablecoins significa entrada de dinheiro
HackProtocolo, perdas, técnica do ataqueRisco para o token e para as redes conectadas
Swap em DEXLado, valor, parcela do pool, movimento do preçoMudanç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.

EtapaQuanto levaO que significa
Bloco do Ethereumslot de 12 sA transação é visível, mas não é final
Finalidade do Ethereumcerca de 15 minO bloco não vai mais mudar
Crédito na exchangeo mínimo de confirmações da exchangeDiferente para cada moeda
Publicação do swap12 s no exemploO registro ainda não é final
Status finalnão antes de 5 min após o swapO preço após 30 s e 5 min é conhecido
Entrega da Genesis API30, 10 ou 5 sPlanos 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.

EndpointO que devolvePlanos
/onchain/{section}Uma das 9 seções on-chainStart, Pro, Max
/onchainAs 9 seções em um único objetoStart, Pro, Max
/onchain/dex-swapsGrandes swaps em DEXPro, Max
/onchain/analyticsTotais de 24h ou 7dPro, Max
/onchain/coin/{symbol}Um resumo de 7 dias de uma moedaPro, 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árioO que mais você vêComo verificar
Preparação para venderVendas em DEX, o preço enfraquece/onchain/dex-swaps com side=sell
Garantia para futurosO open interest cresce, o funding muda/market/open-interest, /funding/rates
Reorganização internaUm saque correspondente da mesma exchangefrom_name em cex-flows, o explorador
Venda da equipe ou de um fundoO remetente é uma carteira da equipeteam-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.