Genesis Arbitrage

Genesis Arbitrage · · 16 min de lectura

API de datos on-chain: transferencias de ballenas, flujos de exchanges y unlocks de tokens

En resumen

  • Una API de datos on-chain devuelve eventos de la blockchain ya decodificados: qué token se movió, de quién, a quién y por cuántos dólares. Los datos en bruto vienen de los nodos, los indexadores los convierten en tablas y las etiquetas de direcciones siguen siendo una atribución que puede fallar.
  • Los traders vigilan depósitos y retiros en exchanges, transferencias grandes, movimientos de billeteras de equipos, posiciones en DEX de perpetuos, unlocks, claims, hackeos y swaps grandes en DEX. Un depósito en un exchange no siempre termina en venta.
  • En Genesis API las nueve secciones on-chain están disponibles desde el plan Start, mientras que los swaps en DEX, la analítica y el resumen de moneda requieren Pro o Max. Tu código calcula la ventana y los totales de flujo, porque las secciones no tienen parámetro de tiempo.

Una API de datos on-chain es una interfaz HTTP a eventos de la blockchain que ya se han recopilado, convertido a dólares y etiquetado: qué token se movió, desde qué dirección, hacia cuál y en qué transacción. Con una API así puedes seguir transferencias de ballenas, entradas a exchanges, unlocks de tokens y swaps grandes en un DEX sin ejecutar tu propio nodo ni indexador. Aquí, una ballena es una dirección que posee tanta cantidad de una moneda que sus transferencias pueden mover el mercado.

De dónde salen los datos on-chain

Los datos pasan por tres capas: un nodo guarda los bloques, un indexador los convierte en filas de eventos y una base de etiquetas pone nombre a las direcciones.

Nodo: bloques y logs

Un nodo de blockchain guarda bloques y los sirve por JSON-RPC. En Ethereum y las cadenas compatibles, una transferencia de un token ERC-20 se escribe en el registro de la transacción como el evento Transfer(address indexed _from, address indexed _to, uint256 _value), y el estándar recomienda emitir el mismo evento con 0x0 como remitente cuando se acuñan tokens nuevos (EIP-20).

El método eth_getLogs devuelve los logs que cumplen un filtro: un rango de bloques fromBlock y toBlock, una address de contrato y los topics del evento (Ethereum JSON-RPC). Un log contiene direcciones, el número de bloque, el hash de la transacción y el importe en las unidades mínimas del token. El bloque no tiene precio en dólares, ni nombre del propietario, ni marca de exchange.

Indexador: de los logs a las tablas

Un indexador lee los bloques en orden, decodifica los eventos y los reparte en tablas: transferencias, swaps, cambios en los pools. Divide el importe entre 10 elevado a los decimals del token (con ocho decimales, es dividir entre 100 000 000) y lo multiplica por el precio en el momento del bloque, lo que da el valor en dólares.

Después vienen los umbrales: el feed conserva las transferencias por encima de un importe fijado, y las series de transferencias pequeñas a una misma dirección se fusionan en una sola fila. Mantener un pipeline así para varias cadenas es un proyecto aparte, y una API de datos on-chain devuelve su resultado en una sola petición.

Etiquetas de direcciones: quién está detrás de una dirección

Una etiqueta es un nombre asociado a una dirección: «Binance», «tesorería del proyecto», «market maker». Se asigna a partir de indicios: la dirección reenvía monedas a una billetera conocida de un exchange, el proyecto publicó sus direcciones, la dirección recibió tokens de un contrato de vesting. El propietario no confirma nada de esto, así que una etiqueta puede estar desactualizada o simplemente ser errónea.

Una dirección sin indicios queda sin nombre: en los ejemplos de la documentación de Genesis API, un remitente así muestra la dirección abreviada, 0xec01…d1a5.

Qué eventos on-chain importan a los traders

Un ejemplo hipotético: en una sola mañana, 2 000 000 $ de la moneda de un proyecto fueron a exchanges y 500 000 $ salieron de la billetera del equipo hacia la dirección de un market maker. Cada evento por separado dice poco; juntos son un motivo para revisar el precio, el open interest y el calendario de unlocks.

