Genesis Arbitrage

Genesis Arbitrage · · 15 min de lecture

Un moniteur de spreads et de funding en Python

En bref

  • Le moniteur est un programme console : toutes les meta.freshness_sec secondes, il récupère les jeux complets /arbitrage/spot-spot et /funding/spread, filtre les lignes selon des seuils, affiche des tableaux et les ajoute à un fichier CSV.
  • Les deux jeux de données sont demandés sans filtres, ils arrivent donc avec un ETag : une requête répétée avec If-None-Match avant le prochain instantané renvoie 304 sans consommer de quota. Sur 429 et 503, le client attend Retry-After secondes.
  • Ce qui reste après des frais taker supposés de 0,1 % par jambe, c’est le spread moins 0,2 point de pourcentage. Sur Pro et Max, le moniteur revérifie les trois meilleures paires sur 1 000 $ de carnet d’ordres.
  • Le plafond est de 86 400 appels par 30 jours sur Trial, soit 17,28 % du quota, et de 1 296 000 sur Pro avec vérifications de carnet, soit 25,92 %.

Un moniteur de spreads et de funding est un programme qui récupère en boucle les spreads entre exchanges et les spreads de funding, garde les lignes au-dessus de vos seuils et les affiche sous forme de tableau dans la console. Le moniteur de cette leçon fait environ 170 lignes de Python : ses données viennent de Genesis API, son historique va dans un fichier CSV et il n’ouvre aucune position. Il n’envoie pas non plus d’alertes ; le bot avec messages Telegram est présenté dans Bot d’arbitrage crypto en Python.

Plan d’interrogation : endpoints, fréquence et consommation d’appels

RequêteCe qu’elle renvoieQuand
/account/usagePlan, freshness_sec, rps_limitAu démarrage, ne consomme pas de quota
/arbitrage/spot-spotPaires Spot – SpotÀ chaque passe, jeu complet
/funding/spreadMeilleures paires d’exchanges par fundingÀ chaque passe, jeu complet
/orderbooks/spreads/spot-spotΔ des carnets pour 1 000 $Pro et Max, trois paires par passe

meta.freshness_sec fixe la fréquence : votre plan reçoit un nouvel instantané toutes les 60 secondes sur Trial, 30 sur Start, 10 sur Pro et 5 sur Max. Un polling plus rapide renvoie le même instantané avec le même meta.updated_at. Les champs des deux jeux de données figurent dans la documentation Spot — Spot et Spread de funding.

Plan et quotaPauseRequêtes par passeAppels par 30 jours
Trial, 500K60 s286 400
Start, 2M30 s2172 800
Pro, 5M10 s51 296 000
Max, 10M5 s52 592 000

Sur Trial : 2 × 86 400 / 60 × 30 = 86 400 appels, soit 17,28 % du quota. Sur Pro, trois vérifications de carnet s’ajoutent aux deux jeux de données : 5 × 86 400 / 10 × 30 = 1 296 000 appels, soit 25,92 % de 5M. Les règles du quota se trouvent dans le guide des limites de Genesis API.

Le moniteur respecte la limite de requêtes par seconde avec une pause de 1,1 / rps_limit seconde entre les requêtes : 1,1 seconde sur Trial et 0,22 sur Pro. Une passe de cinq requêtes sur Pro dure environ une seconde.

Réglages et client avec ETag et Retry-After

Les sept blocs de code de cette leçon forment le fichier monitor.py complet : enregistrez-les l’un après l’autre dans un seul fichier. Les seuils des réglages sont donnés à titre d’exemple ; adaptez-les à vos frais et à vos tailles.

import csv
import os
import time
from datetime import datetime, timezone

import requests

API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0     # spread de la ligne à partir de 1 %
MIN_VOLUME = 50_000  # volume 24 h sur les deux exchanges à partir de 50 000 $
MIN_FUNDING = 0.05   # spread de funding à partir de 0,05 %
FEE = 0.1            # frais taker supposés par jambe, %
TOP = 10             # lignes dans chaque tableau
BOOK_TOP = 3         # paires vérifiées sur les carnets par passe, Pro/Max
BOOK_USD = 1000      # taille de la vérification du carnet, USD
CSV_FILE = "monitor.csv"

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}                # requête -> (ETag, corps de la réponse)
stats = {200: 0, 304: 0}  # nombre de réponses 200 et 304 reçues
pace = {"gap": 1.1, "last": 0.0}  # pause entre les requêtes, s

