Un moniteur de spreads et de funding en Python
En bref
- Le moniteur est un programme console : toutes les
meta.freshness_secsecondes, il récupère les jeux complets/arbitrage/spot-spotet/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 avecIf-None-Matchavant le prochain instantané renvoie304sans consommer de quota. Sur429et503, le client attendRetry-Aftersecondes. - 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ête | Ce qu’elle renvoie | Quand |
|---|---|---|
/account/usage | Plan, freshness_sec, rps_limit | Au démarrage, ne consomme pas de quota |
/arbitrage/spot-spot | Paires Spot – Spot | À chaque passe, jeu complet |
/funding/spread | Meilleures 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 quota | Pause | Requêtes par passe | Appels par 30 jours |
|---|---|---|---|
| Trial, 500K | 60 s | 2 | 86 400 |
| Start, 2M | 30 s | 2 | 172 800 |
| Pro, 5M | 10 s | 5 | 1 296 000 |
| Max, 10M | 5 s | 5 | 2 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
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.
Déplacez le seuil
Réglez
MIN_SPREAD = 0.5et regardez combien de nouvelles lignes gardent la colonne -frais au-dessus de zéro.Ajoutez un jeu de données
Copiez
spot_rowspour/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.Vérifiez la consommation
Au bout d’une heure, appelez
/account/usageet comparezcalls_usedà l’estimation : sur Trial, cela fait jusqu’à 2 × 60 = 120 appels par heure.Trouvez les paires durables
Ouvrez
monitor.csvdans 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.