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, attendRetry-Aftersur429et503, 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 :
| Maillon | Ce qu'il fait | Dans ce bot |
|---|---|---|
| Données | Récupère les prix et les spreads entre plateformes | Genesis API GET /arbitrage/spot-spot |
| Filtre | Garde les paires exécutables | Statut de dépôt et de retrait, Δ des carnets pour 1 000 $ |
| Alerte | Signale la paire | Méthode sendMessage de l'API Bot de Telegram |
| Décision et ordre | Vérifie la paire et passe l'ordre | Une 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.
- Déplacer la crypto : le retrait et le dépôt prennent de quelques minutes à plusieurs heures, et une plateforme peut suspendre les dépôts ou les retraits à tout moment.
- Frais : les deux plateformes prélèvent des frais de trading, et les frais de retrait sont en général un nombre fixe de coins qui engloutit le spread sur un petit montant.
- Slippage : le spread est calculé à partir des derniers échanges, alors qu'un ordre au marché parcourt le carnet d'ordres ; un achat s'exécute donc au-dessus du meilleur ask et une vente en dessous du meilleur bid.
- Temps : les données arrivent avec le délai de votre plan, jusqu'à 60 secondes sur Trial, et d'autres traders voient le même écart et le referment.
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
- Python 3.10 ou plus récent et la bibliothèque
requests. - Une clé Genesis API de n'importe quel plan : cliquez sur « Obtenir la clé » dans votre profil et enregistrez la clé
gns_live_…, qui n'est affichée qu'une fois. Son stockage et sa réémission sont expliqués dans le guide Clé Genesis API. - Un token de bot Telegram : envoyez
/newbotà @BotFather, choisissez un nom et un nom d'utilisateur, et BotFather répond avec un token du type123456:ABC-DEF…. chat_id, l'identifiant de votre conversation avec le bot. Un bot ne peut pas vous écrire le premier (documentation Telegram) : envoyez-lui/start, puis appelezgetUpdates; le nombre dans"chat":{"id":…}est votrechat_id. Les mises à jour sont conservées 24 heures au plus.
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
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_SPREADetMIN_VOLUMEpour un temps : cela montre que la chaîne de l'API à Telegram fonctionne.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.
Vérifier la déduplication
La même paire ne doit pas revenir avant 15 minutes.
Surveiller la consommation d'appels
Regardez le champ
calls_usedde/account/usageou la ligne « Appels utilisés » de votre profil : sur Trial, sans contrôle des carnets, le bot consomme environ 1 440 appels par jour.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.
| Plan | Interrogation | Contrôle du carnet sur 1 000 $ | Appels sur 30 jours |
|---|---|---|---|
| Trial, 20 $/mois | Toutes les 60 s | Non | 43 200 sur 500 000 |
| Start, 50 $/mois | Toutes les 30 s | Non | 86 400 sur 2 millions |
| Pro, 100 $/mois | Toutes les 10 s | Oui | Jusqu'à 1 555 200 sur 5 millions |
| Max, 200 $/mois | Toutes les 5 s | Oui | Jusqu'à 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
- Prix périmés : le snapshot est actualisé toutes les
freshness_secet les carnets ont 5 à 20 secondes de retard sur la plateforme ; vérifiez donc les prix dans le terminal de la plateforme avant d'agir. - Réseaux fermés : les indicateurs de dépôt et de retrait valent à l'instant du snapshot, et une plateforme peut fermer les retraits pendant que vous achetez. Un même ticker peut désigner des tokens différents selon les plateformes ; comparez donc
contractetnetwork. - Frais et retraits :
spread_pctne les inclut pas, et des frais de retrait fixes engloutissent tout le spread sur un petit montant. - Faux spreads sur carnets minces : un large spread de dernier échange sur une crypto peu échangée disparaît dès le premier ordre.
min_volumeet le contrôle sur 1 000 $ écartent certaines de ces paires, mais pas toutes. - Limites atteintes : les requêtes en trop au sein d'une seconde reçoivent
429avecRetry-After: 1, et un quota épuisé arrête le bot jusqu'à la réinitialisation. Utiliser plusieurs clés ou comptes pour contourner les limites enfreint les règles ; des plans supérieurs existent pour les charges plus lourdes. Telegram répond aussi429sous son contrôle anti-flood.
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.