La clé vient de la variable d’environnement GENESIS_API_KEY et se place dans l’en-tête X-API-Key de chaque requête, jamais dans l’URL. cache conserve l’ETag et le corps de la dernière réponse à chaque requête, stats compte les réponses 200 et 304, et pace retient l’instant où la dernière requête est partie.

def get(path, params=None):
    """GET vers Genesis API : cadence, ETag et nouvelles tentatives via Retry-After."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # une requête et jusqu’à trois nouvelles tentatives
        wait = pace["last"] + pace["gap"] - time.monotonic()
        if wait > 0:
            time.sleep(wait)  # au plus rps_limit requêtes par seconde
        pace["last"] = time.monotonic()
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = api.get(API + path, params=params, headers=hdr,
                    timeout=15)
        if r.status_code == 304:  # l’instantané n’a pas changé
            stats[304] += 1
            return cache[key][1]
        if r.status_code in (429, 503):
            wait = int(r.headers.get("Retry-After", "5"))
            if wait > 60:  # voilà à quoi ressemble un quota épuisé
                raise SystemExit(f"Quota épuisé : attendez {wait} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403 : réessayer n’aidera pas
        stats[200] += 1
        body = r.json()
        if "ETag" in r.headers:  # seuls les jeux de données complets en portent un
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("API occupée, nouvelle tentative à la passe suivante")

Un ETag est une étiquette de version de l’instantané. get le renvoie dans l’en-tête If-None-Match et, tant que l’instantané ne change pas, le serveur répond 304 sans corps : aucun quota n’est consommé et la fonction renvoie le corps précédent. Sur 429 et 503, elle attend Retry-After secondes et réessaie ; une pause de plus d’une minute signifie que le quota de la période est épuisé, et le moniteur s’arrête. Les codes d’erreur et les règles de nouvelle tentative figurent dans le guide des réponses et erreurs de Genesis API.

Spreads et funding : chargement, seuils et tri

def spot_rows():
    """Paires Spot – Spot au-dessus des seuils, coin transférable."""
    body = get("/arbitrage/spot-spot")  # sans filtres : avec ETag
    rows = []
    for x in body["data"]:
        vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
        if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
                and x["withdraw_enabled_buy"]
                and x["deposit_enabled_sell"]):
            rows.append({**x, "net": net(x["spread_pct"])})
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]


def funding_rows():
    """Coins avec le plus grand spread de funding."""
    body = get("/funding/spread")  # sans filtres : avec ETag
    rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]

Les deux jeux de données sont demandés sans paramètres : la réponse à une requête avec min_spread, coin ou un autre filtre est construite pour cette requête et arrive sans ETag. Le moniteur applique lui-même les seuils : un spread d’au moins MIN_SPREAD, un volume sur 24 h d’au moins MIN_VOLUME sur les deux exchanges, les retraits ouverts sur l’exchange d’achat et les dépôts ouverts sur l’exchange de vente. Un volume null compte pour zéro, cette ligne ne passe donc pas.

Les lignes sont triées par spread_pct décroissant et les TOP premières vont dans le tableau. Dans /funding/spread, le seuil MIN_FUNDING est comparé au spread_pct de la meilleure paire.

Ce qui reste après les frais et la vérification du carnet d’ordres

def net(spread_pct):
    """Ce qui reste après deux frais taker, environ, %."""
    return round(spread_pct - 2 * FEE, 4)


def book_net(row):
    """Ce qui reste après BOOK_USD de carnet et les frais. Pro et Max."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": BOOK_USD})
    pair = (row["exchange_buy"], row["exchange_sell"])
    for x in body["data"]:
        if (x["exchange_buy"], x["exchange_sell"]) != pair:
            continue
        od = x["order_delta"]
        if od["status"] != "ok":
            return od["status"]  # no_book ou exhausted
        return net(od["spread_pct"])
    return "gone"  # la paire a quitté le jeu de données

Des frais taker supposés de 0,1 % à l’achat et de 0,1 % à la vente réduisent le spread d’environ 0,2 point de pourcentage : une paire à 1,62 % laisse 1,62 − 2 × 0,1 = 1,42 %. Mettez dans FEE les frais de vos exchanges (maker et taker). Les frais de retrait ne figurent pas dans les réponses de l’API et le moniteur n’en tient pas compte.

