Genesis Arbitrage

Genesis Arbitrage · · 10 min de lecture

Limites de Genesis API : quota d’appels, requêtes par seconde, fraîcheur des données et erreurs 429

En bref

  • Votre forfait fixe le quota d’appels sur 30 jours (de 500 000 en Trial à 10 millions en Max), la limite de requêtes par seconde (de 1 à 15) et la fraîcheur des données (de 60 à 5 secondes).
  • Seule une réponse 200 consomme du quota. Les réponses 304 et les erreurs sont gratuites, mais occupent un créneau dans la limite de requêtes par seconde ; au-delà d’une limite, le serveur renvoie 429 et ne facture rien.
  • Interroger plus vite que meta.freshness_sec n’apporte aucune donnée nouvelle : votre forfait reçoit un nouvel instantané une fois par cet intervalle, et If-None-Match transforme les requêtes en trop en réponses 304 gratuites.

Les limites de Genesis API sont quatre plafonds par clé : le quota d’appels sur une période de 30 jours, le rate limit en requêtes par seconde, la fraîcheur des données et le volume de téléchargement. Votre forfait fixe les trois premiers ; le volume de téléchargement est le même pour tous : 60 Mo de données compressées toutes les 10 secondes. Au-delà de n’importe quelle limite, le serveur renvoie une erreur 429 et ne facture rien.

Limites par forfait

ForfaitAppels par 30 joursRequêtes par secondeFraîcheur
Trial, 20 $/mois500 000160 s
Start, 50 $/mois2 000 000230 s
Pro, 100 $/mois5 000 000510 s
Max, 200 $/mois10 000 000155 s

La fraîcheur des données est l’intervalle auquel votre forfait reçoit un nouvel instantané : toutes les 60 secondes en Trial, toutes les 5 en Max. Les réponses l’indiquent dans le champ meta.freshness_sec. Payer 3 mois fait économiser 10 %, 6 mois 20 %. La comparaison des forfaits se trouve sur la page tarifs de Genesis API, et les règles dans la section Plans et limites de la documentation.

Ce qui consomme le quota

Un appel est une réponse 200. Les réponses 304 (données non modifiées) et les erreurs 4xx et 5xx ne consomment pas de quota, mais comptent dans la limite de requêtes par seconde. Une requête vers /account/usage ne consomme aucun appel.

Le quota couvre une période de 30 jours, pas un mois calendaire. L’heure de réinitialisation figure dans l’en-tête X-Quota-Reset, dans le champ period_resets_at et dans la ligne « resets … » de votre profil. Quand le quota est épuisé, le serveur répond 429 rate_limited, et Retry-After contient le nombre de secondes avant la réinitialisation, ce qui peut représenter des jours.

En-têtes de rate limit

La réponse d’un endpoint de données porte l’état de vos limites (valeurs d’illustration) :

En-têteExempleCe qu’il indique
X-RateLimit-Limit5Limite de requêtes par seconde de votre forfait
X-RateLimit-Remaining4Requêtes restantes dans la fenêtre en cours
X-RateLimit-Reset1785200001Heure Unix de réinitialisation de la fenêtre
X-Quota-Limit5000000Quota d’appels sur la période de 30 jours
X-Quota-Remaining4815799Appels restants sur la période
X-Quota-Reset1786492800Heure Unix de réinitialisation du quota
Retry-After1Secondes à attendre avant de réessayer, sur 429 et 503

La fenêtre de requêtes par seconde dure une seconde ; dans une réponse normale, X-RateLimit-Reset pointe donc vers le début de la seconde suivante. Le quota restant de l’exemple : 5 000 000 − 184 201 = 4 815 799 appels, les mêmes chiffres que renvoie /account/usage.

L’endpoint /account/usage

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": { … }
}
ChampTypeSignification
planstringForfait : trial, start, pro ou max
calls_usedintAppels utilisés sur la période en cours
calls_limitintQuota d’appels par période
rps_limitintLimite de requêtes par seconde
freshness_secintRetard des données, en secondes
period_resets_atintHeure Unix de réinitialisation du quota

L’endpoint est disponible sur tous les forfaits et décrit dans la section Utilisation. Appelez-le au démarrage d’un bot, pour vérifier le forfait et le quota restant avant de commencer à interroger.

Erreurs 429 : rate_limited et download_limited

RéponseQuand elle survientQue faire
429 rate_limitedPlus de requêtes par seconde que ne le permet votre forfaitAttendre la durée de Retry-After et espacer les requêtes
429 rate_limitedLe quota de la période est épuiséAttendre la réinitialisation ou changer de forfait
429 rate_limitedTéléchargement complet de l’analytique de funding plus tôt qu’autoriséDemander une tranche avec coin ou envoyer If-None-Match
429 download_limitedPlus de 60 Mo de données compressées en 10 secondesAttendre la durée de Retry-After, restreindre la requête avec des filtres

Le code d’état 429 Too Many Requests est défini dans la RFC 6585, où Retry-After est facultatif. Genesis API l’envoie avec chaque 429, toujours en secondes.

