Genesis Arbitrage

Genesis Arbitrage · · 20 min de lecture

Bot d'arbitrage crypto en Python : de l'API de spreads aux alertes Telegram

En bref

  • Un bot d'arbitrage crypto comporte quatre maillons : les données de spreads, un filtre de paires exécutables, une alerte et la décision d'une personne. Le code gère les trois premiers ; vous passez les ordres sur les plateformes.
  • L'exécution est la partie difficile de l'arbitrage : déplacer la crypto, les frais, le slippage et le temps. Le bot ne garde donc que les paires aux retraits et dépôts ouverts, et sur Pro et Max il recalcule aussi le spread à travers 1 000 $ de carnet d'ordres.
  • Le bot interroge Genesis API au plus souvent toutes les meta.freshness_sec, attend Retry-After sur 429 et 503, et n'alerte sur une paire qu'une fois toutes les 15 minutes au maximum. La version de base tourne avec le plan Trial à 20 $ par mois.

Un bot d'arbitrage crypto est un programme qui récupère à intervalle régulier les spreads entre plateformes (l'écart de prix d'une même crypto, en pourcentage), garde les paires réellement exécutables et vous en informe. Une personne prend la décision et passe l'ordre. Un tel bot pour l'arbitrage spot entre plateformes tient en environ 140 lignes de Python : les spreads viennent de Genesis API, et les messages partent par l'API Bot de Telegram.

De quoi se compose un bot d'arbitrage

Tout bot d'arbitrage repose sur quatre maillons :

MaillonCe qu'il faitDans ce bot
DonnéesRécupère les prix et les spreads entre plateformesGenesis API GET /arbitrage/spot-spot
FiltreGarde les paires exécutablesStatut de dépôt et de retrait, Δ des carnets pour 1 000 $
AlerteSignale la paireMéthode sendMessage de l'API Bot de Telegram
Décision et ordreVérifie la paire et passe l'ordreUne personne sur les plateformes

Votre propre collecteur de données est le maillon le plus long à construire : chaque plateforme a son API, ses noms de tickers et de réseaux, ses statuts de dépôt et de retrait, et tout doit être ramené à un seul format. Genesis API renvoie des paires toutes prêtes sur plus de 20 plateformes CEX, dont Binance, OKX, Bybit, Bitget, MEXC et Gate, avec prix, spread, réseau, contrat, statut de dépôt et de retrait, et volumes. Les champs de chaque endpoint d'arbitrage figurent dans le guide Endpoints d'arbitrage de Genesis API, et le choix d'une source de données est traité dans API crypto : types et comment choisir.

Pourquoi les ordres restent à une personne

Trouver un spread est la partie facile de l'arbitrage. L'exécution est la partie difficile : quatre obstacles séparent une ligne de la réponse de l'API de l'argent sur votre compte.

Exemple hypothétique : le bot envoie une paire avec un spread de 1,2 %, soit 12 $ sur 1 000 $. Après le parcours des carnets d'ordres pour 1 000 $, il reste 0,8 %, soit 8 $. Des frais taker de 0,1 % à l'achat et à la vente coûtent environ 2 $, et le retrait de la crypto coûte 3 $.

Un code qui achèterait et retirerait la crypto tout seul transformerait chacun de ces échecs en un ordre que personne n'a vérifié. C'est pourquoi ce bot envoie un signal : il contrôle lui-même les retraits, les dépôts et le spread après les carnets, et une personne vérifie le contrat, les frais et l'itinéraire du transfert avant d'agir. De toute façon, Genesis API ne peut pas passer d'ordres : elle ne fait que lire des données. La vérification manuelle pas à pas d'une paire est décrite dans Arbitrage crypto entre plateformes.

Ce qu'il vous faut

python3 --version   # Python 3.10 ou plus récent est requis
python3 -m pip install requests

export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
export TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

# après /start dans la conversation du bot, cherchez "chat":{"id":...}
curl "https://api.telegram.org/bot$TG_BOT_TOKEN/getUpdates"