Sur Pro et Max, book_net revérifie les trois meilleures paires sur les carnets d’ordres : /orderbooks/spreads/spot-spot avec le coin de la paire et volume=1000 renvoie les lignes de ce coin avec un objet order_delta, et la fonction prend la ligne avec la même paire d’exchanges (Δ des carnets). S’il n’y a pas de carnet ou s’il est épuisé, vous obtenez le statut no_book ou exhausted au lieu d’un nombre. Une requête avec coin n’a pas d’ETag et coûte toujours un appel, c’est pourquoi une passe n’en fait que trois, fixés par BOOK_TOP.

Le tableau de la console

def show(spot, s_meta, fund, f_meta):
    now = time.time()
    s_age = now - s_meta["updated_at"]
    f_age = now - f_meta["updated_at"]
    print(f"\nSpot – Spot, âge de l’instantané {s_age:.0f} s")
    print(f"{'Coin':<8}{'Achat → vente':<20}"
          f"{'Spread':>7}{'-frais':>9}{'Carnet':>11}")
    for x in spot:
        pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
        book = x.get("book", "—")
        if isinstance(book, float):
            book = f"{book:.2f}"
        print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
              f'{x["net"]:>9.2f}{book:>11}')
    print(f"\nFunding, âge de l’instantané {f_age:.0f} s")
    for x in fund:
        b = x["best"]
        legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
                f'{b["exchange_2"]} {b["interval_2"] or "?"}')
        print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
    print(f"Réponses 200 : {stats[200]}, 304 : {stats[304]}")

Le premier tableau affiche le coin, la paire d’exchanges, spread_pct, ce qui reste après les frais et ce qui reste après le carnet ; un tiret signifie que le carnet n’a pas été vérifié. Le second affiche la meilleure paire d’exchanges par funding, avec les intervalles de funding et spread_pct. Au-dessus des tableaux figure l’âge de l’instantané, soit l’heure actuelle moins meta.updated_at, et en dessous le nombre de réponses 200 et 304 depuis le démarrage.

Historique CSV

def save(spot, fund):
    """Ajoute la passe au CSV : heure, jeu de données, paire, spreads."""
    new = not os.path.exists(CSV_FILE)
    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
    with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        if new:
            w.writerow(["time_utc", "dataset", "coin", "leg_1",
                        "leg_2", "spread_pct", "net_pct", "book"])
        for x in spot:
            w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
                        x["exchange_sell"], x["spread_pct"], x["net"],
                        x.get("book")])  # None devient une cellule vide
        for x in fund:
            b = x["best"]
            w.writerow([ts, "funding", x["coin"], b["exchange_1"],
                        b["exchange_2"], x["spread_pct"], None, None])

Le tableau de la console dure jusqu’à la passe suivante, tandis que monitor.csv conserve chaque passe : il montre combien de temps une paire dure et à quelles heures elle apparaît. Le module csv fait partie de la bibliothèque standard de Python. Ouvrez le fichier avec newline="", comme l’exige la documentation du module ; sinon, sur les systèmes qui utilisent les fins de ligne \r\n, un \r en trop se retrouve dans le fichier.

La colonne book contient ce qui reste après le carnet, en pourcentage, ou le statut exhausted ou no_book. Le module écrit None comme une cellule vide, la colonne reste donc vide pour les lignes de funding et les paires non vérifiées. Les heures sont en UTC.

La boucle principale

def main():
    usage = get("/account/usage")["data"]  # ne consomme pas de quota
    books = usage["plan"] in ("pro", "max")
    pace["gap"] = 1.1 / usage["rps_limit"]
    print("Plan", usage["plan"], "| instantané toutes les",
          usage["freshness_sec"], "s | carnets d’ordres :",
          "oui" if books else "non")
    pause = usage["freshness_sec"]
    while True:
        try:
            spot, s_meta = spot_rows()
            fund, f_meta = funding_rows()
            if books:
                for x in spot[:BOOK_TOP]:
                    x["book"] = book_net(x)
            show(spot, s_meta, fund, f_meta)
            save(spot, fund)
            pause = s_meta.get("freshness_sec", pause)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # clé, plan ou paramètres : réessayer n’aidera pas
            print("Erreur du serveur, nouvelle tentative :", e)
        except (requests.RequestException, RuntimeError) as e:
            print("Pas de réponse, nouvelle tentative :", e)
        time.sleep(pause)  # plus vite que freshness_sec = le même instantané


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nMoniteur arrêté, l’historique est dans", CSV_FILE)