EventoQué se veCómo se suele interpretar
Depósito en un exchangeLas monedas llegan a una dirección de un exchangePosible venta, garantía o una reorganización
Retiro de un exchangeLas monedas salen hacia una dirección externaCustodia, DeFi u otro exchange
Transferencia grandeUna transferencia por encima del umbral entre direccionesUna ballena mueve su posición
Billetera del equipoMovimientos desde direcciones de la fundación, la tesorería o los fundadoresUn depósito en un exchange pesa más que un movimiento interno
Posición en DEX de perpetuosLong o short: tamaño, precio, plataformaLa apuesta de una ballena y el riesgo de liquidación
UnlockFecha, porcentaje y valor de la liberaciónNueva oferta de la moneda
ClaimTokens de un airdrop, vesting o recompensasLos destinatarios pueden vender de inmediato
Mint y bridgeEmisión de tokens, movimientos entre cadenasLa acuñación de stablecoins significa entrada de dinero
HackeoProtocolo, pérdidas, técnica del ataqueRiesgo para el token y las cadenas conectadas
Swap en DEXLado, importe, parte del pool, movimiento del precioCambio de precio antes de que reaccionen los exchanges

Las posiciones en exchanges descentralizados de futuros perpetuos, los DEX de perpetuos, son visibles porque estas plataformas mantienen sus datos abiertos. En Hyperliquid, el endpoint info POST https://api.hyperliquid.xyz/info con una petición clearinghouseState devuelve las posiciones abiertas y el margen de cualquier dirección, sin clave (documentación de Hyperliquid). Los CEX no publican las posiciones de otros traders; ofrecen cifras agregadas como el open interest.

Un unlock es la liberación de tokens del equipo, de inversores o de la fundación según un calendario de vesting, que los entrega en tramos en fechas fijas. La fecha se conoce de antemano, por lo que el mercado puede descontar la venta antes del evento.

Un swap en un DEX mueve el precio del pool en el mismo bloque. Un ejemplo hipotético: una compra de 150 000 $ en un pool con 1 200 000 $ de liquidez toma 150 000 / 1 200 000 × 100 = 12,5 % del pool. El precio del pool se mueve de forma notable, mientras que en los exchanges el movimiento aparece más tarde o no aparece. Los precios de DEX y CEX se comparan en el artículo sobre la API de DEX.

Un hackeo se ve on-chain como transferencias de salida desde el contrato de un protocolo. Los bridges sufren más ataques que otros protocolos porque sus contratos guardan grandes sumas: los casos más destacados están en el artículo sobre puentes blockchain, y un robo a un exchange en el análisis del hackeo de Bybit.

Latencia y confirmación

Pasan de segundos a minutos entre una transacción y una fila en tu código; es la latencia de los datos. Apenas importa para un resumen diario de flujos, pero decide el resultado cuando reaccionas a un depósito o un swap grande.

Confirmación de la red

En Ethereum puede aparecer un bloque nuevo en cada slot, cada 12 segundos, y se vuelve final tras unos 15 minutos (ethereum.org). Un bloque finalizado no se puede cambiar a menos que se pierda una cantidad enorme de ETH. Un indexador que solo necesita la imagen consolidada puede leer bloques hasta la etiqueta finalized, que es como un nodo llama al último bloque finalizado.

Un exchange acredita un depósito cuando la transacción alcanza un número mínimo de confirmaciones de red, y en Binance, por ejemplo, ese mínimo es distinto para cada moneda (FAQ de Binance). Así, un depósito en un exchange es visible on-chain antes de que el propietario pueda vender esas monedas.

Retraso de los datos

En el ejemplo de swap de la documentación de Genesis API, ts = 1794675511 es la hora del swap y published_at = 1794675523 es la hora de publicación: 1794675523 − 1794675511 = 12 segundos de diferencia. A eso se suman la frescura de los datos de tu plan en meta.freshness_sec (30 segundos en Start, 10 en Pro, 5 en Max) y tu intervalo de polling.

