Genesis Arbitrage

Genesis Arbitrage · · 16 min de lecture

API de données on-chain : transferts de baleines, flux des exchanges et unlocks de tokens

En bref

  • Une API de données on-chain renvoie des événements de la blockchain déjà décodés : quel token a bougé, de qui, vers qui et pour combien de dollars. Les données brutes viennent des nœuds, les indexeurs les transforment en tables, et les étiquettes d’adresses restent une attribution qui peut être fausse.
  • Les traders surveillent les dépôts et retraits sur les exchanges, les gros transferts, les mouvements des portefeuilles d’équipe, les positions sur les DEX de perpétuels, les unlocks, les claims, les hacks et les gros swaps sur DEX. Un dépôt sur un exchange ne se termine pas toujours par une vente.
  • Dans Genesis API, les neuf sections on-chain sont disponibles dès le plan Start, tandis que les swaps DEX, l’analytique et la fiche de la monnaie demandent Pro ou Max. Votre code calcule la fenêtre et les totaux de flux, car les sections n’ont pas de paramètre de temps.

Une API de données on-chain est une interface HTTP vers des événements de la blockchain déjà collectés, convertis en dollars et étiquetés : quel token a bougé, de quelle adresse, vers quelle adresse et dans quelle transaction. Avec une telle API, vous pouvez suivre les transferts de baleines, les entrées sur les exchanges, les unlocks de tokens et les gros swaps sur un DEX sans faire tourner votre propre nœud ni indexeur. Une baleine désigne ici une adresse qui détient assez d’une monnaie pour que ses transferts puissent faire bouger le marché.

D’où viennent les données on-chain

Les données passent par trois couches : un nœud stocke les blocs, un indexeur les transforme en lignes d’événements et une base d’étiquettes nomme les adresses.

Nœud : blocs et logs

Un nœud de blockchain stocke les blocs et les sert via JSON-RPC. Sur Ethereum et les chaînes compatibles, un transfert de token ERC-20 est écrit dans le journal de la transaction sous la forme de l’événement Transfer(address indexed _from, address indexed _to, uint256 _value), et la norme recommande d’émettre le même événement avec 0x0 comme expéditeur lorsque de nouveaux tokens sont créés (EIP-20).

La méthode eth_getLogs renvoie les logs qui correspondent à un filtre : une plage de blocs fromBlock et toBlock, une address de contrat et les topics de l’événement (Ethereum JSON-RPC). Un log contient des adresses, le numéro du bloc, le hash de la transaction et le montant dans les plus petites unités du token. Le bloc n’a ni prix en dollars, ni nom de propriétaire, ni indicateur d’exchange.

Indexeur : des logs aux tables

Un indexeur lit les blocs dans l’ordre, décode les événements et les range dans des tables : transferts, swaps, changements de pools. Il divise le montant par 10 puissance les decimals du token (avec huit décimales, cela revient à diviser par 100 000 000) et le multiplie par le prix au moment du bloc, ce qui donne la valeur en dollars.

Viennent ensuite les seuils : le flux conserve les transferts au-dessus d’un montant fixé, et les séries de petits transferts vers une même adresse sont fusionnées en une seule ligne. Faire tourner un tel pipeline pour plusieurs chaînes est un projet à part entière, et une API de données on-chain renvoie son résultat en une seule requête.

Étiquettes d’adresses : qui se cache derrière une adresse

Une étiquette est un nom attaché à une adresse : « Binance », « trésorerie du projet », « market maker ». Elle est attribuée à partir d’indices : l’adresse transfère des fonds vers un portefeuille connu d’un exchange, le projet a publié lui-même ses adresses, l’adresse a reçu des tokens d’un contrat de vesting. Le propriétaire ne confirme rien de tout cela, donc une étiquette peut être périmée ou tout simplement fausse.

Une adresse sans indices reste sans nom : dans les exemples de la documentation de Genesis API, un tel expéditeur apparaît sous forme d’adresse abrégée, 0xec01…d1a5.

Quels événements on-chain comptent pour les traders

Un exemple hypothétique : en une matinée, 2 000 000 $ de la monnaie d’un projet sont allés vers des exchanges, et 500 000 $ ont quitté le portefeuille de l’équipe vers l’adresse d’un market maker. Chaque événement pris seul dit peu de chose ; ensemble, ils sont une raison de vérifier le prix, l’open interest et le calendrier des unlocks.