export TG_CHAT_ID="123456789"

Les variables définies avec export durent jusqu'à la fermeture du terminal. D'après la documentation Telegram, le token donne le contrôle total du bot, et la clé donne accès à votre plan ; les deux ne vivent donc que dans des variables d'environnement : jamais dans le code ni dans un dépôt.

Le code du bot pas à pas

Les sept blocs ci-dessous forment le bot.py complet : enregistrez-les dans un seul fichier, dans cet ordre. Les seuils des réglages sont des valeurs indicatives ; ajustez-les à vos frais et à la taille de vos ordres.

1. Réglages

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1"
TG = "https://api.telegram.org/bot" + os.environ["TG_BOT_TOKEN"]
CHAT_ID = os.environ["TG_CHAT_ID"]

MIN_SPREAD = 1.0      # spread de la ligne à partir de 1 %
MIN_VOLUME = 50_000   # volume 24 h sur les deux plateformes, dès 50 000 $
MIN_EXEC = 0.5        # spread après carnets de 1 000 $, dès 0,5 %
TOP = 5               # paires par passage, au maximum
REPEAT_SEC = 15 * 60  # une paire au plus une fois toutes les 15 minutes
RECHECK_SEC = 5 * 60  # une paire mangée par le carnet attend 5 minutes

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}       # requête -> (ETag, réponse)
wait_until = {}  # paire -> heure jusqu'à laquelle on se tait

La clé voyage dans l'en-tête X-API-Key de chaque requête faite via la session api et ne figure jamais dans l'URL. MIN_VOLUME écarte les paires dont le volume sur 24 h est inférieur à 50 000 $ sur l'une des plateformes. cache conserve les ETag des réponses, et wait_until l'heure jusqu'à laquelle le bot se tait sur une paire.

2. Appeler Genesis API : Retry-After et ETag

def get(path, params=None):
    """GET vers Genesis API avec reprises Retry-After et ETag."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # une requête et jusqu'à trois reprises
        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:  # snapshot inchangé
            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'y fait rien
        body = r.json()
        if "ETag" in r.headers:  # seuls les jeux complets ont un ETag
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("Genesis API occupée, nouvel essai au prochain tour")

429 est renvoyé quand vous dépassez la limite de requêtes par seconde ou le volume de téléchargement, et 503 pendant la reconstruction des données. Les deux portent Retry-After, et get attend autant de secondes que le serveur le demande. Un quota épuisé renvoie aussi 429, mais avec Retry-After égal au délai avant la réinitialisation, parfois plusieurs jours : le bot s'arrête alors. 400, 401 et 403 ne disparaissent pas en réessayant ; raise_for_status les lève donc. Toutes les limites figurent dans le guide Limites de Genesis API.

3. Spreads et filtrage des paires

def candidates():
    """Paires Spot – Spot dont la crypto est réellement transférable."""
    body = get("/arbitrage/spot-spot",
               {"min_spread": MIN_SPREAD, "min_volume": MIN_VOLUME})
    # retraits ouverts côté achat, dépôts ouverts côté vente
    rows = [x for x in body["data"]
            if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows, body["meta"]["freshness_sec"]

min_spread et min_volume filtrent les lignes côté serveur. Il n'existe pas de paramètres pour les indicateurs de dépôt et de retrait ; le code les vérifie donc : la crypto est transférable si les retraits sont ouverts sur la plateforme d'achat (withdraw_enabled_buy) et les dépôts sur la plateforme de vente (deposit_enabled_sell). Les champs utilisés par le bot, dans une ligne tirée de la documentation Spot — Spot :

{
  "coin": "FUEL",
  "exchange_buy": "ByBit",
  "exchange_sell": "Gate",
  "spread_pct": 0.11,
  "network": "ETH",
  "contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
  "withdraw_enabled_buy": true,
  "deposit_enabled_sell": true,
  "volume_24h_buy": 17652.64,
  "volume_24h_sell": 12512.51,
  "trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
  "trade_url_sell": "https://www.gate.io/trade/FUEL_USDT",
  …
}

Cette ligne ne passerait pas les filtres du bot : un spread de 0,11 % et des volumes inférieurs à 50 000 $. Le bot met le réseau et le contrat dans le message pour que vous les compariez aux pages de retrait et de dépôt des deux plateformes.

4. Le contrôle du carnet sur 1 000 $

def exec_spread(row):
    """Spread après carnets de 1 000 $. Pro et Max uniquement."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": 1000})
    for x in body["data"]:
        od = x["order_delta"]
        if (x["exchange_buy"] == row["exchange_buy"]
                and x["exchange_sell"] == row["exchange_sell"]
                and od["status"] == "ok"):
            return od["spread_pct"]
    return None  # no_book, exhausted, ou la paire a disparu