EtapaCuánto duraQué significa
Bloque de Ethereumslot de 12 sLa transacción es visible pero no es final
Finalidad de Ethereumunos 15 minEl bloque ya no cambiará
Acreditación en el exchangeel mínimo de confirmaciones del exchangeDistinto para cada moneda
Publicación del swap12 s en el ejemploEl registro aún no es final
Estado finalno antes de 5 min tras el swapSe conoce el precio a los 30 s y a los 5 min
Entrega de Genesis API30, 10 o 5 sPlanes Start, Pro y Max

Para los swaps, el feed period=live con registros sin verificar es más rápido, pero un registro puede desaparecer si el swap resulta ser una reorganización de liquidez. El parámetro final=true conserva solo los swaps verificados, que llegan al menos 5 minutos más tarde.

Datos on-chain en Genesis API

Genesis API devuelve los feeds de la sección Genesis OnChain: las filas de transferencias ya incluyen las etiquetas del remitente y del receptor, el importe en dólares y en tokens, el hash de la transacción y un enlace al explorador. Las peticiones son HTTP GET con la clave en el encabezado X-API-Key, y la respuesta es JSON con un campo data y un bloque meta.

EndpointQué devuelvePlanes
/onchain/{section}Una de las 9 secciones on-chainStart, Pro, Max
/onchainLas 9 secciones en un solo objetoStart, Pro, Max
/onchain/dex-swapsSwaps grandes en DEXPro, Max
/onchain/analyticsTotales de 24h o 7dPro, Max
/onchain/coin/{symbol}Un resumen de 7 días de una monedaPro, Max

Las secciones se llaman como los feeds: large-transfers, cex-flows, mint-bridge, team-wallets, perp-positions, unlocks, claims, hacks y coin-traffic, que contiene series de transferencias de una moneda a un mismo destino. Los filtros son min_usd y coin, además de when con upcoming o past para los unlocks. No hay parámetro de tiempo, así que la ventana se calcula a partir del campo ts.

Una petición de los próximos unlocks de tokens por más de 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"

Una fila de unlock tiene unlock_percent y unlock_value_usd (porcentaje y valor), hours_left (horas hasta el evento) y allocations (desglose por destinatario).

Pro y Max añaden tres endpoints. /onchain/dex-swaps devuelve swaps grandes con la parte de liquidez del pool, el impacto estimado en el precio y el movimiento del precio a los 30 segundos y a los 5 minutos (resumen DEX en la documentación). /onchain/analytics calcula totales para 24h o 7d: kpi.cex_in, kpi.cex_out, kpi.cex_net y flujos por exchange (analítica OnChain). /onchain/coin/{symbol} reúne los eventos, swaps y unlocks de una moneda durante 7 días junto con su precio CEX, OI y funding (moneda OnChain).

Solo una respuesta 200 consume cuota, y en Trial los endpoints on-chain devuelven 403 plan_restricted. Start cuesta 50 $ al mes por 2 M de llamadas, Pro 100 $ por 5 M y Max 200 $ por 10 M (precios de Genesis API). Todos los parámetros y campos, con ejemplos de respuesta, están en la guía de endpoints on-chain.

Sin código, los mismos feeds están en el panel de Genesis OnChain, los swaps en el resumen DEX, y los totales diarios y semanales en la analítica OnChain.

Python: depósitos de una moneda en exchanges durante una ventana

Un ejemplo hipotético: en 6 horas llegaron a exchanges cinco transferencias de ARB, por 640 000 $, 520 000 $, 410 000 $, 330 000 $ y 150 000 $. El total es 640 000 + 520 000 + 410 000 + 330 000 + 150 000 = 2 050 000, así que se supera el umbral de 2 000 000 $. Cuando la primera transferencia tiene más de 6 horas, sale de la ventana: 2 050 000 − 640 000 = 1 410 000, y el total vuelve a quedar por debajo del umbral.

cex-flows no tiene un campo direction, así que la dirección sale de las etiquetas: un exchange en to_name es un depósito, un exchange en from_name es un retiro. La respuesta es el feed actual de la sección, así que el script conserva los depósitos por tx_hash y descarta los antiguos por su cuenta. De ese modo el total de la ventana no se cuenta dos veces entre un polling y otro.

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        # ventana, segundos
ALERT_USD = 2_000_000    # total de depósitos que dispara una 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):  # límite de peticiones o reconstrucción
        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}: a exchanges en 6 h ${total:,.0f}, "
          f"transferencias {len(deposits)}")
    if total >= ALERT_USD and not alerted:
        print("Umbral superado: revisa precio, OI y funding")
    alerted = total >= ALERT_USD
    time.sleep(body["meta"]["freshness_sec"])