Au démarrage, le moniteur appelle /account/usage : la requête ne consomme pas de quota et renvoie le plan, freshness_sec et rps_limit (Utilisation). Le plan indique au moniteur s’il faut vérifier les carnets d’ordres, et rps_limit fixe la pause entre les requêtes. Le moniteur encaisse les pannes réseau et les erreurs 5xx jusqu’à la passe suivante, tandis que les erreurs 4xx (clé erronée, abonnement expiré, plan sans l’endpoint) l’arrêtent.

Lancer le moniteur et lire la sortie

python3 --version   # Python 3.10 ou plus récent est requis
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py

Sortie sur le plan Pro, exemple illustratif :

Plan pro | instantané toutes les 10 s | carnets d’ordres : oui

Spot – Spot, âge de l’instantané 4 s
Coin    Achat → vente        Spread   -frais     Carnet
KLM     ByBit → Gate           1.62     1.42       0.86
XYZ     MEXC → Gate            1.24     1.04  exhausted
ABC     BingX → HTX            1.12     0.92       0.31
QRS     Gate → OKX             1.05     0.85          —

Funding, âge de l’instantané 4 s
XYZ     MEXC 4h / Bitget 8h          0.0600 %
ABC     Hyper 1h / CoinEx 8h         0.0500 %
Réponses 200 : 6, 304 : 0

KLM : le spread de la ligne est de 1,62 %, de 1,42 % après deux frais et de 0,86 % après 1 000 $ de carnet d’ordres plus les frais. XYZ a épuisé le carnet à 1 000 $ : pour une telle paire, on réduit la taille ou on l’écarte. QRS est la quatrième ligne, son carnet n’a donc pas été demandé. Le tableau de funding montre la fréquence de règlement de chaque exchange : Hyper (le nom d’Hyperliquid dans les réponses) toutes les heures et CoinEx toutes les 8 heures. Appuyez sur Ctrl+C pour arrêter le moniteur.

Parmi les quatre vérifications d’une paire de la leçon 3, le moniteur effectue lui-même l’écart de prix et le transfert, le carnet d’ordres sur Pro et Max, et affiche la fraîcheur au-dessus du tableau. Vous vérifiez le contrat et les frais de retrait.

Pratique

  1. Lancez le moniteur

    La première ligne de la sortie affiche le plan, le pas de l’instantané et si les carnets sont vérifiés ; comparez-les à votre profil.

  2. Déplacez le seuil

    Réglez MIN_SPREAD = 0.5 et regardez combien de nouvelles lignes gardent la colonne -frais au-dessus de zéro.

  3. Ajoutez un jeu de données

    Copiez spot_rows pour /arbitrage/futures-futures : le format des lignes est le même. Retirez la vérification des dépôts et des retraits pour les futures, puisqu’aucun coin n’y circule entre les exchanges.

  4. Vérifiez la consommation

    Au bout d’une heure, appelez /account/usage et comparez calls_used à l’estimation : sur Trial, cela fait jusqu’à 2 × 60 = 120 appels par heure.

  5. Trouvez les paires durables

    Ouvrez monitor.csv dans un tableur et comptez combien de passes de suite chaque paire d’exchanges a duré.

Les risques de l’automatisation, des données périmées et des erreurs jusqu’aux clés et aux agents d’IA, sont traités dans la leçon 5, et l’interrogation économe avec filtres, compression et ETag dans l’article sur comment interroger une API sans atteindre les limites.

Questions et réponses

En quoi le moniteur diffère-t-il d’un bot d’arbitrage ?

Le moniteur affiche un tableau et conserve l’historique ; un bot envoie des alertes sur les nouvelles paires et se tait sur les répétitions. Ils partagent le code de requête et de filtrage, et le bot Telegram est présenté dans Bot d’arbitrage crypto en Python.

Puis-je interroger plus vite que freshness_sec ?

Vous n’obtiendrez pas de nouvelles données : votre plan reçoit un instantané toutes les freshness_sec secondes. Une requête sans filtres avant le prochain instantané renvoie un 304 gratuit, alors qu’une requête filtrée consomme un appel pour les mêmes données.

Pourquoi la colonne Carnet affiche-t-elle un tiret ?

Le Δ des carnets n’existe que sur Pro et Max, et le moniteur le demande pour les trois meilleures paires (BOOK_TOP). Sur Trial et Start, l’endpoint renvoie 403 plan_restricted, le moniteur ne l’appelle donc pas.