Genesis Arbitrage

Genesis Arbitrage · · 12 min de lectura

Datos on-chain en Genesis API: transferencias, flujos, unlocks, swaps en DEX

En resumen

  • El endpoint /onchain/{section} devuelve cualquiera de los nueve feeds de Genesis OnChain, desde grandes transferencias hasta hackeos, en los planes Start, Pro y Max. Una petición a /onchain sin sección devuelve todos los feeds en un solo objeto.
  • Los swaps grandes en DEX, la analítica de 24 horas o 7 días y el resumen de 7 días de una moneda están disponibles en los planes Pro y Max.
  • Las etiquetas de direcciones son una atribución, no una garantía. Una transferencia a un exchange no siempre significa una venta, y un registro de swap puede desaparecer tras la verificación.

Los endpoints on-chain de Genesis API devuelven los datos de la sección Genesis OnChain: grandes transferencias de tokens, depósitos y retiros de exchanges, movimientos de billeteras de equipos, posiciones en DEX perpetuos, unlocks de tokens, claims y hackeos, además de swaps grandes en DEX. Cada fila ya incluye las etiquetas del emisor y del receptor, el importe en USD y enlaces al explorador. Es suficiente para seguir a las ballenas y monitorear los flujos de los exchanges desde tu propio código, sin un indexador de blockchain propio.

Endpoints y planes

EndpointQué devuelvePlanes de la API
/onchain/{section}Una de las nueve secciones de Genesis OnChainStart, Pro, Max
/onchainLas nueve secciones en un solo objetoStart, Pro, Max
/onchain/dex-swapsSwaps grandes en DEXPro, Max
/onchain/analyticsAnalítica OnChain de 24h o 7dPro, Max
/onchain/coin/{symbol}Resumen de 7 días de una monedaPro, Max

En Trial, todos los endpoints on-chain devuelven 403 plan_restricted. La frescura es de 30 s en Start, 10 s en Pro y 5 s en Max, y el mismo valor llega en meta.freshness_sec. La clave y la primera petición se explican en el inicio rápido, las cuotas en los límites de Genesis API.

Nueve secciones de /onchain/{section}

sectionQué contieneBloque del panel
large-transfersGrandes transferencias de tokensLarge Transfers
cex-flowsDepósitos en exchanges y retiros de ellosCEX Deposits / Withdrawals
mint-bridgeMint de tokens y transferencias por bridgeMint / Bridge
team-walletsMovimientos de billeteras de equiposTeam Transfers
perp-positionsGrandes posiciones en DEX perpetuosPerp. DEX Positions
unlocksUnlocks de tokensUnlocks
claimsClaimsClaims
coin-trafficSerie de transferencias de una moneda a un mismo destinoCoin Traffic
hacksHackeos y exploitsHacks / Exploits

Qué muestra cada bloque y qué señales buscar se explica en la guía del panel de Genesis OnChain, los parámetros en la documentación. Una petición a /onchain sin sección devuelve en data un objeto: la clave es el nombre de la sección y el valor, sus filas. Los filtros se aplican entonces a todas las secciones.

ParámetroTipoQué hace
min_usdnumberImporte mínimo del evento, USD
coinstringFilas de una moneda; hacks no tiene moneda, así que la lista llega vacía
whenstringSolo para unlocks: upcoming o past
sectionstringSección para una petición /onchain?section=…

Cualquier otro valor de when devuelve 400 bad_request. A continuación, la sección coin-traffic, un elemento del 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 de las secciones

Las secciones large-transfers, cex-flows, mint-bridge, team-wallets y claims se componen de transferencias; las demás tienen campos propios.

CamposDóndeSignificado
ts, linksTodas las seccionesHora del evento en segundos unix y enlaces listos: text + url
token / token_nameTransferencias, coin-trafficTicker del token y nombre completo
chain / chain_name, usd / amountTransferenciasRed, importe en USD y en tokens
from_* / to_*TransferenciasEmisor y receptor: etiqueta, dirección, enlace al explorador
tx_hash / explorer_url / arkham_urlTransferenciasHash de la transacción, enlaces al explorador y a Arkham
direction, target / target_addresscoin-trafficDirección deposit, withdrawal o transfer y destino del flujo
total_usd / count / window_hours, transfers[]coin-trafficTotal de la serie, número de transferencias, ventana en horas y las mayores transferencias
side / size / price / platformperp-positionsLong o Short, tamaño, precio, plataforma
unlock_percent / unlock_value_usd / hours_left / allocationsunlocksCuota y valor del unlock, horas restantes, asignaciones
classification / technique / returned_fundshacksClasificación, técnica del ataque, fondos devueltos

Swaps en DEX: /onchain/dex-swaps

Planes Pro y Max. El endpoint devuelve el feed de swaps grandes, como la pantalla Resumen DEX: cada swap muestra qué parte de la liquidez del pool absorbió, qué movimiento de precio cabe esperar y qué pasó a los 30 segundos y a los 5 minutos. El esquema de la respuesta está en la documentación.

ParámetroTipoQué hace
periodstringlive — los últimos 15 minutos, por defecto; 1h, 6h, 24h o 7d
chainstringRed
sidestringbuy o sell
dexstringDEX; varios separados por comas
min_usdnumberImporte mínimo del swap, USD
min_impactnumberImpacto absoluto mínimo en el pool, %
finalbooleantrue — solo swaps verificados
tokenstringTicker del token
qstringBúsqueda por token, nombre, direcciones, trader, hash, DEX y red
CampoTipoSignificado
idstringIdentificador estable: red, transacción, token
tierstringNivel según la liquidez del pool: de T1 ($30.000–100.000) a T4 (más de $10 M)
pool_liquidity_usd / size_pct_liquidity / impact_est_pctnumber o nullLiquidez del pool, la parte del swap en ella y el impacto estimado en el precio, %
price_after_30s_usd / price_after_5m_usd / move_after_5m_pctnumber o nullPrecio a los 30 s y a los 5 min y el movimiento del precio en los 5 minutos posteriores al swap
factsstringEstado de la verificación: pending, publish, 30s, final o unavailable
trader_name / trader_addressstring o nullEtiqueta y dirección del trader

