Genesis Arbitrage

Genesis Arbitrage · · 13 min de lecture

Réponses et erreurs de Genesis API : format JSON, ETag et 304, codes HTTP

En bref

  • Une réponse réussie de Genesis API est une enveloppe success, data et meta ; une erreur est success: false plus un objet error avec un code et un message.
  • Si vous renvoyez l’ETag précédent dans If-None-Match, le serveur répond 304 sans corps quand les données n’ont pas changé, et un 304 ne consomme pas de quota.
  • Réessayez 429 et 503 après la pause Retry-After. Réessayer ne corrige pas 400, 401, 403, 404 ni 410 : changez la requête, la clé ou le plan.

Genesis API répond à chaque requête en JSON, un format de données texte fait d’objets clé–valeur et de tableaux. Une réponse réussie arrive toujours dans la même enveloppe success, data et meta ; une erreur arrive avec un code de statut HTTP et un objet error. Le code de statut indique à votre programme quoi faire : utiliser les données, attendre Retry-After secondes puis réessayer, ou corriger la requête.

Enveloppe de la réponse : success, data et meta

Une réponse abrégée de GET /arbitrage/spot-spot, tirée de la documentation (le endpoint est disponible sur tous les plans) :

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
ChampTypeContenu
successbooleantrue : la requête a abouti, false : erreur
datatableau ou objetLes données du endpoint
meta.countintNombre d’éléments dans data
meta.updated_atintHeure unix de construction des données
meta.freshness_secintDélai de diffusion pour votre plan, en secondes
meta.planstringVotre plan, pro dans l’exemple

L’exception est l’analytique du funding : son meta contient count, updated_at et schema_version, sans freshness_sec ni plan. L’enveloppe est décrite dans la section Format de réponse de la documentation, et les champs de data sur la page de chaque endpoint.

Trois conventions valent pour tous les endpoints :

data : un tableau de lignes ou un objet

La forme de data est indiquée dans la description de chaque endpoint. Pour GET /arbitrage/spot-spot, c’est un tableau : un élément par paire d’arbitrage, comme une ligne du tableau du site. Pour GET /account/usage, c’est un seul objet avec l’état de votre clé :

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage est disponible sur tous les plans et affiche votre plan, la consommation du quota et freshness_sec : interroger plus souvent n’apporte rien. Les champs sont décrits dans Utilisation, et la première requête est détaillée pas à pas dans le démarrage rapide. Un code qui manipule plusieurs endpoints doit vérifier la forme explicitement : isinstance(data, list) en Python.

Filtres : facultatifs, jeu de données complet sans eux

Tous les paramètres de filtre sont facultatifs : une requête sans filtre renvoie le jeu de données complet du endpoint. Indiquez plusieurs plateformes dans exchange, séparées par des virgules, et une crypto par son ticker dans coin :

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

L’option -G transforme les paramètres -d en chaîne de requête : ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Écrivez les noms des plateformes comme ils reviennent dans les champs de la réponse : ByBit, Gate, MEXC. Les paramètres des endpoints d’arbitrage sont dans le guide des endpoints d’arbitrage.

Le quota compte les réponses, pas les lignes : une requête avec ou sans filtre est un appel. Un filtre réduit le corps de la réponse, donc le trafic et la consommation de la limite de téléchargement. Toutes les limites sont détaillées dans le guide des limites de Genesis API.

Compression gzip

Genesis API envoie les jeux de données complets et les réponses volumineuses compressés en gzip lorsque le client envoie l’en-tête Accept-Encoding: gzip (RFC 9110, section 12.5.3). Une petite réponse peut arriver non compressée.

requests de Python envoie cet en-tête lui-même et décompresse la réponse. curl ne demande pas la compression sans l’option --compressed ; avec elle, il la demande et décompresse.

La limite de téléchargement compte les données compressées : au plus 60 Mo par tranche de 10 secondes et par clé, et les réponses de moins de 64 Ko ne sont pas comptées. Au-delà, vous recevez 429 download_limited.

ETag et 304 : ignorer les données inchangées

ETag est un en-tête de réponse qui contient une étiquette de version des données. Le client renvoie cette étiquette dans l’en-tête If-None-Match. Si les données n’ont pas changé, le serveur répond 304 Not Modified sans corps ; sinon, un 200 ordinaire avec de nouvelles données et un nouvel ETag.

# Jeu de données complet, sans filtres : afficher uniquement les en-têtes de la réponse
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# Répéter avec l’ETag de la première réponse (valeur d’illustration)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

Un ETag accompagne la réponse à une requête sans filtres et change à chaque nouvel instantané des données. La réponse à une requête filtrée est construite pour cette requête et arrive sans ETag ; dans ce cas, le filtre lui-même économise le trafic. Les ETag aident surtout pour les données qui évoluent lentement : le résumé de l’analytique du funding change d’ETag environ toutes les 15 minutes, et les réponses 304 ne comptent pas dans sa limite de téléchargement complet.

Une réponse 304 ne consomme pas de quota, mais compte dans la limite de requêtes par seconde. Renvoyez l’étiquette exactement comme elle est arrivée : selon la RFC 9110, c’est une chaîne entre guillemets, et le préfixe W/ indique une étiquette faible.

Codes d’erreur et conduite à tenir

En cas d’erreur, Genesis API renvoie le statut HTTP correspondant et un corps avec success: false :

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code est un code lisible par machine sur lequel votre programme peut brancher sa logique. error.message est l’explication pour un humain : pour 400, elle donne la raison ; pour 410, l’adresse de remplacement.