L'endpoint renvoie les lignes de la crypto dans le jeu Spot – Spot avec un objet order_delta : le Δ des carnets, c'est-à-dire le spread après parcours des carnets, en achetant sur les asks de la plateforme d'achat et en vendant sur les bids de la plateforme de vente. La fonction prend la ligne aux mêmes plateformes et son order_delta.spread_pct quand status vaut ok ; no_book signifie qu'il n'y a pas de carnet, et exhausted que le carnet s'est épuisé avant 1 000 $. Les carnets ont 5 à 20 secondes de retard sur la plateforme ; les champs sont décrits dans la documentation Δ des carnets et dans le guide des endpoints de carnets d'ordres.

Cette étape n'existe que sur Pro et Max ; sur Trial et Start, l'endpoint renvoie 403 plan_restricted. Le bot lit votre plan au démarrage et saute le contrôle dans ce cas : le message indique que le carnet n'a pas été vérifié, et c'est à vous de regarder la profondeur dans le terminal de la plateforme.

5. Le message Telegram

def message(row, ex):
    buy, sell = row["exchange_buy"], row["exchange_sell"]
    if ex is None:
        book = "carnet non vérifié (Trial ou Start)"
    else:
        book = f"après carnets de 1 000 $ : {ex:.2f} %"
    return "\n".join([
        f'{row["coin"]} : {buy} → {sell}',
        f'Spread {row["spread_pct"]} %, {book}',
        f'Réseau {row["network"]}, contrat {row["contract"] or "—"}',
        f'Achat : {row["trade_url_buy"]}',
        f'Vente : {row["trade_url_sell"]}',
    ])


def send(text):
    """sendMessage de l'API Telegram ; sur 429, attendre retry_after."""
    for _ in range(3):
        r = requests.post(TG + "/sendMessage", timeout=15, json={
            "chat_id": CHAT_ID, "text": text,
            "link_preview_options": {"is_disabled": True}})
        if r.status_code != 429:
            r.raise_for_status()  # 400 ou 401 : mauvais chat ou token
            return
        wait = r.json().get("parameters", {}).get("retry_after", 5)
        time.sleep(wait)  # contrôle anti-flood de Telegram
    raise RuntimeError("Telegram n'a pas accepté le message")

sendMessage prend chat_id et text de 1 à 4096 caractères, et la requête va à https://api.telegram.org/bot<token>/sendMessage (documentation de l'API Bot de Telegram). link_preview_options avec is_disabled désactive les aperçus de liens. Sous contrôle anti-flood, Telegram renvoie 429 et place l'attente, en secondes, dans parameters.retry_after. Dans une même conversation, Telegram demande aux bots de ne pas envoyer plus d'un message par seconde (FAQ des développeurs de bots).

Un message ressemble à ceci, à titre d'exemple hypothétique :

XYZ : MEXC → Gate
Spread 1,4 %, après carnets de 1 000 $ : 0,62 %
Réseau ETH, contrat 0x…
Achat : https://…
Vente : https://…

6. Déduplication : une paire toutes les 15 minutes