En el ejemplo siguiente, un swap de $412.500 en un pool con $4.120.000 de liquidez absorbió 412.500 / 4.120.000 × 100 = 10,01 % del pool. El impacto estimado es del 4,8 % y, a los 5 minutos, el precio se había movido un 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"
}

Analítica OnChain: /onchain/analytics

También para Pro y Max. Una sola llamada devuelve la pantalla Analítica de Genesis OnChain para period=24h (por defecto) o 7d, con totales, intervalos por hora, flujos de exchanges, unlocks, hackeos, monedas en foco y el feed de eventos. Todos los campos están en la documentación.

CampoTipoSignificado
kpiobjectTotales: events, usd, tokens, cex_in, cex_out, cex_net
hourlyobjectIntervalos con paso de 1 h para 24h y de 6 h para 7d
exchange_flowsobjectPor exchange: in_usd, out_usd, net
tokensarrayHasta 40 monedas en foco con el evento mayor y el contexto CEX
eventsarrayFeed de eventos del período, hasta 600

cex_net son los depósitos menos los retiros: en el ejemplo, 312.456.789 − 287.654.321 = 24.802.468, es decir, $24,8 M más entraron en exchanges de los que salieron.

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": [ … ]
}

Moneda OnChain: /onchain/coin/{symbol}

Pro y Max también reciben un resumen de 7 días de una moneda, como la página de moneda: eventos on-chain, swaps en DEX, unlocks y contexto CEX. El ticker va en la ruta, de 1 a 32 caracteres, y la respuesta se reconstruye como máximo una vez cada 10 segundos. Los campos están en la documentación.

CampoTipoSignificado
cexobject o nullPrecio, OI, funding a 8 horas, mejor spread, redes, depósito y retiro; null si la moneda no está en los CEX compatibles
kpiobjectTotales de 7 días: eventos, cex_in, cex_out, swaps, dex_buy, dex_sell
by_sectionobjectNúmero de eventos por sección, con claves como large_tx y cex_deposits
events / swapsarrayEventos y swaps, hasta 2000; los totales completos en events_total y swaps_total
unlocks.upcoming / unlocks.pastarrayUnlocks próximos y pasados
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
}

Ejemplo hipotético: depósitos de una moneda en exchanges con cex-flows

El objetivo es saber cuánto de una moneda se movió a exchanges en la última hora y recibir un aviso por cada depósito grande. En cex-flows la dirección se ve en las etiquetas: un exchange en to_name es un depósito, un exchange en from_name es un retiro.

En una hora, ARB registró cuatro depósitos: $412.000, $260.000, $180.000 y $148.000, en total $412.000 + $260.000 + $180.000 + $148.000 = $1.000.000. Hubo un retiro de $150.000. El flujo neto hacia los exchanges es $1.000.000 − $150.000 = $850.000: entra más de lo que sale. Así se ve la fila hipotética del primer 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. Fija la moneda y el umbral

    coin y min_usd dejan en la respuesta solo las transferencias grandes de una moneda.

  2. Separa depósitos de retiros

    Un exchange en to_name es un depósito; en from_name, un retiro. Compara las etiquetas por subcadena, sin distinguir mayúsculas.

  3. Cuenta la ventana y las transferencias nuevas

    Suma las filas de la última hora según ts y avisa solo con valores nuevos de tx_hash.

  4. Consulta con la frescura de tu plan

    Haz una pausa de meta.freshness_sec entre peticiones; ante 429 y 503, espera 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")  # subcadenas de etiquetas
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 o reconstrucción
        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 en un 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")):  # retiro
            outflow += usd
    print(f"última hora: a exchanges ${inflow:,.0f}, "
          f"flujo neto ${inflow - outflow:,.0f}")
    time.sleep(body["meta"]["freshness_sec"])

El script solo lee datos e imprime avisos; qué hacer con la moneda es decisión tuya. Las series de transferencias pequeñas a un mismo exchange se agrupan en la sección coin-traffic, donde la dirección ya viene en el campo direction. Los totales de todas las monedas salen de /onchain/analytics en kpi.cex_in, kpi.cex_out y kpi.cex_net, y una visión general de los usos de los datos on-chain está en el artículo sobre la API de datos on-chain.

Preguntas y respuestas

¿Qué plan necesito para los datos on-chain?

Las nueve secciones de /onchain/{section} están abiertas en Start, Pro y Max. Los swaps en DEX, la analítica y el resumen de moneda son solo para Pro y Max, y en Trial los endpoints on-chain devuelven 403 plan_restricted.

¿Hay historial de más de 7 días?

Las ventanas más largas son period=7d para swaps y analítica y 7 días en el resumen de moneda; Genesis API no tiene un archivo aparte. Para un historial largo, guarda los registros tú mismo en cada consulta.

¿Por qué desapareció un swap de la respuesta?

La verificación detectó una reorganización de liquidez en lugar de una operación, y el registro se eliminó. Compara los swaps guardados por id o pide solo final=true.

¿Cómo obtengo los próximos unlocks de tokens?

Pide /onchain/unlocks?when=upcoming. Cada fila trae unlock_percent y unlock_value_usd, la cuota y el valor del unlock, y hours_left, las horas que faltan. min_usd fija un umbral de valor y coin elige una moneda.