Genesis Arbitrage

Genesis Arbitrage · · 12 min de leitura

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

EndpointO que retornaPlanos da API
/onchain/{section}Uma das nove seções do Genesis OnChainStart, Pro, Max
/onchainAs nove seções em um único objetoStart, Pro, Max
/onchain/dex-swapsSwaps grandes em DEXPro, Max
/onchain/analyticsAnálise OnChain de 24h ou 7dPro, Max
/onchain/coin/{symbol}Resumo de 7 dias de uma moedaPro, 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}

sectionO que contémBloco do painel
large-transfersGrandes transferências de tokensLarge Transfers
cex-flowsDepósitos em exchanges e saques delasCEX Deposits / Withdrawals
mint-bridgeMint de tokens e transferências por bridgeMint / Bridge
team-walletsMovimentações de carteiras de equipesTeam Transfers
perp-positionsGrandes posições em DEX perpétuosPerp. DEX Positions
unlocksUnlocks de tokensUnlocks
claimsClaimsClaims
coin-trafficSérie de transferências de uma moeda para um mesmo destinoCoin Traffic
hacksHacks e exploitsHacks / 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âmetroTipoO que faz
min_usdnumberValor mínimo do evento, USD
coinstringLinhas de uma moeda; hacks não tem moeda, então a lista volta vazia
whenstringSomente para unlocks: upcoming ou past
sectionstringSeçã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.

CamposOndeSignificado
ts, linksTodas as seçõesHora do evento em segundos unix e links prontos: text + url
token / token_nameTransferências, coin-trafficTicker do token e nome completo
chain / chain_name, usd / amountTransferênciasRede, valor em USD e em tokens
from_* / to_*TransferênciasRemetente e destinatário: rótulo, endereço, link do explorador
tx_hash / explorer_url / arkham_urlTransferênciasHash da transação, links do explorador e da Arkham
direction, target / target_addresscoin-trafficSentido deposit, withdrawal ou transfer e destino do fluxo
total_usd / count / window_hours, transfers[]coin-trafficTotal da série, número de transferências, janela em horas e as maiores transferências
side / size / price / platformperp-positionsLong ou Short, tamanho, preço, plataforma
unlock_percent / unlock_value_usd / hours_left / allocationsunlocksParcela e valor do unlock, horas restantes, alocações
classification / technique / returned_fundshacksClassificaçã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âmetroTipoO que faz
periodstringlive — os últimos 15 minutos, padrão; 1h, 6h, 24h ou 7d
chainstringRede
sidestringbuy ou sell
dexstringDEX; separadas por vírgula para várias
min_usdnumberValor mínimo do swap, USD
min_impactnumberImpacto absoluto mínimo no pool, %
finalbooleantrue — somente swaps verificados
tokenstringTicker do token
qstringBusca por token, nome, endereços, trader, hash, DEX e rede
CampoTipoSignificado
idstringIdentificador estável: rede, transação, token
tierstringNí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_pctnumber ou nullLiquidez 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_pctnumber ou nullPreço após 30 s e 5 min e a variação do preço nos 5 minutos seguintes ao swap
factsstringStatus da verificação: pending, publish, 30s, final ou unavailable
trader_name / trader_addressstring ou nullRó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.

CampoTipoSignificado
kpiobjectTotais: events, usd, tokens, cex_in, cex_out, cex_net
hourlyobjectIntervalos com passo de 1 h para 24h e de 6 h para 7d
exchange_flowsobjectPor exchange: in_usd, out_usd, net
tokensarrayAté 40 moedas em foco com o maior evento e o contexto CEX
eventsarrayFeed 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.

CampoTipoSignificado
cexobject ou nullPreço, OI, funding de 8 horas, melhor spread, redes, depósito e saque; null se a moeda não está nas CEX compatíveis
kpiobjectTotais de 7 dias: eventos, cex_in, cex_out, swaps, dex_buy, dex_sell
by_sectionobjectNúmero de eventos por seção, com chaves como large_tx e cex_deposits
events / swapsarrayEventos e swaps, até 2000; totais completos em events_total e swaps_total
unlocks.upcoming / unlocks.pastarrayUnlocks 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…"
}
  1. Defina a moeda e o limite

    coin e min_usd mantêm na resposta apenas as grandes transferências de uma moeda.

  2. Separe depósitos de saques

    Uma exchange em to_name é depósito; em from_name, saque. Compare os rótulos por substring, sem diferenciar maiúsculas.

  3. Conte a janela e as transferências novas

    Some as linhas da última hora por ts e avise apenas para novos valores de tx_hash.

  4. Consulte na atualização do seu plano

    Faça uma pausa de meta.freshness_sec entre as requisições; em 429 e 503, aguarde Retry-After segundos.

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.