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
| Endpoint | Qué devuelve | Planes de la API |
|---|---|---|
/onchain/{section} | Una de las nueve secciones de Genesis OnChain | Start, Pro, Max |
/onchain | Las nueve secciones en un solo objeto | Start, Pro, Max |
/onchain/dex-swaps | Swaps grandes en DEX | Pro, Max |
/onchain/analytics | Analítica OnChain de 24h o 7d | Pro, Max |
/onchain/coin/{symbol} | Resumen de 7 días de una moneda | Pro, 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}
section | Qué contiene | Bloque del panel |
|---|---|---|
large-transfers | Grandes transferencias de tokens | Large Transfers |
cex-flows | Depósitos en exchanges y retiros de ellos | CEX Deposits / Withdrawals |
mint-bridge | Mint de tokens y transferencias por bridge | Mint / Bridge |
team-wallets | Movimientos de billeteras de equipos | Team Transfers |
perp-positions | Grandes posiciones en DEX perpetuos | Perp. DEX Positions |
unlocks | Unlocks de tokens | Unlocks |
claims | Claims | Claims |
coin-traffic | Serie de transferencias de una moneda a un mismo destino | Coin Traffic |
hacks | Hackeos y exploits | Hacks / 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ámetro | Tipo | Qué hace |
|---|---|---|
min_usd | number | Importe mínimo del evento, USD |
coin | string | Filas de una moneda; hacks no tiene moneda, así que la lista llega vacía |
when | string | Solo para unlocks: upcoming o past |
section | string | Secció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.
| Campos | Dónde | Significado |
|---|---|---|
ts, links | Todas las secciones | Hora del evento en segundos unix y enlaces listos: text + url |
token / token_name | Transferencias, coin-traffic | Ticker del token y nombre completo |
chain / chain_name, usd / amount | Transferencias | Red, importe en USD y en tokens |
from_* / to_* | Transferencias | Emisor y receptor: etiqueta, dirección, enlace al explorador |
tx_hash / explorer_url / arkham_url | Transferencias | Hash de la transacción, enlaces al explorador y a Arkham |
direction, target / target_address | coin-traffic | Dirección deposit, withdrawal o transfer y destino del flujo |
total_usd / count / window_hours, transfers[] | coin-traffic | Total de la serie, número de transferencias, ventana en horas y las mayores transferencias |
side / size / price / platform | perp-positions | Long o Short, tamaño, precio, plataforma |
unlock_percent / unlock_value_usd / hours_left / allocations | unlocks | Cuota y valor del unlock, horas restantes, asignaciones |
classification / technique / returned_funds | hacks | Clasificació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ámetro | Tipo | Qué hace |
|---|---|---|
period | string | live — los últimos 15 minutos, por defecto; 1h, 6h, 24h o 7d |
chain | string | Red |
side | string | buy o sell |
dex | string | DEX; varios separados por comas |
min_usd | number | Importe mínimo del swap, USD |
min_impact | number | Impacto absoluto mínimo en el pool, % |
final | boolean | true — solo swaps verificados |
token | string | Ticker del token |
q | string | Búsqueda por token, nombre, direcciones, trader, hash, DEX y red |
| Campo | Tipo | Significado |
|---|---|---|
id | string | Identificador estable: red, transacción, token |
tier | string | Nivel 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_pct | number o null | Liquidez 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_pct | number o null | Precio a los 30 s y a los 5 min y el movimiento del precio en los 5 minutos posteriores al swap |
facts | string | Estado de la verificación: pending, publish, 30s, final o unavailable |
trader_name / trader_address | string o null | Etiqueta 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.
| Campo | Tipo | Significado |
|---|---|---|
kpi | object | Totales: events, usd, tokens, cex_in, cex_out, cex_net |
hourly | object | Intervalos con paso de 1 h para 24h y de 6 h para 7d |
exchange_flows | object | Por exchange: in_usd, out_usd, net |
tokens | array | Hasta 40 monedas en foco con el evento mayor y el contexto CEX |
events | array | Feed 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.
| Campo | Tipo | Significado |
|---|---|---|
cex | object o null | Precio, OI, funding a 8 horas, mejor spread, redes, depósito y retiro; null si la moneda no está en los CEX compatibles |
kpi | object | Totales de 7 días: eventos, cex_in, cex_out, swaps, dex_buy, dex_sell |
by_section | object | Número de eventos por sección, con claves como large_tx y cex_deposits |
events / swaps | array | Eventos y swaps, hasta 2000; los totales completos en events_total y swaps_total |
unlocks.upcoming / unlocks.past | array | Unlocks 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…"
}
Fija la moneda y el umbral
coinymin_usddejan en la respuesta solo las transferencias grandes de una moneda.Separa depósitos de retiros
Un exchange en
to_namees un depósito; enfrom_name, un retiro. Compara las etiquetas por subcadena, sin distinguir mayúsculas.Cuenta la ventana y las transferencias nuevas
Suma las filas de la última hora según
tsy avisa solo con valores nuevos detx_hash.Consulta con la frescura de tu plan
Haz una pausa de
meta.freshness_secentre peticiones; ante429y503, esperaRetry-Aftersegundos.
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.