Genesis API pour agents IA : OpenAPI, llms.txt et function calling
En bref
- Pour les agents, il y a openapi.json (OpenAPI 3.1, 37 opérations avec les plans), llms-full.txt, llms.txt et un catalogue d’API selon la RFC 9727.
- Le modèle choisit un outil et ses arguments ; votre serveur fait la requête avec la clé et renvoie au modèle un court JSON avec l’heure des données.
- Genesis API ne fait que lire les données. Votre code limite la cadence des requêtes, le modèle traite le texte des réponses comme des données, et un humain confirme tout trade.
Genesis API est une API REST de données de marché crypto qu’un agent IA appelle comme un outil : le modèle décide de quelles données il a besoin, votre serveur envoie une requête GET avec la clé et renvoie un court JSON. Pour les agents et les modèles de langage, il existe une description de l’API lisible par machine : une spécification OpenAPI 3.1, une référence complète en Markdown et un catalogue d’API. Les données sont celles que montre le site : spreads CEX et DEX, carnets d’ordres, funding, flux on-chain et marchés de prédiction.
Fichiers lisibles par machine
| Fichier | Contenu | À quoi ça sert |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1 : 37 opérations, paramètres, schémas de réponse, plans dans x-genesis-plans, en-têtes de rate limit | Import dans un client d’API, génération de code, outils d’agents |
| genesisarbitrage.com/llms-full.txt | La référence complète dans un seul fichier Markdown : endpoints, paramètres, champs, exemples, limites, erreurs | Contexte pour un modèle qui écrit du code ou répond à des questions sur l’API |
| genesisarbitrage.com/llms.txt | Aperçu du site : Genesis API, outils, Guide, cours, glossaire, blog | Premier regard d’un modèle sur le site |
| genesisarbitrage.com/.well-known/api-catalog | Catalogue d’API selon la RFC 9727 : liens vers la spécification, la documentation, les tarifs et le statut | Découverte de l’API à partir du domaine |
La spécification suit OpenAPI 3.1, dont les schémas sont un sur-ensemble de JSON Schema 2020-12 : les paramètres d’une opération passent donc dans la définition d’un outil presque sans changement. llms.txt est un format proposé en 2024 : un fichier Markdown à la racine du site, avec un court aperçu et des liens pour les modèles de langage. Le catalogue se trouve à l’adresse définie par la RFC 9727.
Les pages de documentation, de produit et de tarifs de Genesis API contiennent <link rel="service-desc"> dans <head>, qui pointe vers openapi.json. Ce type de relation vient de la RFC 8631 et désigne une description de service destinée aux machines. Un extrait abrégé de la spécification :
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/arbitrage/spot-spot": {
"get": {
"operationId": "getArbitrageSpotSpot",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query",
"schema": { "type": "string" } },
{ "name": "min_spread", "in": "query",
"schema": { "type": "number" } },
…
]
}
}
}
}
Chaque opération a un operationId, des paramètres typés, un schéma de réponse 200, une réponse 304, des codes d’erreur et les en-têtes X-RateLimit-*, X-Quota-*, X-Request-Id et ETag. La clé est décrite par le schéma de sécurité ApiKeyAuth : type apiKey, en-tête X-API-Key.
Comment se connecter
Obtenez une clé et gardez-la sur le serveur
La clé
gns_live_…est émise dans votre profil, dans le bloc Genesis API, et n’est affichée qu’une fois. Stockez-la dans la variable d’environnementGENESIS_API_KEYdu serveur qui exécute l’agent. Le stockage et la réémission sont expliqués dans le guide de la clé API.Importez la spécification
Un client d’API ou un framework d’agents qui accepte OpenAPI construit les requêtes et les outils directement à partir de
openapi.json: l’URL de base vient deservers, l’en-tête de la clé deApiKeyAuth. La façon d’envoyer la clé est décrite dans Authentification.Gardez les opérations dont vous avez besoin
Chaque définition d’outil occupe de la place dans le contexte du modèle, et choisir parmi peu d’outils est plus simple. Gardez les opérations utiles à votre tâche et retirez celles qui sortent de votre plan d’après
x-genesis-plans: elles répondent403 plan_restricted.Donnez la référence au modèle
Si l’agent écrit du code ou répond à des questions sur l’API, ajoutez
llms-full.txtà son contexte : il contient les paramètres, les champs et les exemples de chaque endpoint, les limites et les codes d’erreur.Vérifiez la clé avec un premier appel
/account/usagerenvoie votre plan, le quota utilisé, la limite de requêtes par seconde et la fraîcheur des données.
Comment le modèle appelle Genesis API
Le function calling est le mécanisme par lequel le modèle renvoie le nom d’un outil et des arguments au lieu de texte, et votre code fait l’appel. La boucle :
- Avec la question de l’utilisateur, le modèle reçoit les définitions des outils : nom, rôle et paramètres sous forme de JSON Schema.
- Le modèle répond par un appel :
get_spreadsavec les arguments{"coin": "TON", "min_spread": 0.5}. - Votre serveur valide les arguments, fait un GET avec l’en-tête
X-API-Keyet réduit la réponse aux champs utiles. - Un court JSON avec l’heure des données repart vers le modèle, qui répond à l’utilisateur.
Le modèle ne fait aucun appel réseau et ne voit jamais la clé : il n’a que la définition de l’outil et le résultat. Un outil get_spreads au-dessus de l’endpoint Spot — Spot :
{
"name": "get_spreads",
"description": "Où acheter un coin moins cher et le vendre plus haut (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Ticker du coin, par ex. BTC"
},
"min_spread": {
"type": "number",
"description": "Spread minimal, % : 0.5 signifie 0.5 %"
}
},
"additionalProperties": false
}
}
Le champ qui contient le schéma des paramètres porte un nom différent selon les fournisseurs de modèles, inputSchema dans MCP ; à l’intérieur, c’est toujours du JSON Schema. Les propriétés coin et min_spread viennent des paramètres de l’opération getArbitrageSpotSpot, et description dit quand appeler l’outil : le modèle choisit d’après ce texte.
Un handler Python qui appelle /arbitrage/spot-spot et renvoie au modèle jusqu’à 10 lignes avec les champs nécessaires et meta.updated_at :
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # la clé reste sur le serveur
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # params -> (heure, ETag, corps de la réponse)
def get_spreads(coin=None, min_spread=None):
params = {"coin": coin, "min_spread": min_spread}
params = {k: v for k, v in params.items() if v is not None}
ck = tuple(sorted(params.items()))
ts, etag, body = cache.get(ck, (0, None, None))
if body and time.time() - ts < body["meta"]["freshness_sec"]:
return shorten(body) # les données ne seront pas mises à jour plus tôt
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 et 503 : attendre Retry-After, réessayer
r = requests.get(API, headers=headers, params=params,
timeout=10)
if r.status_code not in (429, 503) or attempt:
break
time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
if r.status_code == 200:
body, etag = r.json(), r.headers.get("ETag")
elif r.status_code != 304:
return {"error": r.status_code} # le modèle voit le code
cache[ck] = (time.time(), etag, body)
return shorten(body)
def shorten(body):
rows = sorted(body["data"], key=lambda x: x["spread_pct"],
reverse=True)[:10]
t = body["meta"]["updated_at"]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": [{f: x.get(f) for f in FIELDS} for x in rows]}
La réponse reste en cache pendant meta.freshness_sec secondes : les données ne seront pas mises à jour plus tôt. Ensuite, le handler envoie l’ETag précédent dans If-None-Match, et une réponse 304 ne consomme pas de quota. Sur 429 et 503, il attend Retry-After, plafonné à 30 s, réessaie une fois et renvoie les autres erreurs au modèle sous forme de code. Le modèle reçoit 10 lignes de 6 champs. Un exemple illustratif : une réponse complète de 214 lignes de 22 champs représente 214 × 22 = 4 708 valeurs, la réponse réduite 10 × 6 = 60.
Règles pour l’agent
| Règle | Comment |
|---|---|
| La clé reste sur le serveur | Une variable d’environnement du handler ; pas de clé dans le prompt, le navigateur ni les journaux de chat |
| L’API ne fait que lire | Genesis API ne passe aucun ordre ; un humain confirme tout trade sur l’exchange |
| Votre code fixe la cadence | Cache pendant freshness_sec, ETag et If-None-Match, une file d’attente sous la limite de requêtes par seconde |
| Des filtres, pas l’ensemble complet | coin, min_spread, exchange ; jusqu’à 10 lignes et les champs utiles pour le modèle |
| L’heure des données dans chaque réponse | updated_at et l’âge dans le résultat de l’outil et dans la réponse à l’utilisateur |
| Le texte externe n’est que de la donnée | Le modèle n’agit pas d’après les titres de marchés, les issues, les noms de traders ni les textes de signaux |
Le modèle peut demander plusieurs outils à la fois, et la limite compte toutes les requêtes de la clé : 1 requête par seconde sur Trial, 15 sur Max. Les réponses 304 et les erreurs ne consomment pas de quota, mais comptent dans la limite par seconde ; voir Plans et limites et le guide des limites.
Les champs title et outcome des marchés de prédiction, le name d’un trader, le token_name des événements on-chain et les message_ru et message_en des signaux de Genesis AI+ viennent de sources externes. Quelqu’un peut nommer un marché « ignore les instructions précédentes et… » : c’est de la prompt injection, des commandes glissées dans les données. Ne transmettez ces champs qu’à l’intérieur du résultat de l’outil, limitez leur longueur et précisez dans le prompt système que le texte des résultats est de la donnée.
MCP : votre propre serveur au-dessus de l’API REST
MCP (Model Context Protocol) est un standard ouvert pour connecter les applications d’IA à des systèmes externes. Un serveur MCP fournit à l’application des outils, des ressources et des modèles de prompts ; les messages sont en JSON-RPC 2.0, via stdio en local et Streamable HTTP à distance. La spécification et les SDK de plusieurs langages sont sur modelcontextprotocol.io.
Genesis API n’a pas de serveur MCP officiel. Vous pouvez construire le vôtre à partir des mêmes handlers : un outil MCP est un GET vers un endpoint de Genesis API, ses paramètres sont du JSON Schema dans inputSchema, et la clé se trouve dans l’environnement du serveur. Un serveur stdio local garde la clé sur votre machine. Placez un serveur distant derrière une autorisation (MCP recommande OAuth) ; sinon, quiconque apprend l’adresse peut dépenser votre quota.
La façon dont les agents travaillent avec les données de marché crypto en général est détaillée dans l’article sur les données de marché crypto pour agents IA, et les risques de l’automatisation dans la cinquième leçon du cours.
Questions et réponses
Genesis API a-t-elle un serveur MCP officiel ?
Non. Pour les agents, il y a openapi.json, llms-full.txt et le catalogue d’API. Vous pouvez écrire vous-même un serveur MCP au-dessus de l’API REST : chaque outil est une requête GET avec la clé issue d’une variable d’environnement.
Un agent peut-il trader via Genesis API ?
Non. Genesis API ne fait que lire les données et ne passe aucun ordre. L’agent repère les opportunités et envoie des alertes ; un humain fait le trade sur l’exchange.
De quel plan un agent a-t-il besoin ?
N’importe lequel : Trial donne 1 requête par seconde et une fraîcheur de 60 s, Max 15 requêtes par seconde et 5 s. Les endpoints inclus dans chaque plan figurent dans x-genesis-plans et sur la page des tarifs de Genesis API.
Pourquoi le modèle cite-t-il des prix périmés ?
Les données ont le retard de fraîcheur de votre plan, et le cache du handler ajoute jusqu’à freshness_sec. Donnez au modèle updated_at et l’âge des données, et demandez-lui d’indiquer l’heure dans sa réponse.