ÉvénementCe que l’on voitComment on le lit habituellement
Dépôt sur un exchangeLes coins arrivent à une adresse d’exchangeVente possible, collatéral ou simple réorganisation
Retrait d’un exchangeLes coins partent vers une adresse externeConservation, DeFi ou autre exchange
Gros transfertUn transfert au-dessus du seuil entre adressesUne baleine déplace sa position
Portefeuille d’équipeMouvements depuis des adresses de la fondation, de la trésorerie ou des fondateursUn dépôt sur un exchange pèse plus qu’un mouvement interne
Position sur DEX de perpétuelsLong ou short : taille, prix, plateformeLe pari d’une baleine et le risque de liquidation
UnlockDate, part et valeur de la libérationNouvelle offre de la monnaie
ClaimTokens d’un airdrop, d’un vesting, de récompensesLes destinataires peuvent vendre tout de suite
Mint et bridgeÉmission de tokens, transferts entre chaînesLe mint de stablecoins signifie un afflux d’argent
HackProtocole, pertes, technique d’attaqueRisque pour le token et les chaînes liées
Swap sur DEXSens, montant, part du pool, mouvement du prixLe prix bouge avant que les exchanges ne réagissent

Les positions sur les exchanges décentralisés de contrats perpétuels, les DEX de perpétuels, sont visibles parce que ces plateformes gardent leurs données ouvertes. Sur Hyperliquid, l’endpoint info POST https://api.hyperliquid.xyz/info avec une requête clearinghouseState renvoie les positions ouvertes et la marge de n’importe quelle adresse, sans clé (documentation Hyperliquid). Les CEX ne publient pas les positions des autres traders ; ils donnent des chiffres agrégés comme l’open interest.

Un unlock est la libération de tokens de l’équipe, d’investisseurs ou de la fondation selon un calendrier de vesting, qui les distribue par tranches à des dates fixées. La date est connue à l’avance, donc le marché peut intégrer la vente dans les prix avant l’événement.

Un swap sur un DEX déplace le prix du pool dans le même bloc. Un exemple hypothétique : un achat de 150 000 $ dans un pool de 1 200 000 $ de liquidité représente 150 000 / 1 200 000 × 100 = 12,5 % du pool. Le prix du pool bouge nettement, alors que sur les exchanges le mouvement apparaît plus tard, voire pas du tout. Les prix DEX et CEX sont comparés dans l’article sur l’API DEX.

Un hack apparaît on-chain sous forme de transferts sortants depuis le contrat d’un protocole. Les bridges sont attaqués plus souvent que d’autres protocoles parce que leurs contrats détiennent de grosses sommes : les cas notables sont dans l’article sur les ponts blockchain, et un vol sur un exchange dans l’analyse du hack de Bybit.

Latence et confirmation

Quelques secondes à quelques minutes s’écoulent entre une transaction et une ligne dans votre code ; c’est la latence des données. Elle compte peu pour un aperçu quotidien des flux, mais elle décide du résultat quand vous réagissez à un gros dépôt ou à un gros swap.

Confirmation du réseau

Sur Ethereum, un nouveau bloc peut apparaître à chaque slot, toutes les 12 secondes, et il devient final au bout d’environ 15 minutes (ethereum.org). Un bloc finalisé ne peut pas être modifié sans perdre une quantité colossale d’ETH. Un indexeur qui n’a besoin que de l’image consolidée peut lire les blocs jusqu’à la balise finalized, nom que donne un nœud au dernier bloc finalisé.

Un exchange crédite un dépôt quand la transaction atteint un nombre minimal de confirmations réseau, et chez Binance, par exemple, ce minimum diffère selon la monnaie (FAQ Binance). Un dépôt sur un exchange est donc visible on-chain avant que le propriétaire puisse vendre ces coins.

Délai des données

Dans l’exemple de swap de la documentation de Genesis API, ts = 1794675511 est l’heure du swap et published_at = 1794675523 l’heure de publication : 1794675523 − 1794675511 = 12 secondes d’écart. S’y ajoutent la fraîcheur des données de votre plan dans meta.freshness_sec (30 secondes sur Start, 10 sur Pro, 5 sur Max) et votre intervalle de polling.