HTTPerror.codeSignificationQue faire
400bad_requestParamètres de requête invalides, par exemple volume=700 sur /orderbooks/execCorrigez les paramètres d’après message : la même requête échouera à nouveau
401invalid_keyClé absente, invalide ou révoquée, ou abonnement à l’API expiréVérifiez l’en-tête X-API-Key et l’état de l’abonnement dans votre profil
403plan_restrictedLe endpoint n’est pas dans votre planPassez à un plan qui l’inclut ou supprimez la requête
404not_foundEndpoint ou ressource introuvable : jeu de données, section, crypto, carnet d’ordresVérifiez le chemin et les paramètres dans la documentation
410goneLe endpoint est retiréPassez à l’adresse indiquée dans message
429rate_limitedLimite de requêtes par seconde dépassée, ou quota de la période épuiséAttendez Retry-After secondes et ralentissez ; si le quota est épuisé, attendez la réinitialisation ou changez de plan
429download_limitedVolume de téléchargement dépassé : 60 Mo de données compressées par tranche de 10 s et par cléAttendez Retry-After, réduisez le trafic avec des filtres, coin et If-None-Match
500internal_errorErreur interneRéessayez plus tard ; si elle persiste, contactez le support avec le X-Request-Id
503snapshot_not_readyLes données sont en cours de reconstruction ou leur source redémarreRéessayez après Retry-After secondes

L’en-tête Retry-After accompagne 429 et 503 et contient le nombre de secondes à attendre : en général quelques secondes, mais quand le quota de la période est épuisé, c’est le temps avant sa réinitialisation, qui peut se compter en jours. Les erreurs 4xx et 5xx ne consomment pas de quota, mais comptent dans la limite de requêtes par seconde : un nouvel essai trop tôt renverra très probablement la même erreur. Termes du glossaire : HTTP 429 et rate limit.

X-Request-Id : quoi envoyer au support

Chaque réponse de Genesis API, réussie ou non, porte un en-tête X-Request-Id avec l’identifiant de la requête. Si une erreur revient ou si les données semblent fausses, envoyez au support :

N’envoyez pas votre clé. Si elle s’est retrouvée dans un chat, des journaux ou du code visible par d’autres personnes, réémettez-la dans votre profil : l’ancienne clé cesse de fonctionner immédiatement.

Ordre de traitement d’une réponse

  1. Vérifier le code de statut

    200 : lisez data et meta, et conservez l’ETag s’il est présent. 304 : utilisez les données de la réponse précédente.

  2. Traiter les erreurs temporaires

    429 et 503 avec une courte pause : attendez Retry-After secondes et réessayez, trois fois de suite au maximum. 500 : réessayez plus tard.

  3. S’arrêter sur les erreurs de requête

    400, 401, 403, 404, 410, et un 429 avec une pause de plusieurs heures ou jours : corrigez les paramètres, la clé ou le plan, ou attendez la réinitialisation du quota.

  4. Vérifier l’âge des données

    Comparez meta.updated_at avec l’heure actuelle : un bot qui agit sur un vieil instantané voit des spreads qui ont déjà disparu.

  5. Planifier la requête suivante

    Pas avant meta.freshness_sec secondes plus tard, avec If-None-Match pour les requêtes sans filtres.

Une fonction get_json en Python

La fonction réunit ces règles : elle garde le dernier ETag de chaque adresse et renvoie les données précédentes sur 304, attend Retry-After sur 429 et 503 et réessaie jusqu’à trois fois, mais n’attend pas les pauses de plus d’une minute. Les autres erreurs lèvent une exception avec le statut, le message et le X-Request-Id. La clé vient de la variable d’environnement GENESIS_API_KEY.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (chemin, paramètres) -> (ETag, données)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # une requête plus jusqu’à 3 nouvelles tentatives
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # les données n’ont pas changé
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # ne jamais attendre des heures ou des jours
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "pas du JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # seulement sur les réponses sans filtres
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

Le paramètre timeout=15 est indispensable : sans délai d’attente, requests attend une réponse indéfiniment.

Interrogation à l’intervalle de votre plan : le jeu de données complet arrive avec un ETag et les lignes sont filtrées dans le code. Les erreurs 4xx arrêtent le programme ; une panne du serveur attend le cycle suivant.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # jeu de données complet
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "paires avec un spread de 1 % ou plus")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx : la requête, la clé, le plan ou le quota
        print("erreur serveur, nouvel essai au prochain cycle :", e)
    time.sleep(pause)

Questions et réponses

Une réponse 304 consomme-t-elle du quota ?

Non. Seules les réponses 200 consomment du quota. Les réponses 304 et les erreurs 4xx et 5xx sont gratuites, mais comptent dans la limite de requêtes par seconde.

Que faire après un 410 ?

Le endpoint est retiré et l’adresse de remplacement figure dans error.message. Par exemple, GET /arbitrage/predictions a été retiré le 15 novembre 2026 et son message renvoie vers /predictions/arbitrage. Mettez à jour le chemin dans votre code.

Pourquoi data est-il vide sans erreur ?

Les filtres ont éliminé toutes les lignes : par exemple, min_spread est supérieur à tous les spreads actuels. Une telle réponse a meta.count égal à 0 ; assouplissez le filtre.

Pourquoi n’y a-t-il pas d’ETag dans la réponse ?

Un ETag accompagne la réponse à une requête sans filtres. La réponse à une requête avec coin, exchange, min_spread ou un autre filtre est construite pour cette requête et arrive sans étiquette, donc If-None-Match ne s’y applique pas.