Genesis Arbitrage

Genesis Arbitrage · · 12 min de lecture

Votre première requête API : HTTP, en-têtes et JSON

En bref

  • Une requête HTTP vers une API se compose d’une méthode, d’une adresse formée de l’URL de base, du chemin et des paramètres, et d’en-têtes. La clé Genesis API se place uniquement dans l’en-tête X-API-Key.
  • Le code de statut indique la suite : 200 signifie lire les données, 304 que rien n’a changé, 401 et 403 qu’il faut vérifier la clé et le plan, 429 et 503 qu’il faut attendre Retry-After secondes.
  • La réponse de Genesis API est une enveloppe avec success, data et meta. Les pourcentages arrivent sous forme de nombres simples (0.01 signifie 0,01 %) et l’heure en secondes unix.
  • Les erreurs courantes du débutant sont une clé dans l’URL, une variable d’environnement vide, et une faute de frappe dans le chemin ou dans le nom d’un paramètre. Une faute dans un paramètre ne déclenche aucune erreur : vous obtenez l’ensemble des données au lieu des données filtrées.

Pour appeler une API, votre programme envoie une requête HTTP composée d’une méthode, d’une adresse et d’en-têtes, et le serveur renvoie un code de statut, ses propres en-têtes et un corps, qui est du JSON pour Genesis API. Vous pouvez envoyer la requête depuis un terminal avec curl ou depuis du code dans n’importe quel langage disposant d’un client HTTP. La première requête ci-dessous vérifie la clé avec /account/usage, et la seconde récupère les taux de financement (funding) du BTC depuis /funding/rates. Ce qu’est une API et ce que l’on peut automatiser avec elle est expliqué dans la leçon 1.

Anatomie d’une requête

Voici la requête des taux de financement (funding) du BTC que curl envoie au serveur, telle que l’option -v l’affiche dans les lignes commençant par > (la clé est remplacée par un espace réservé) :

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
ÉlémentDans l’exempleSignification
MéthodeGETLire des données ; tous les endpoints de Genesis API sont en GET
URL de basehttps://api.genesisarbitrage.com/v1Serveur et version de l’API
Chemin/funding/ratesL’endpoint des taux de financement (funding)
Paramètres?coin=BTCFiltre : BTC uniquement
En-têteX-API-KeyLa clé par laquelle le serveur identifie votre compte et votre plan

Les paramètres suivent le ? sous forme de paires nom=valeur reliées par & : ?coin=BTC&exchange=Binance,OKX. Les filtres de Genesis API sont facultatifs : sans coin, le même endpoint renvoie toutes les cryptomonnaies. Les décimales prennent un point, jamais une virgule : min_spread=0.5.

Les en-têtes sont des lignes nom: valeur qui voyagent avec l’adresse. Les noms d’en-têtes ne sont pas sensibles à la casse (RFC 9110, section 5.1) : X-API-Key et x-api-key désignent le même en-tête, et un x-request-id en minuscules dans la sortie de curl est le même X-Request-Id. Genesis API n’accepte la clé que dans X-API-Key.

Codes de statut

La première ligne de la réponse contient le code de statut, et votre programme décide de la suite d’après ce code :

CodeSignificationQue faire
200Requête traitée, données dans le corpsLire data et meta
304Données inchangées depuis votre dernière réponseRéutiliser les données précédentes
401Clé absente, invalide, révoquée ou abonnement expiréVérifier l’en-tête et l’abonnement
403Endpoint absent de votre plan (plan_restricted)Changer de plan ou abandonner la requête
429Limite de requêtes, de téléchargements ou de quota dépasséeAttendre Retry-After secondes
503Données en cours de reconstruction (snapshot_not_ready)Réessayer après Retry-After secondes

Seul un 200 consomme votre quota : un 304 et les erreurs sont gratuits, mais comptent dans la limite de requêtes par seconde. Un 304 n’est renvoyé qu’à une requête portant l’en-tête If-None-Match ; cet en-tête et les codes 400, 404, 410 et 500 sont décrits dans Réponses et erreurs de Genesis API. Pourquoi un nouvel essai après un 429 demande une pause est expliqué dans l’entrée du glossaire HTTP 429 Too Many Requests.

Première requête : /account/usage

/account/usage affiche l’état de votre clé : plan, quota utilisé et limites. Il est disponible sur tous les plans et ne consomme aucun appel, c’est donc là que va votre première requête. Placez d’abord la clé dans une variable d’environnement, puis envoyez la requête :

# collez la clé et appuyez sur Entrée : elle ne s’affichera pas à l’écran
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

L’option -i affiche la ligne de statut et les en-têtes avant le corps. Le corps de la réponse, un exemple illustratif pour le plan Trial :

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan est votre plan, et calls_used sur calls_limit correspond à l’utilisation du quota pour la période de 30 jours. L’exemple affiche 0 car aucune autre requête n’a encore été faite, et /account/usage lui-même ne consomme pas d’appel. rps_limit est le nombre de requêtes par seconde, freshness_sec la fréquence de mise à jour des données de votre plan, et period_resets_at le moment de la remise à zéro du quota. Les champs sont décrits dans la section Utilisation de la documentation.

Parmi les en-têtes, repérez X-Request-Id, l’identifiant de la requête que vous transmettez au support à la place de votre clé, et X-RateLimit-Remaining, le nombre de requêtes restantes dans la fenêtre de limite en cours.

La même requête en Python