ÉtapeDuréeCe que cela signifie
Bloc Ethereumslot de 12 sLa transaction est visible mais pas finale
Finalité Ethereumenviron 15 minLe bloc ne changera plus
Crédit par l’exchangele minimum de confirmations de l’exchangeDifférent selon la monnaie
Publication du swap12 s dans l’exempleL’enregistrement n’est pas encore final
Statut finalpas avant 5 min après le swapLe prix à 30 s et à 5 min est connu
Livraison par Genesis API30, 10 ou 5 sPlans Start, Pro et Max

Pour les swaps, le flux period=live avec des enregistrements non vérifiés est plus rapide, mais un enregistrement peut disparaître si le swap s’avère être une réorganisation de liquidité. Le paramètre final=true ne garde que les swaps vérifiés, qui arrivent au moins 5 minutes plus tard.

Données on-chain dans Genesis API

Genesis API renvoie les flux de la section Genesis OnChain : les lignes de transferts portent déjà les étiquettes de l’expéditeur et du destinataire, le montant en dollars et en tokens, le hash de la transaction et un lien vers l’explorateur. Les requêtes sont des HTTP GET avec la clé dans l’en-tête X-API-Key, et la réponse est du JSON avec un champ data et un bloc meta.

EndpointCe qu’il renvoiePlans
/onchain/{section}Une des 9 sections on-chainStart, Pro, Max
/onchainLes 9 sections dans un seul objetStart, Pro, Max
/onchain/dex-swapsGros swaps sur DEXPro, Max
/onchain/analyticsTotaux sur 24h ou 7dPro, Max
/onchain/coin/{symbol}Une fiche de 7 jours d’une monnaiePro, Max

Les sections portent le nom des flux : large-transfers, cex-flows, mint-bridge, team-wallets, perp-positions, unlocks, claims, hacks et coin-traffic, qui contient des séries de transferts d’une monnaie vers une même cible. Les filtres sont min_usd et coin, plus when avec upcoming ou past pour les unlocks. Il n’y a pas de paramètre de temps, donc la fenêtre se calcule à partir du champ ts.

Une requête pour les prochains unlocks de tokens de plus 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"

Une ligne d’unlock contient unlock_percent et unlock_value_usd (part et valeur), hours_left (heures avant l’événement) et allocations (répartition par destinataire).

Pro et Max ajoutent trois endpoints. /onchain/dex-swaps renvoie les gros swaps avec la part de liquidité du pool, l’impact estimé sur le prix et le mouvement du prix après 30 secondes et 5 minutes (aperçu DEX dans la documentation). /onchain/analytics calcule les totaux sur 24h ou 7d : kpi.cex_in, kpi.cex_out, kpi.cex_net et les flux par exchange (analytique OnChain). /onchain/coin/{symbol} rassemble les événements, swaps et unlocks d’une monnaie sur 7 jours avec son prix CEX, son OI et son funding (monnaie OnChain).

Seule une réponse 200 consomme du quota, et sur Trial les endpoints on-chain renvoient 403 plan_restricted. Start coûte 50 $ par mois pour 2 M d’appels, Pro 100 $ pour 5 M, Max 200 $ pour 10 M (tarifs de Genesis API). Chaque paramètre et chaque champ, avec des exemples de réponse, se trouve dans le guide des endpoints on-chain.

Sans code, les mêmes flux sont sur le tableau de bord Genesis OnChain, les swaps dans l’aperçu DEX, et les totaux quotidiens et hebdomadaires dans l’analytique OnChain.

Python : dépôts d’une monnaie sur les exchanges sur une fenêtre

Un exemple hypothétique : en 6 heures, cinq transferts d’ARB sont arrivés sur des exchanges, pour 640 000 $, 520 000 $, 410 000 $, 330 000 $ et 150 000 $. Le total est 640 000 + 520 000 + 410 000 + 330 000 + 150 000 = 2 050 000, donc le seuil de 2 000 000 $ est franchi. Dès que le premier transfert a plus de 6 heures, il sort de la fenêtre : 2 050 000 − 640 000 = 1 410 000, et le total repasse sous le seuil.

cex-flows n’a pas de champ direction, donc le sens se déduit des étiquettes : un exchange dans to_name est un dépôt, un exchange dans from_name est un retrait. La réponse est le flux courant de la section, donc le script conserve les dépôts par tx_hash et supprime lui-même les anciens. Ainsi, le total de la fenêtre n’est pas compté deux fois d’un polling à l’autre.

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        # fenêtre, secondes
ALERT_USD = 2_000_000    # total de dépôts qui déclenche une alerte
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):  # rate limit ou reconstruction
        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}: vers les exchanges en 6 h ${total:,.0f}, "
          f"transferts {len(deposits)}")
    if total >= ALERT_USD and not alerted:
        print("Seuil franchi : vérifiez le prix, l’OI et le funding")
    alerted = total >= ALERT_USD
    time.sleep(body["meta"]["freshness_sec"])

