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 :
200signifie lire les données,304que rien n’a changé,401et403qu’il faut vérifier la clé et le plan,429et503qu’il faut attendreRetry-Aftersecondes. - La réponse de Genesis API est une enveloppe avec
success,dataetmeta. Les pourcentages arrivent sous forme de nombres simples (0.01signifie 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ément | Dans l’exemple | Signification |
|---|---|---|
| Méthode | GET | Lire des données ; tous les endpoints de Genesis API sont en GET |
| URL de base | https://api.genesisarbitrage.com/v1 | Serveur et version de l’API |
| Chemin | /funding/rates | L’endpoint des taux de financement (funding) |
| Paramètres | ?coin=BTC | Filtre : BTC uniquement |
| En-tête | X-API-Key | La 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 :
| Code | Signification | Que faire |
|---|---|---|
200 | Requête traitée, données dans le corps | Lire data et meta |
304 | Données inchangées depuis votre dernière réponse | Réutiliser les données précédentes |
401 | Clé absente, invalide, révoquée ou abonnement expiré | Vérifier l’en-tête et l’abonnement |
403 | Endpoint absent de votre plan (plan_restricted) | Changer de plan ou abandonner la requête |
429 | Limite de requêtes, de téléchargements ou de quota dépassée | Attendre Retry-After secondes |
503 | Donné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 :
- l’enveloppe :
successvauttrue, les données sont dansdataet les champs de service dansmeta;meta.countest le nombre d’éléments dedata, soit une cryptomonnaie pourcoin=BTC, avec un tableauexchangesà l’intérieur ; - les pourcentages arrivent sous forme de nombres simples :
"funding_pct": 0.01signifie 0,01 % par intervalle, et non 1 % ; sur une position de 10 000 $, un paiement à ce taux vaut 10 000 × 0,01 / 100 = 1 $ ; funding_8h_pctramène le taux à 8 heures pour que des exchanges aux intervalles différents se comparent directement : Hyper règle toutes les heures, et 0.0013 × 8 = 0,0104 % pour 8 heures ;next_payoutest l’heure du prochain paiement en UTC sous forme de chaîne « HH:MM », etnullsignifie absence de données, pas zéro ;meta.updated_atest le temps unix de construction de l’instantané : 1794675861 correspond au 14 novembre 2026, 17:04:21 UTC ; sur Trial, l’instantané se rafraîchit toutes les 60 secondes.
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
| Erreur | Ce que renvoie le serveur | Comment 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é vide | 401 avec le même texte : curl supprime un en-tête vide | Vérifier la longueur : echo ${#GENESIS_API_KEY} |
Faute dans le chemin : /v1/funding/rate ou sans /v1 | 404 | Comparer le chemin avec la documentation |
Faute dans le nom d’un paramètre : coins=BTC | 200 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,5 | 200 sans filtre appliqué | Utiliser un point : 0.5 |
Paire au lieu du ticker : coin=BTCUSDT | 200, data vide, meta.count égal à 0 | Utiliser 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
Envoyez une requête sans clé
curl -i "https://api.genesisarbitrage.com/v1/account/usage"renvoie401avecinvalid_keyet « Missing X-API-Key header. » dans le corps. Repérezx-request-idparmi les en-têtes.Répétez-la avec la clé
Définissez la variable avec
read -set envoyez la requête de la section/account/usage. Vous obtenez un200et votre plan dansdata.plan.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.
Trouvez le taux le plus élevé
Ajoutez le second bloc au script et trouvez l’exchange avec le
funding_8h_pctle plus élevé. Ramenez à la main sonfunding_pctà 8 heures : taux × 8 / intervalle en heures.Cassez la requête exprès
Remplacez
coinparcoinset comparezmeta.count, puis retirez lesde/funding/rateset 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.