Données on-chain dans Genesis API : transferts, flux, unlocks, swaps DEX
En bref
- Le endpoint /onchain/{section} renvoie l’un des neuf flux Genesis OnChain, des grands transferts aux hacks, sur les plans Start, Pro et Max. Une requête sur /onchain sans section renvoie tous les flux dans un seul objet.
- Les gros swaps DEX, l’analytique sur 24 heures ou 7 jours et la synthèse d’un coin sur 7 jours sont disponibles sur les plans Pro et Max.
- Les étiquettes d’adresses relèvent de l’attribution, pas de la certitude. Un transfert vers un exchange ne signifie pas toujours une vente, et un enregistrement de swap peut disparaître après vérification.
Les endpoints on-chain de Genesis API renvoient les données de la section Genesis OnChain : grands transferts de tokens, dépôts et retraits d’exchanges, mouvements de wallets d’équipes, positions sur DEX perpétuels, unlocks de tokens, claims et hacks, ainsi que les gros swaps sur DEX. Chaque ligne contient déjà les étiquettes de l’expéditeur et du destinataire, le montant en USD et les liens vers l’explorateur. C’est suffisant pour suivre les baleines et surveiller les flux des exchanges depuis votre propre code, sans indexeur de blockchain.
Endpoints et plans
| Endpoint | Ce qu’il renvoie | Plans de l’API |
|---|---|---|
/onchain/{section} | L’une des neuf sections Genesis OnChain | Start, Pro, Max |
/onchain | Les neuf sections dans un seul objet | Start, Pro, Max |
/onchain/dex-swaps | Gros swaps DEX | Pro, Max |
/onchain/analytics | Analytique OnChain sur 24h ou 7d | Pro, Max |
/onchain/coin/{symbol} | Synthèse sur 7 jours d’un coin | Pro, Max |
Sur Trial, tous les endpoints on-chain renvoient 403 plan_restricted. La fraîcheur est de 30 s sur Start, 10 s sur Pro et 5 s sur Max, et la même valeur arrive dans meta.freshness_sec. La clé et la première requête sont décrites dans le démarrage rapide, les quotas dans les limites de Genesis API.
Neuf sections de /onchain/{section}
section | Contenu | Bloc du tableau de bord |
|---|---|---|
large-transfers | Grands transferts de tokens | Large Transfers |
cex-flows | Dépôts vers les exchanges et retraits depuis ceux-ci | CEX Deposits / Withdrawals |
mint-bridge | Mint de tokens et transferts par bridge | Mint / Bridge |
team-wallets | Mouvements des wallets d’équipes | Team Transfers |
perp-positions | Grandes positions sur DEX perpétuels | Perp. DEX Positions |
unlocks | Unlocks de tokens | Unlocks |
claims | Claims | Claims |
coin-traffic | Série de transferts d’un coin vers une même cible | Coin Traffic |
hacks | Hacks et exploits | Hacks / Exploits |
Ce que montre chaque bloc et quels signaux chercher est expliqué dans le guide du tableau de bord Genesis OnChain, les paramètres dans la documentation. Une requête sur /onchain sans section renvoie dans data un objet : la clé est le nom de la section, la valeur ses lignes. Les filtres s’appliquent alors à toutes les sections.
| Paramètre | Type | Effet |
|---|---|---|
min_usd | number | Montant minimal de l’événement, USD |
coin | string | Lignes d’un seul coin ; hacks n’a pas de coin, la liste revient donc vide |
when | string | Pour unlocks uniquement : upcoming ou past |
section | string | Section pour une requête /onchain?section=… |
Toute autre valeur de when renvoie 400 bad_request. Ci-dessous, la section coin-traffic, un élément du tableau 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",
…
}
]
}
Champs des sections
Les sections large-transfers, cex-flows, mint-bridge, team-wallets et claims sont composées de transferts ; les autres ont leurs propres champs.
| Champs | Où | Signification |
|---|---|---|
ts, links | Toutes les sections | Heure de l’événement en secondes unix et liens prêts à l’emploi : text + url |
token / token_name | Transferts, coin-traffic | Ticker du token et nom complet |
chain / chain_name, usd / amount | Transferts | Réseau, montant en USD et en tokens |
from_* / to_* | Transferts | Expéditeur et destinataire : étiquette, adresse, lien vers l’explorateur |
tx_hash / explorer_url / arkham_url | Transferts | Hash de la transaction, liens vers l’explorateur et Arkham |
direction, target / target_address | coin-traffic | Sens deposit, withdrawal ou transfer et cible du flux |
total_usd / count / window_hours, transfers[] | coin-traffic | Total de la série, nombre de transferts, fenêtre en heures et plus gros transferts |
side / size / price / platform | perp-positions | Long ou Short, taille, prix, plateforme |
unlock_percent / unlock_value_usd / hours_left / allocations | unlocks | Part et valeur de l’unlock, heures restantes, allocations |
classification / technique / returned_funds | hacks | Classification, technique d’attaque, fonds restitués |
Swaps DEX : /onchain/dex-swaps
Plans Pro et Max. Le endpoint renvoie le flux des gros swaps, comme l’écran Aperçu DEX : chaque swap indique quelle part de la liquidité du pool il a prise, quel mouvement de prix en attendre et ce qui s’est passé après 30 secondes et 5 minutes. Le schéma de la réponse figure dans la documentation.
| Paramètre | Type | Effet |
|---|---|---|
period | string | live — les 15 dernières minutes, par défaut ; 1h, 6h, 24h ou 7d |
chain | string | Réseau |
side | string | buy ou sell |
dex | string | DEX ; séparés par des virgules pour plusieurs |
min_usd | number | Montant minimal du swap, USD |
min_impact | number | Impact absolu minimal sur le pool, % |
final | boolean | true — uniquement les swaps vérifiés |
token | string | Ticker du token |
q | string | Recherche par token, nom, adresses, trader, hash, DEX et réseau |
| Champ | Type | Signification |
|---|---|---|
id | string | Identifiant stable : réseau, transaction, token |
tier | string | Niveau selon la liquidité du pool : de T1 (30 000–100 000 $) à T4 (plus de 10 M$) |
pool_liquidity_usd / size_pct_liquidity / impact_est_pct | number ou null | Liquidité du pool, part du swap dans celle-ci et impact estimé sur le prix, % |
price_after_30s_usd / price_after_5m_usd / move_after_5m_pct | number ou null | Prix après 30 s et 5 min et mouvement du prix sur les 5 minutes suivant le swap |
facts | string | Statut de vérification : pending, publish, 30s, final ou unavailable |
trader_name / trader_address | string ou null | Étiquette et adresse du trader |
Dans l’exemple ci-dessous, un swap de 412 500 $ dans un pool de 4 120 000 $ de liquidité a pris 412 500 / 4 120 000 × 100 = 10,01 % du pool. L’impact estimé est de 4,8 % et, après 5 minutes, le prix avait bougé de 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"
}
Analytique OnChain : /onchain/analytics
Également pour Pro et Max. Un seul appel renvoie l’écran Analytique Genesis OnChain pour period=24h (par défaut) ou 7d, avec totaux, tranches horaires, flux des exchanges, unlocks, hacks, coins en vue et flux d’événements. Tous les champs sont dans la documentation.
| Champ | Type | Signification |
|---|---|---|
kpi | object | Totaux : events, usd, tokens, cex_in, cex_out, cex_net |
hourly | object | Tranches au pas de 1 h pour 24h et de 6 h pour 7d |
exchange_flows | object | Par exchange : in_usd, out_usd, net |
tokens | array | Jusqu’à 40 coins en vue avec le plus gros événement et le contexte CEX |
events | array | Flux d’événements de la période, jusqu’à 600 |
cex_net correspond aux dépôts moins les retraits : dans l’exemple, 312 456 789 − 287 654 321 = 24 802 468, soit 24,8 M$ de plus entrés sur les exchanges que sortis.
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": [ … ]
}
Coin OnChain : /onchain/coin/{symbol}
Pro et Max reçoivent aussi une synthèse sur 7 jours d’un coin, comme la page du coin : événements on-chain, swaps DEX, unlocks et contexte CEX. Le ticker se place dans le chemin, de 1 à 32 caractères, et la réponse est reconstruite au plus une fois toutes les 10 secondes. Les champs sont dans la documentation.
| Champ | Type | Signification |
|---|---|---|
cex | object ou null | Prix, OI, funding sur 8 heures, meilleur spread, réseaux, dépôt et retrait ; null si le coin n’est pas sur les CEX pris en charge |
kpi | object | Totaux sur 7 jours : événements, cex_in, cex_out, swaps, dex_buy, dex_sell |
by_section | object | Nombre d’événements par section, avec des clés comme large_tx et cex_deposits |
events / swaps | array | Événements et swaps, jusqu’à 2000 ; totaux complets dans events_total et swaps_total |
unlocks.upcoming / unlocks.past | array | Unlocks à venir et passés |
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
}
Exemple hypothétique : dépôts d’un coin vers les exchanges via cex-flows
L’objectif est de savoir quelle quantité d’un coin a été envoyée vers les exchanges au cours de la dernière heure et d’être notifié à chaque gros dépôt. Dans cex-flows, le sens se lit dans les étiquettes : un exchange dans to_name signifie un dépôt, un exchange dans from_name un retrait.
En une heure, ARB a connu quatre dépôts : 412 000 $, 260 000 $, 180 000 $ et 148 000 $, soit au total 412 000 $ + 260 000 $ + 180 000 $ + 148 000 $ = 1 000 000 $. Il y a eu un retrait de 150 000 $. Le flux net vers les exchanges est de 1 000 000 $ − 150 000 $ = 850 000 $ : il entre plus qu’il ne sort. Voici la ligne hypothétique du premier dépôt :
{
"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…"
}
Fixer le coin et le seuil
coinetmin_usdne gardent dans la réponse que les gros transferts d’un seul coin.Séparer dépôts et retraits
Un exchange dans
to_nameest un dépôt, dansfrom_nameun retrait. Comparez les étiquettes par sous-chaîne, sans tenir compte de la casse.Compter la fenêtre et les nouveaux transferts
Additionnez les lignes de la dernière heure d’après
tset ne notifiez que pour les nouvelles valeurs detx_hash.Interroger à la fraîcheur de votre plan
Faites une pause de
meta.freshness_secentre les requêtes ; sur429et503, attendezRetry-Aftersecondes.
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") # sous-chaînes des étiquettes
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 reconstruction
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")): # dépôt vers 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")): # retrait
outflow += usd
print(f"dernière heure : vers les exchanges ${inflow:,.0f}, "
f"flux net ${inflow - outflow:,.0f}")
time.sleep(body["meta"]["freshness_sec"])
Le script se contente de lire les données et d’afficher des notifications ; que faire du coin reste votre décision. Les séries de petits transferts vers un même exchange sont regroupées dans la section coin-traffic, où le sens figure déjà dans le champ direction. Les totaux tous coins confondus viennent de /onchain/analytics dans kpi.cex_in, kpi.cex_out et kpi.cex_net, et un aperçu des usages des données on-chain se trouve dans l’article sur l’API de données on-chain.
Questions et réponses
De quel plan ai-je besoin pour les données on-chain ?
Les neuf sections /onchain/{section} sont ouvertes sur Start, Pro et Max. Les swaps DEX, l’analytique et la synthèse d’un coin sont réservés à Pro et Max, et sur Trial les endpoints on-chain renvoient 403 plan_restricted.
Existe-t-il un historique au-delà de 7 jours ?
Les fenêtres les plus longues sont period=7d pour les swaps et l’analytique et 7 jours dans la synthèse d’un coin ; Genesis API n’a pas d’archive séparée. Pour un long historique, conservez vous-même les enregistrements à chaque interrogation.
Pourquoi un swap a-t-il disparu de la réponse ?
La vérification a révélé un réaménagement de liquidité plutôt qu’une transaction, et l’enregistrement a été supprimé. Rapprochez les swaps conservés par id ou demandez uniquement final=true.
Comment obtenir les prochains unlocks de tokens ?
Demandez /onchain/unlocks?when=upcoming. Chaque ligne contient unlock_percent et unlock_value_usd, la part et la valeur de l’unlock, et hours_left, les heures restantes. min_usd fixe un seuil de valeur, coin choisit un coin.