Le tuple CEX contient des sous-chaînes d’étiquettes ; ajoutez les exchanges où la monnaie se négocie. Le script se contente de compter et d’afficher : Genesis API ne passe aucun ordre, et la décision de trader reste la vôtre.

Une réponse à une requête avec coin et min_usd arrive sans ETag, donc chaque polling consomme un appel. Sur Start, la pause est de 30 secondes, soit 2 592 000 / 30 = 86 400 appels sur 30 jours, ou 4,32 % du quota de 2 M. Pour une douzaine de monnaies, récupérez le flux /onchain/cex-flows sans filtres et triez-le vous-même : l’ensemble complet arrive avec un ETag, et une répétition avec If-None-Match sur des données inchangées renvoie 304 sans consommer de quota.

Les transferts inférieurs à min_usd ne seront pas comptés : les séries de petits transferts d’une monnaie vers un exchange sont regroupées dans coin-traffic, avec les champs direction, total_usd, count et window_hours.

Comment lire un dépôt sur un exchange

Les mêmes 2 050 000 $ d’ARB arrivés sur des exchanges en 6 heures pourraient être la préparation d’une vente, un collatéral pour des futures ou un mouvement entre des comptes du même propriétaire. Une ligne du flux ne dira pas laquelle de ces hypothèses est la bonne.

ScénarioCe que l’on voit d’autreComment vérifier
Préparation d’une venteVentes sur DEX, le prix faiblit/onchain/dex-swaps avec side=sell
Collatéral pour des futuresL’open interest augmente, le funding change/market/open-interest, /funding/rates
Réorganisation interneUn retrait correspondant du même exchangefrom_name dans cex-flows, l’explorateur
Vente de l’équipe ou d’un fondsL’expéditeur est un portefeuille d’équipeteam-wallets, unlocks

Plusieurs événements sur une même monnaie pèsent plus qu’un seul : un dépôt sur un exchange, un transfert depuis le portefeuille de l’équipe et un unlock à venir. Vous pouvez les voir dans une seule réponse de /onchain/coin/{symbol}, où les événements sont à côté du bloc cex avec oi_usd et funding_8h. Les endpoints /market/open-interest et /funding/rates du tableau sont disponibles dès Trial.

Les autres données de marché et la façon de choisir une source selon la tâche sont présentées dans l’aperçu de l’API crypto.

Questions et réponses

Quelle est la fiabilité des étiquettes d’adresses dans les données on-chain ?

Les étiquettes sont attribuées à partir d’indices et le propriétaire de l’adresse ne les confirme pas, donc une exactitude totale est impossible. Plus il y a de transferts reliant une adresse à un portefeuille connu, plus la conclusion est fiable, et les nouvelles adresses restent plus souvent sans nom. Vérifiez tout gros événement via le lien de l’explorateur.

Genesis API propose-t-elle un historique on-chain ?

Il n’y a pas d’archive profonde. Les fenêtres les plus longues sont de 7 jours : period=7d pour les swaps et l’analytique et la fiche de monnaie sur 7 jours, tandis que les unlocks passés viennent de when=past. Construisez vous-même un long historique en enregistrant les données à chaque polling par tx_hash ou id.

Que signifient les statuts pending et final pour les swaps DEX ?

C’est le champ facts, le statut de vérification de l’enregistrement. pending signifie que le swap est publié et que le prix après le swap est encore attendu ; publish et 30s sont des étapes intermédiaires ; final signifie que l’enregistrement est vérifié et que le prix à 30 secondes et à 5 minutes est connu ; unavailable signifie que les facts n’ont pas pu être collectés. Tant que le statut n’est pas final, un enregistrement peut disparaître, donc stockez les swaps par id ou demandez final=true.

Peut-on suivre les baleines avec une API gratuitement ?

Vous pouvez prendre les données brutes sur votre propre nœud ou sur un endpoint public via JSON-RPC, mais les étiquettes, les montants en dollars et les seuils sont alors à construire vous-même. Genesis API n’a pas de plan gratuit : les sections on-chain commencent avec le plan Start à 50 $ par mois, les swaps DEX et l’analytique avec Pro à 100 $.