La tupla CEX contiene subcadenas de etiquetas; añade los exchanges donde cotiza la moneda. El script solo cuenta e imprime: Genesis API no coloca órdenes, y la decisión de operar sigue siendo tuya.

Una respuesta a una petición con coin y min_usd llega sin ETag, así que cada polling consume una llamada. En Start la pausa es de 30 segundos, lo que son 2 592 000 / 30 = 86 400 llamadas en 30 días, o el 4,32 % de la cuota de 2 M. Para una docena de monedas, pide el feed /onchain/cex-flows sin filtros y sepáralo tú mismo: el conjunto completo llega con un ETag, y una repetición con If-None-Match sobre datos sin cambios devuelve 304 sin consumir cuota.

Las transferencias por debajo de min_usd no se contarán: las series de transferencias pequeñas de una moneda a un exchange se agrupan en coin-traffic, con los campos direction, total_usd, count y window_hours.

Cómo leer un depósito en un exchange

Los mismos 2 050 000 $ de ARB que llegaron a exchanges en 6 horas podrían ser la preparación de una venta, garantía para futuros o un movimiento entre cuentas del propio propietario. Una fila del feed no te dirá cuál de los tres.

EscenarioQué más se veCómo comprobarlo
Preparación de una ventaVentas en DEX, el precio se debilita/onchain/dex-swaps con side=sell
Garantía para futurosCrece el open interest, cambia el funding/market/open-interest, /funding/rates
Reorganización internaUn retiro equivalente del mismo exchangefrom_name en cex-flows, el explorador
Venta del equipo o de un fondoEl remitente es una billetera del equipoteam-wallets, unlocks

Varios eventos sobre una misma moneda pesan más que uno solo: un depósito en un exchange, una transferencia desde la billetera del equipo y un unlock próximo. Puedes verlos en una única respuesta de /onchain/coin/{symbol}, donde los eventos están junto al bloque cex con oi_usd y funding_8h. Los endpoints /market/open-interest y /funding/rates de la tabla están disponibles desde Trial.

Otros datos de mercado y cómo elegir una fuente para cada tarea se explican en la guía de la API de criptomonedas.

Preguntas y respuestas

¿Qué precisión tienen las etiquetas de direcciones en los datos on-chain?

Las etiquetas se asignan a partir de indicios y el propietario de la dirección no las confirma, así que no es posible una precisión total. Cuantas más transferencias vinculan una dirección con una billetera conocida, más fiable es la conclusión, y las direcciones nuevas quedan sin nombre con más frecuencia. Comprueba cualquier evento grande desde el enlace del explorador.

¿Tiene Genesis API historial on-chain?

No hay un archivo profundo. Las ventanas más largas son de 7 días: period=7d para swaps y analítica y el resumen de moneda de 7 días, mientras que los unlocks pasados salen de when=past. Construye tú mismo un historial largo guardando los registros en cada polling por tx_hash o id.

¿Qué significan los estados pending y final en los swaps de DEX?

Es el campo facts, el estado de verificación del registro. pending significa que el swap está publicado y aún se espera el precio posterior; publish y 30s son etapas intermedias; final significa que el registro está verificado y se conoce el precio a los 30 segundos y a los 5 minutos; unavailable significa que no se pudieron recopilar los facts. Hasta que el estado sea final, un registro puede desaparecer, así que guarda los swaps por id o pide final=true.

¿Puedo seguir a las ballenas con una API gratis?

Puedes tomar datos en bruto de tu propio nodo o de un endpoint público por JSON-RPC, pero entonces las etiquetas, los importes en dólares y los umbrales los construyes tú. Genesis API no tiene plan gratuito: las secciones on-chain empiezan con el plan Start a 50 $ al mes, y los swaps en DEX y la analítica con Pro a 100 $.