def scan(books):
    """Un passage : spreads, carnets, messages."""
    rows, pause = candidates()
    done = 0
    for row in rows:
        key = (row["coin"], row["exchange_buy"], row["exchange_sell"])
        if time.time() < wait_until.get(key, 0):
            continue  # déjà signalée, ou le carnet a mangé le spread
        if done == TOP:
            break
        done += 1
        ex = exec_spread(row) if books else None
        ok = not books or (ex is not None and ex >= MIN_EXEC)
        if ok:
            send(message(row, ex))
        # silence 15 minutes après une alerte, 5 si le carnet est mince
        hold = REPEAT_SEC if ok else RECHECK_SEC
        wait_until[key] = time.time() + hold
        time.sleep(1)  # au plus une requête et un message par seconde
    return pause

Une paire est le triplet crypto, plateforme d'achat et plateforme de vente. Après une alerte, le bot se tait sur cette paire pendant 15 minutes, même si le spread tient. Si le carnet a mangé le spread, le bot revient sur la paire au bout de 5 minutes ; le contrôle du carnet ne coûte donc pas un appel à chaque passage. Un passage prend au plus les cinq paires aux plus grands spreads et marque une pause d'une seconde après chacune : le bot reste ainsi dans ce que conseille Telegram et dans la limite par seconde de n'importe quel plan. Le dictionnaire vit en mémoire ; après un redémarrage, des paires récentes peuvent donc se répéter.

7. La boucle : pause d'au moins freshness_sec

def main():
    usage = get("/account/usage")["data"]  # ne consomme pas de quota
    books = usage["plan"] in ("pro", "max")
    pause = usage["freshness_sec"]
    print("Plan", usage["plan"], "| interrogation toutes les", pause,
          "s | carnets :", "oui" if books else "non")
    while True:
        try:
            pause = scan(books)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # clé, plan ou token : réessayer n'y fait rien
            print("Erreur serveur, nouvel essai :", e)
        except (requests.RequestException, RuntimeError) as e:
            print("Pas de réponse, nouvel essai :", e)
        time.sleep(pause)  # pas plus souvent que meta.freshness_sec


if __name__ == "__main__":
    main()

Au démarrage, le bot appelle /account/usage : la requête ne consomme pas de quota et renvoie votre plan et freshness_sec. C'est la fraîcheur des données, l'intervalle auquel votre plan reçoit un nouveau snapshot : 60 secondes sur Trial, 30 sur Start, 10 sur Pro et 5 sur Max. Ensuite, la pause vient de meta.freshness_sec, car interroger plus vite renvoie le même snapshot. Les pannes réseau et les erreurs 5xx attendent le passage suivant, tandis que les autres erreurs 4xx — mauvaise clé, abonnement expiré, plan sans l'endpoint, mauvais token ou chat_id — arrêtent le bot. Les codes d'erreur sont listés dans Réponses et erreurs de Genesis API, et un moniteur de spreads sans Telegram se construit dans la leçon Moniteur de spreads et de funding en Python.

Comment le lancer et le vérifier

python3 bot.py
# Plan trial | interrogation toutes les 60 s | carnets : non
  1. Attendre le premier passage

    Les messages arrivent quand le marché a des paires au-dessus de vos seuils. Si rien n'arrive en quelques minutes, baissez MIN_SPREAD et MIN_VOLUME pour un temps : cela montre que la chaîne de l'API à Telegram fonctionne.

  2. Comparer une paire avec le tableau

    Ouvrez Spot – Spot sur le site : la même crypto et la même paire de plateformes figurent dans le tableau. Les chiffres peuvent différer légèrement, car l'API sert le snapshot avec le délai de votre plan.

  3. Vérifier la déduplication

    La même paire ne doit pas revenir avant 15 minutes.

  4. Surveiller la consommation d'appels

    Regardez le champ calls_used de /account/usage ou la ligne « Appels utilisés » de votre profil : sur Trial, sans contrôle des carnets, le bot consomme environ 1 440 appels par jour.

  5. Laisser le bot tourner

    nohup python3 bot.py >> bot.log 2>&1 & lance le bot en arrière-plan ; définissez les variables d'environnement dans la même session de terminal.

