Genesis Arbitrage

Genesis Arbitrage · · 13 min de lecture

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

EndpointCe qu’il renvoiePlans de l’API
/onchain/{section}L’une des neuf sections Genesis OnChainStart, Pro, Max
/onchainLes neuf sections dans un seul objetStart, Pro, Max
/onchain/dex-swapsGros swaps DEXPro, Max
/onchain/analyticsAnalytique OnChain sur 24h ou 7dPro, Max
/onchain/coin/{symbol}Synthèse sur 7 jours d’un coinPro, 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}

sectionContenuBloc du tableau de bord
large-transfersGrands transferts de tokensLarge Transfers
cex-flowsDépôts vers les exchanges et retraits depuis ceux-ciCEX Deposits / Withdrawals
mint-bridgeMint de tokens et transferts par bridgeMint / Bridge
team-walletsMouvements des wallets d’équipesTeam Transfers
perp-positionsGrandes positions sur DEX perpétuelsPerp. DEX Positions
unlocksUnlocks de tokensUnlocks
claimsClaimsClaims
coin-trafficSérie de transferts d’un coin vers une même cibleCoin Traffic
hacksHacks et exploitsHacks / 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ètreTypeEffet
min_usdnumberMontant minimal de l’événement, USD
coinstringLignes d’un seul coin ; hacks n’a pas de coin, la liste revient donc vide
whenstringPour unlocks uniquement : upcoming ou past
sectionstringSection 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.

ChampsOùSignification
ts, linksToutes les sectionsHeure de l’événement en secondes unix et liens prêts à l’emploi : text + url
token / token_nameTransferts, coin-trafficTicker du token et nom complet
chain / chain_name, usd / amountTransfertsRéseau, montant en USD et en tokens
from_* / to_*TransfertsExpéditeur et destinataire : étiquette, adresse, lien vers l’explorateur
tx_hash / explorer_url / arkham_urlTransfertsHash de la transaction, liens vers l’explorateur et Arkham
direction, target / target_addresscoin-trafficSens deposit, withdrawal ou transfer et cible du flux
total_usd / count / window_hours, transfers[]coin-trafficTotal de la série, nombre de transferts, fenêtre en heures et plus gros transferts
side / size / price / platformperp-positionsLong ou Short, taille, prix, plateforme
unlock_percent / unlock_value_usd / hours_left / allocationsunlocksPart et valeur de l’unlock, heures restantes, allocations
classification / technique / returned_fundshacksClassification, 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ètreTypeEffet
periodstringlive — les 15 dernières minutes, par défaut ; 1h, 6h, 24h ou 7d
chainstringRéseau
sidestringbuy ou sell
dexstringDEX ; séparés par des virgules pour plusieurs
min_usdnumberMontant minimal du swap, USD
min_impactnumberImpact absolu minimal sur le pool, %
finalbooleantrue — uniquement les swaps vérifiés
tokenstringTicker du token
qstringRecherche par token, nom, adresses, trader, hash, DEX et réseau
ChampTypeSignification
idstringIdentifiant stable : réseau, transaction, token
tierstringNiveau selon la liquidité du pool : de T1 (30 000–100 000 $) à T4 (plus de 10 M$)
pool_liquidity_usd / size_pct_liquidity / impact_est_pctnumber ou nullLiquidité 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_pctnumber ou nullPrix après 30 s et 5 min et mouvement du prix sur les 5 minutes suivant le swap
factsstringStatut de vérification : pending, publish, 30s, final ou unavailable
trader_name / trader_addressstring 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.

ChampTypeSignification
kpiobjectTotaux : events, usd, tokens, cex_in, cex_out, cex_net
hourlyobjectTranches au pas de 1 h pour 24h et de 6 h pour 7d
exchange_flowsobjectPar exchange : in_usd, out_usd, net
tokensarrayJusqu’à 40 coins en vue avec le plus gros événement et le contexte CEX
eventsarrayFlux 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.

ChampTypeSignification
cexobject ou nullPrix, 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
kpiobjectTotaux sur 7 jours : événements, cex_in, cex_out, swaps, dex_buy, dex_sell
by_sectionobjectNombre d’événements par section, avec des clés comme large_tx et cex_deposits
events / swapsarrayÉvénements et swaps, jusqu’à 2000 ; totaux complets dans events_total et swaps_total
unlocks.upcoming / unlocks.pastarrayUnlocks à 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…"
}
  1. Fixer le coin et le seuil

    coin et min_usd ne gardent dans la réponse que les gros transferts d’un seul coin.

  2. Séparer dépôts et retraits

    Un exchange dans to_name est un dépôt, dans from_name un retrait. Comparez les étiquettes par sous-chaîne, sans tenir compte de la casse.

  3. Compter la fenêtre et les nouveaux transferts

    Additionnez les lignes de la dernière heure d’après ts et ne notifiez que pour les nouvelles valeurs de tx_hash.

  4. Interroger à la fraîcheur de votre plan

    Faites une pause de meta.freshness_sec entre les requêtes ; sur 429 et 503, attendez Retry-After secondes.

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.