Un script pour Python 3.10+ avec la bibliothèque requests lit la clé dans la même variable d’environnement :

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # KeyError si elle n’est pas définie

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # sans timeout, requests peut attendre indéfiniment
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan :", usage["plan"])
print("appels :", usage["calls_used"], "sur", usage["calls_limit"])
print("remise à zéro du quota :", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"] arrête le script si la variable n’est pas définie, ce qui vaut mieux que d’envoyer une requête sans clé et de recevoir un 401. r.headers n’est pas sensible à la casse : X-Request-Id est trouvé même quand le serveur envoie x-request-id.

period_resets_at est un temps unix : le nombre de secondes écoulées depuis le 1er janvier 1970, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) le transforme en date : 1796463000 correspond au 5 décembre 2026, 09:30 UTC.

Deuxième requête : taux de financement (funding) du BTC

Le funding est un paiement périodique entre les positions longues et courtes d’un contrat à terme perpétuel, et les exchanges le règlent toutes les 8, 4 ou 1 heures. /funding/rates renvoie les taux de tous les exchanges, et le paramètre coin les limite à une cryptomonnaie. La réponse à GET /funding/rates?coin=BTC, un exemple illustratif avec deux exchanges de la liste :

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

Comment lire cette réponse :

Tous les champs figurent dans la section Taux de funding de la documentation. Le bloc suivant poursuit le script : BASE, key et les imports sont déjà en place.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests construit ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # lève une exception sur 4xx et 5xx
body = r.json()
if not body["data"]:
    raise SystemExit("cryptomonnaie absente des données : vérifiez le ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("instantané du", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
          f'par {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% par 8h')

Pour l’exemple de réponse, le script affiche :

instantané du 2026-11-14 17:04:21 UTC
Hyper     0.0013% par 1h,  0.0104% par 8h
Bitget      0.01% par 8h,    0.01% par 8h

Hyper se classe au-dessus de Bitget alors que son taux par intervalle est 0,01 / 0,0013 ≈ 7,7 fois plus faible. Sans normalisation à 8 heures, cette comparaison est faussée.

Erreurs courantes du débutant

ErreurCe que renvoie le serveurComment la corriger
Clé dans l’URL : ?api_key=…401 et « Missing X-API-Key header. »Envoyer la clé uniquement dans l’en-tête X-API-Key
Variable de clé vide401 avec le même texte : curl supprime un en-tête videVérifier la longueur : echo ${#GENESIS_API_KEY}
Faute dans le chemin : /v1/funding/rate ou sans /v1404Comparer le chemin avec la documentation
Faute dans le nom d’un paramètre : coins=BTC200 et toutes les cryptomonnaies : un paramètre inconnu est ignoréVérifier meta.count : avec coin=BTC, il vaut 1
Virgule décimale : min_spread=0,5200 sans filtre appliquéUtiliser un point : 0.5
Paire au lieu du ticker : coin=BTCUSDT200, data vide, meta.count égal à 0Utiliser le ticker de la cryptomonnaie : BTC

La faute dans un paramètre est la plus sournoise : il n’y a aucune erreur, mais le script reçoit l’ensemble des données au lieu d’une seule cryptomonnaie et y dépense un appel. Après avoir ajouté un nouveau filtre, comparez meta.count avec ce que vous attendez.

Essayez vous-même

  1. Envoyez une requête sans clé

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" renvoie 401 avec invalid_key et « Missing X-API-Key header. » dans le corps. Repérez x-request-id parmi les en-têtes.

  2. Répétez-la avec la clé

    Définissez la variable avec read -s et envoyez la requête de la section /account/usage. Vous obtenez un 200 et votre plan dans data.plan.

  3. Vérifiez la date de remise à zéro

    Lancez le script Python et comparez la date de remise à zéro du quota avec la ligne « remise à zéro … » du bloc « Genesis API » de votre profil. L’obtention d’une clé pas à pas est décrite dans le démarrage rapide de Genesis API.

  4. Trouvez le taux le plus élevé

    Ajoutez le second bloc au script et trouvez l’exchange avec le funding_8h_pct le plus élevé. Ramenez à la main son funding_pct à 8 heures : taux × 8 / intervalle en heures.

  5. Cassez la requête exprès

    Remplacez coin par coins et comparez meta.count, puis retirez le s de /funding/rates et regardez le code de statut.

Les endpoints utiles pour décider à partir des spreads, des carnets d’ordres et du funding font l’objet de la leçon 3.

Questions et réponses

Puis-je appeler l’API depuis un navigateur ?

Uniquement les adresses qui ne demandent pas de clé : https://api.genesisarbitrage.com/health s’ouvre dans un navigateur et affiche {"ok":true}. La barre d’adresse ne peut pas ajouter d’en-tête X-API-Key : les requêtes avec clé passent donc par curl, un script ou le formulaire « Essayer » de la documentation. N’intégrez jamais la clé dans le code d’un site web ou d’une extension : quiconque ouvre le code source de la page la verra.

En quoi l’option -i diffère-t-elle de -v dans curl ?

-i affiche la ligne de statut et les en-têtes de la réponse avant le corps. -v montre aussi la requête elle-même : les lignes avec > sont ce qui est parti vers le serveur, et les lignes avec < ce qui est revenu.

Comment convertir le temps unix en date sans Python ?

Sous macOS, exécutez date -u -r 1796463000 ; sous Linux, date -u -d @1796463000. Pour ce nombre, les deux affichent le 5 décembre 2026, 09:30 UTC.