Quel plan Genesis API pour le bot

Un passage correspond à un appel /arbitrage/spot-spot, plus jusqu'à cinq appels /orderbooks/spreads/spot-spot sur Pro et Max ; seules les réponses 200 consomment du quota. Borne haute sur 30 jours : (1 + contrôles par passage) × 86 400 / pause × 30.

PlanInterrogationContrôle du carnet sur 1 000 $Appels sur 30 jours
Trial, 20 $/moisToutes les 60 sNon43 200 sur 500 000
Start, 50 $/moisToutes les 30 sNon86 400 sur 2 millions
Pro, 100 $/moisToutes les 10 sOuiJusqu'à 1 555 200 sur 5 millions
Max, 200 $/moisToutes les 5 sOuiJusqu'à 3 110 400 sur 10 millions

Sur Trial, cela donne 86 400 / 60 × 30 = 43 200 appels, soit 8,64 % du quota. Sur Pro, dans le pire cas où chaque passage contrôle cinq carnets, on obtient 6 × 86 400 / 10 × 30 = 1 555 200 appels, soit 31,1 % du quota. Les règles du quota se trouvent dans la section Plans et limites de la documentation.

Risques d'un bot d'arbitrage

Sans code : les alertes Telegram de Genesis Arbitrage

Si vous préférez ne pas écrire ni exécuter votre propre bot, les Alertes Telegram de Genesis Arbitrage envoient les paires à votre place. Vous créez un bot dans @BotFather, collez son token sur le site et choisissez des catégories comme Spot - Spot, DEX - Futures, Crosschain et Arbitrage de Funding. Les filtres fixent le spread minimal, les plateformes et les réseaux, le Statut dépôt/retrait et le Spread par ordres, et le Délai de répétition (min) limite la fréquence de retour d'une même paire. Le bot personnel fonctionne avec le plan Pro du site, distinct des plans Genesis API ; la configuration est décrite dans le guide des notifications Telegram.

Questions et réponses

Le bot peut-il passer des ordres seul ?

Pas via Genesis API : l'API ne fournit que des données et ne passe aucun ordre. Le trading s'ajoute par les API propres des plateformes avec des clés de trading, ce qui est un autre code et votre propre risque : un spread périmé ou un retrait fermé devient un ordre que personne n'a vérifié.

Combien coûte un bot comme celui-ci ?

Le code est gratuit, tout comme les messages du bot vers les utilisateurs de Telegram. Vous payez les données : Genesis API démarre à 20 $ par mois avec Trial, et le contrôle du carnet commence avec Pro, à 100 $. Il vous faut aussi un ordinateur ou un serveur qui tourne en continu.

De quel plan Genesis API ai-je besoin ?

Trial suffit pour le bot de base : /arbitrage/spot-spot est disponible sur tous les plans, avec un nouveau snapshot toutes les 60 secondes. Start actualise les données toutes les 30 secondes. Le contrôle du Δ des carnets sur 1 000 $ ne fonctionne que sur Pro et Max.

Pourquoi le bot a-t-il envoyé une paire dont le spread a disparu sur la plateforme ?

Les données arrivent avec le délai de votre plan, et d'autres traders referment aussi l'écart. Le spread de la ligne est en outre calculé à partir des derniers échanges, alors que vous ne pouvez acheter qu'à l'ask et vendre qu'au bid. Vérifiez les prix et le carnet d'ordres dans le terminal de la plateforme avant d'agir.

Puis-je publier le bot sur GitHub ?

Oui : les conditions autorisent à construire vos propres bots sur Genesis API, et la seule restriction est de revendre les données brutes telles quelles. Gardez la clé et le token hors du dépôt. Si la clé se retrouve dans du code public, cliquez sur « Réémettre » dans votre profil, et la commande /token dans @BotFather remplace le token du bot.