Les réponses de moins de 64 Ko ne comptent pas dans le volume de téléchargement, et interroger tous les jeux de données à la fraîcheur de votre forfait tient largement dans la limite. Les téléchargements complets de l’analytique de funding sans coin ont leur propre limite : /funding/analytics/summary et /funding/analytics/recent une fois par 60 secondes, /funding/analytics/daily une fois par 300 secondes et par clé. Les requêtes avec coin et les réponses 304 ne sont pas limitées ; les détails sont dans la section Analytique de funding.

Accès par forfait et 403 plan_restricted

ForfaitCe qui est ouvert
TrialArbitrage CEX (Spot – Spot, Spot – Futures, Futures – Futures), taux de financement (funding) et spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, signaux IA, recherche de coins, /account/usage
StartTout Trial, plus les actions /arbitrage/stocks, les sections on-chain /onchain/{section}, l’arbitrage des marchés de prédiction en modes exact et dutch, l’état des plateformes
Pro et MaxTous les endpoints : DEX – Spot, DEX – Futures, Crosschain, DEX Dumps, carnets d’ordres, analytique de funding, analytique des marchés de prédiction, smart money, transactions, traders, modes llm et sport, swaps DEX, analytique OnChain et coin

Un endpoint hors de votre forfait renvoie 403, tout comme une requête mode=sport vers /predictions/arbitrage sur Start :

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

Un 403 ne consomme pas de quota. Le réessayer ne sert à rien : seul un forfait supérieur ouvre l’accès.

Dimensionner son forfait selon la charge

Exemple d’illustration : un bot interroge trois endpoints, /arbitrage/spot-spot, /funding/spread et /market/open-interest, toutes les 10 secondes, 24 h/24.

Le même bot interrogeant à la fraîcheur de chaque forfait :

Fraîcheur et interrogationAppels par 30 joursForfaitPart du quota
Toutes les 60 s129 600Trial26 %
Toutes les 30 s259 200Start13 %
Toutes les 10 s777 600Pro16 %
Toutes les 5 s1 555 200Max16 %

Interroger toutes les 10 secondes a du sens à partir de Pro : 777 600 / 5 000 000 = 15,552 % du quota, et la limite de 5 requêtes par seconde permet d’envoyer les trois d’un coup. Si le bot s’accommode de données vieilles de 30 secondes, Start avec une interrogation toutes les 30 secondes coûte 259 200 / 2 000 000 = 12,96 % du quota.

Interroger sans appels gaspillés : ETag et Retry-After

Votre forfait reçoit un nouvel instantané toutes les meta.freshness_sec secondes, et interroger plus vite renvoie le même instantané avec le même meta.updated_at. Sans l’en-tête If-None-Match, une telle réponse est un 200 et un appel consommé. Avec lui, le serveur répond 304 sans corps : le quota reste intact, mais un créneau de la limite par seconde est pris.

Un ETag ne vient pas avec toutes les réponses. Les jeux de données complets le renvoient, c’est-à-dire les requêtes sans filtres, comme /funding/spread dans l’exemple ci-dessous. Une réponse filtrée (coin, min_spread et d’autres) n’a pas d’ETag, et chaque interrogation coûte un appel : les filtres économisent du trafic, l’ETag économise du quota. Les nouvelles tentatives et la compression sont traitées dans comment interroger une API efficacement et dans le guide des réponses et erreurs.

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # le quota est épuisé, on s’arrête ici
            raise SystemExit(f"Quota épuisé, réinitialisation dans {wait} s")
        time.sleep(wait)
        continue
    r.raise_for_status()  # une nouvelle tentative ne corrige pas 401 ni 403
    left = r.headers.get("X-Quota-Remaining")  # peut être absent
    if left is not None and int(left) < 10_000:
        print("Quota bientôt épuisé :", left)
    if r.status_code == 200:  # avec 304, les données n’ont pas changé
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "coins dans la réponse")
    time.sleep(pause)

Changer et renouveler son forfait

Comment obtenir et conserver la clé est expliqué dans le guide de la clé Genesis API.

Questions et réponses

Que se passe-t-il si le quota s’épuise avant la fin de la période ?

Le serveur renvoie 429 rate_limited avec Retry-After jusqu’à la réinitialisation du quota, et rien n’est facturé. Attendez la nouvelle période ou payez un forfait supérieur : il prend effet immédiatement, avec un quota neuf.

Les réponses 304 et les erreurs comptent-elles dans les limites ?

Pas dans le quota : seul 200 le consomme. Elles comptent en revanche dans la limite de requêtes par seconde : les réponses 304 et les erreurs occupent des créneaux dans la fenêtre par seconde.

Comment vérifier le quota restant sans consommer d’appel ?

Lisez X-Quota-Remaining dans une réponse de données ou appelez /account/usage : cette requête ne consomme pas d’appel. La ligne des appels utilisés dans votre profil montre aussi la consommation.

Puis-je contourner la limite avec plusieurs clés ?

Non. Chaque compte reçoit une clé, les limites sont comptées par clé, et changer d’adresse IP ne les modifie pas. Ouvrir plusieurs comptes pour contourner les limites enfreint les règles ; si vous avez besoin de plus, passez à un forfait supérieur.