Données de marché crypto pour agents IA : API, function calling, MCP et llms.txt
En bref
- Un modèle de langage ne connaît le marché que jusqu’à la date limite de son entraînement. Il obtient les prix, spreads et taux de financement (funding) actuels grâce à des outils : le modèle choisit l’appel et ses arguments, et votre code fait la requête à l’API.
- Un outil bâti sur une API de données de marché doit rester étroit : un endpoint, des filtres en paramètres, quelques lignes avec les champs utiles et l’heure des données dans le résultat. Les définitions d’outils viennent de la spécification OpenAPI, et MCP branche les mêmes outils sur tout client compatible.
- La clé reste sur votre serveur, le texte issu de données externes n’atteint le modèle que dans des résultats d’outils, et un humain confirme chaque opération. Genesis API est en lecture seule et publie openapi.json, llms-full.txt et un catalogue d’API pour les agents.
Un agent IA obtient des données de marché crypto par des outils : le modèle décide de quelles données il a besoin, votre code appelle une API crypto et renvoie un court JSON avec les prix, les spreads et l’heure de construction des données. Les outils se connectent soit par le function calling de l’API du modèle, soit par un serveur MCP, et les deux reposent sur une API REST ordinaire.
Les exemples utilisent Genesis API, une API REST en lecture seule avec des données CEX, DEX, on-chain et de marchés prédictifs. Pour les API crypto en général et la façon de les comparer, voir API crypto : types d’API de données de marché et comment choisir.
Pourquoi le modèle ne connaît pas les prix actuels
Un modèle de langage est entraîné sur des textes collectés jusqu’à une certaine date, sa date limite de connaissances. Il ignore tout des listings, des taux et des prix postérieurs, et un prix du BTC cité de mémoire est un chiffre tiré d’un texte d’entraînement de date inconnue. Le modèle ne connaît pas non plus l’heure actuelle si vous ne la lui transmettez pas dans la requête.
Pour l’arbitrage, une réponse de mémoire est inutile : un spread entre exchanges dure quelques minutes, et le taux de financement (funding) change à chaque période de règlement, toutes les 8, 4 ou 1 heures. Les chiffres en direct ne viennent que d’un outil : une documentation d’API dans le contexte apprend au modèle les chemins et les paramètres, mais elle ne contient aucun prix.
| Ce dont le modèle a besoin | D’où cela vient | Exemple |
|---|---|---|
| Chemins, paramètres et champs de l’API | Documentation dans le contexte | llms-full.txt, openapi.json |
| Prix, spreads, taux | Appel d’un outil | GET /funding/spread?coin=TON |
| Heure actuelle et âge des données | Prompt système et résultat de l’outil | updated_at, age_sec |
Comment fonctionne le function calling
Le function calling est un mode dans lequel le modèle renvoie le nom d’un outil et ses arguments au lieu de texte, et votre code exécute la requête. Exemple illustratif : un utilisateur demande où se trouve en ce moment le plus grand spread de funding pour TON. L’appel et le résultat, de façon schématique :
{
"tool_call": {
"name": "get_funding",
"arguments": { "coin": "TON" }
},
"tool_result": {
"updated_at": 1794675860,
"age_sec": 12,
"rows": [
{
"coin": "TON",
"spread_pct": 0.04,
"pair": ["Bitget", "Bybit"],
"funding_pct": [0.05, 0.01],
"interval": ["8h", "8h"]
}
]
}
}
- L’application envoie au modèle la question et les définitions des outils : nom, rôle et schéma des arguments en JSON Schema.
- Le modèle renvoie un appel
get_fundingavec les arguments{"coin": "TON"}. - Votre code valide les arguments, envoie
GET /funding/spread?coin=TONavec l’en-têteX-API-Keyet réduit la réponse. - Le résultat retourne au modèle, qui répond : Bitget et Bybit, 0,05 % et 0,01 % par 8 heures, un écart de 0,04 %, données vieilles de 12 secondes.
- Si les données ne suffisent pas, le modèle appelle l’outil suivant.
Le modèle ne fait aucune requête réseau et ne voit jamais la clé API. Les noms de champs dépendent de l’API du modèle : dans l’API Claude, le schéma se trouve dans input_schema, l’appel arrive comme un bloc tool_use et le résultat repart comme un bloc tool_result, alors que MCP nomme le schéma inputSchema. Dans les deux cas, c’est du JSON Schema.
Comment concevoir des outils sur une API de données de marché
Un outil, une tâche
Le modèle choisit un outil d’après sa description, donc des outils étroits fonctionnent plus fiablement qu’un call_api(path, params) générique. Choisir parmi cinq à sept outils conçus pour les tâches de l’agent est plus facile que de choisir parmi les 37 opérations de la spécification.
| Outil | Endpoint de Genesis API | Plans |
|---|---|---|
get_spreads | /arbitrage/spot-spot | Tous |
get_funding | /funding/spread | Tous |
get_prediction_arbs | /predictions/arbitrage | Start, Pro, Max |
get_book | /orderbooks/book | Pro, Max |
La description indique quand appeler l’outil et dans quelles unités sont les nombres : dans Genesis API, les spreads et les taux sont des pourcentages, donc 0.92 signifie 0,92 %.
Des filtres en paramètres, la validation dans le code
Les filtres de l’API comme coin, exchange et min_spread deviennent des paramètres de l’outil. Le modèle les remplit d’après la question, le handler les vérifie par rapport à une liste autorisée de paramètres, de types et de valeurs, et enum énumère les valeurs permises : pour /orderbooks/book, market vaut seulement spot ou futures. Le modèle ne construit jamais le chemin de la requête, et le schéma rejette les champs superflus (additionalProperties: false).
Une réponse filtrée arrive sans ETag, donc chaque interrogation filtrée répétée coûte un appel : il n’y a pas de 304 gratuit. Si l’agent a besoin de dizaines de coins, il est moins cher de garder en local le jeu de données complet non filtré et de l’interroger avec If-None-Match.
Des résultats compacts
Exemple illustratif : la réponse complète non filtrée de /funding/spread couvre 1 000 coins. Pour un coin présent sur 10 exchanges, une ligne contient 2 + 10 + 8 × 5 = 52 valeurs : le coin, le spread, 10 champs de la meilleure paire dans best et 5 champs pour chacun des 8 autres exchanges dans others. La réponse entière fait 1 000 × 52 = 52 000 valeurs, alors qu’une réponse sur les meilleures paires demande 5 lignes de 8 valeurs : 5 × 8 = 40.
Les définitions d’outils et les résultats entrent dans le contexte à chaque étape : l’API Claude les facture comme des tokens d’entrée.
Heure des données et fraîcheur
Le handler place dans le résultat updated_at, l’heure de construction des données issue de meta.updated_at en secondes unix, et age_sec. Le modèle peut alors dire « données vieilles de 12 secondes » au lieu de faire passer le spread d’hier pour un spread actuel.
La fraîcheur des données dépend du plan : meta.freshness_sec va de 60 s sur Trial à 5 s sur Max. Tant que cet intervalle n’est pas écoulé, l’API renvoie le même instantané, donc le handler met la réponse en cache pendant freshness_sec secondes. Les carnets d’ordres ont leur propre horloge : book_ts, age_sec et un indicateur stale pour les carnets de plus de 30 s.
Exemple : l’outil get_funding
La définition ci-dessous utilise le format MCP ; pour l’API Claude, le même contenu va dans input_schema. Le handler applique limit lui-même : l’API n’a pas ce paramètre.
{
"name": "get_funding",
"description": "Where funding is higher or lower: best exchange pair",
"inputSchema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. TON"
},
"min_spread": {
"type": "number",
"minimum": 0,
"description": "Minimum spread, %: 0.05 means 0.05%"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "How many rows to return, 5 by default"
}
},
"additionalProperties": false
}
}
Le handler Python : un cache pour freshness_sec, une courte pause sur 429 et 503, un log sans la clé et un résultat compact avec l’heure des données.
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # la clé reste sur le serveur
cache = {} # paramètres de la requête -> (heure de réception, corps de la réponse)
def get_funding(coin=None, min_spread=None, limit=5):
p = {"coin": coin and coin.upper(), "min_spread": min_spread}
p = {k: v for k, v in p.items() if v}
ck = tuple(sorted(p.items()))
got, body = cache.get(ck, (0, None))
if not body or time.time() - got >= body["meta"]["freshness_sec"]:
for attempt in range(2): # 429, 503 : courte attente, une nouvelle tentative
r = requests.get(URL, params=p, timeout=10,
headers={"X-API-Key": KEY})
wait = int(r.headers.get("Retry-After", "0"))
if attempt or wait > 5 or r.status_code not in (429, 503):
break
time.sleep(wait)
logging.info("get_funding %s -> %s id=%s", p, r.status_code,
r.headers.get("X-Request-Id")) # pas de clé dans le log
if r.status_code != 200:
return {"error": r.status_code} # 401, 403, 429, 503
body = r.json()
cache[ck] = (time.time(), body)
t = body["meta"]["updated_at"]
top = sorted(body["data"], key=lambda x: -x["spread_pct"])
rows = [{"coin": x["coin"], "spread_pct": x["spread_pct"],
"pair": [x["best"]["exchange_1"], x["best"]["exchange_2"]],
"funding_pct": [x["best"]["funding_1_pct"],
x["best"]["funding_2_pct"]],
"interval": [x["best"]["interval_1"],
x["best"]["interval_2"]]}
for x in top[:min(max(int(limit), 1), 10)]]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": rows}
Le handler n’attend pas les pauses de plus de 5 secondes : une fois le quota épuisé, Retry-After pointe vers la réinitialisation, qui peut être à plusieurs jours. Le modèle reçoit le code d’état et explique à l’utilisateur ce qui s’est passé : 403 signifie plan_restricted, un endpoint hors du plan (erreurs de Genesis API).
OpenAPI comme source des définitions d’outils
OpenAPI est un standard de description lisible par machine des API HTTP : une opération est décrite par un operationId, un court summary et des paramètres avec leurs schémas. En version 3.1, le Schema Object est un sur-ensemble de JSON Schema 2020-12 (spécification OpenAPI 3.1), et MCP lit inputSchema comme du JSON Schema 2020-12 par défaut. Les paramètres passent donc dans un outil sans conversion.
Le script construit les outils à partir de la spécification de Genesis API : il prend les opérations voulues, ignore celles qui sont hors de votre plan d’après x-genesis-plans et reprend les paramètres de requête et de chemin. Les en-têtes relèvent du handler.
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted : operationId -> nom de l’outil ; plan : trial … max."""
spec = requests.get(SPEC, timeout=15).json()
tools, routes = [], {}
for path, item in spec["paths"].items():
op = item.get("get", {})
name = wanted.get(op.get("operationId"))
if not name or plan not in op.get("x-genesis-plans", []):
continue # non voulue ou hors plan : 403 plan_restricted
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # le handler envoie X-API-Key, If-None-Match
props[prm["name"]] = {**prm["schema"],
"description": prm["description"]}
if prm.get("required"):
required.append(prm["name"])
tools.append({
"name": name,
"description": op["description"].split("\n\n")[0],
"inputSchema": {"type": "object", "properties": props,
"required": required,
"additionalProperties": False}})
routes[name] = path # nom de l’outil -> chemin de l’endpoint
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
getFundingSpread devient un outil get_funding avec les paramètres coin et min_spread. Si vous passez toutes les opérations, Trial en garde 11 sur 37 et Start en garde 16. Le dictionnaire routes stocke le chemin de chaque outil.
MCP : votre propre serveur au-dessus d’une API REST
MCP (Model Context Protocol) est un standard ouvert pour connecter des applications d’IA à des données et à des outils. Anthropic l’a publié en open source le 25 novembre 2024 (annonce d’Anthropic) et, le 9 décembre 2025, l’a confié à l’Agentic AI Foundation, un fonds sous l’égide de la Linux Foundation (blog MCP).
L’application qui porte le modèle, l’hôte, crée un client MCP par serveur. Un serveur expose des outils, des ressources et des modèles de prompts via JSON-RPC 2.0 : un serveur local via stdio, un serveur distant via Streamable HTTP, pour lequel MCP recommande d’obtenir les tokens par OAuth (architecture MCP).
| Function calling | MCP | |
|---|---|---|
| Où les outils sont définis | Dans la requête à l’API du modèle | Sur le serveur ; le client les récupère avec tools/list |
| Qui exécute l’appel | Le code de votre application | Le serveur MCP, sur une requête tools/call |
| Où cela fonctionne | Dans l’application où vous avez écrit la boucle | Dans tout client compatible MCP |
Envelopper une API REST dans un serveur MCP demande quatre étapes :
Choisir les opérations
Prenez 3 à 7 opérations pour la tâche de l’agent ; construisez les noms, descriptions et paramètres des outils à partir d’OpenAPI, comme dans le script ci-dessus.
Renvoyer la liste sur tools/list
Le serveur renvoie
name,descriptionetinputSchemapour chaque outil.Traiter tools/call
Validez les arguments, faites une requête GET avec la clé de l’environnement du serveur et renvoyez un JSON compact dans un bloc
content. Renvoyez une erreur d’API avecisError: true: le modèle s’en sert pour corriger ses arguments.Choisir le transport
Avec stdio, le serveur tourne sur votre machine et la clé ne la quitte jamais. Placez un serveur Streamable HTTP distant derrière une autorisation, sinon quiconque apprend l’URL dépensera votre quota.
Des SDK MCP officiels existent pour 10 langages, de Python et TypeScript à Go et Rust (liste des SDK).
llms.txt et llms-full.txt
llms.txt est un fichier Markdown placé à /llms.txt qui aide les modèles de langage à utiliser un site web. Jeremy Howard a proposé le format le 3 septembre 2024 (llmstxt.org) : la seule partie obligatoire est un H1 avec le nom, suivi d’un résumé en citation et de sections avec des liens vers les versions Markdown des pages.
La proposition ne définit pas llms-full.txt : ce nom désigne une documentation entière dans un seul fichier Markdown, et le site de documentation de MCP, par exemple, le publie. Le modèle n’a pas besoin de suivre des liens, puisque toute la documentation arrive dans son contexte.
Sécurité de l’agent
Gardez la clé dans une variable d’environnement sur le serveur : elle ne doit apparaître ni dans les prompts, ni dans les navigateurs, ni dans les logs. Une clé Genesis API est en lecture seule : elle ne peut ni passer d’ordre ni retirer des fonds, et une fuite vous coûte du quota. Remplacez une clé divulguée avec Réémettre dans votre profil (stockage des clés).
L’injection de prompt est une instruction destinée au modèle cachée dans les données. Le nom d’un token est choisi par celui qui l’a déployé et le nom d’un trader par le trader, donc un champ peut contenir « ignore previous instructions ». Dans Genesis API, le texte externe arrive dans les champs title et outcome des marchés prédictifs, le name des traders, le token_name on-chain et les message_ru et message_en des signaux de Genesis AI+ : indiquez dans le prompt système que les résultats d’outils ne sont que des données.
La spécification MCP exige que les serveurs valident les entrées des outils, limitent la fréquence des invocations et assainissent les sorties, et conseille aux clients de confirmer les opérations sensibles et de journaliser l’usage des outils (outils MCP). Journalisez le X-Request-Id : avec lui, l’heure en UTC, l’endpoint et le statut, le support peut retrouver la requête.
Les risques de l’automatisation sont traités dans la leçon 5 du cours API crypto.
Coûts et limites
Seule une réponse 200 consomme le quota de Genesis API ; 304 et les erreurs sont gratuits, mais comptent dans la limite de débit (rate limit) par seconde. Au-delà des limites, le serveur répond 429 et ne facture rien.
| Plan | Prix | Quota et débit | Fraîcheur |
|---|---|---|---|
| Trial | 20 $/mois | 500 000 appels, 1 req/s | 60 s |
| Start | 50 $/mois | 2 M d’appels, 2 req/s | 30 s |
| Pro | 100 $/mois | 5 M d’appels, 5 req/s | 10 s |
| Max | 200 $/mois | 10 M d’appels, 15 req/s | 5 s |
Exemple illustratif : 500 questions par jour avec 3 appels d’outils chacune font 500 × 3 = 1 500 appels par jour et 1 500 × 30 = 45 000 sur 30 jours, soit 9 % du quota Trial. Le cache couvre les répétitions avec les mêmes paramètres pendant freshness_sec, et un plafond d’appels d’outils par réponse empêche une boucle de dévorer le quota.
Interroger plus souvent que meta.freshness_sec n’apporte aucun nouvel instantané. L’interrogation économique avec ETag et les nouvelles tentatives sont expliquées dans Comment interroger une API crypto sans atteindre les limites, les limites dans le guide Limites de Genesis API. Si l’agent n’a besoin que de règles et d’aucun modèle, un bot d’arbitrage crypto en Python est plus simple.
Genesis API pour les agents IA
Genesis API est une API REST avec les données de Genesis Arbitrage : spreads CEX et DEX, carnets d’ordres, funding, open interest, cross-chain, flux on-chain, marchés prédictifs, surebets de bookmakers et signaux d’IA. Les requêtes sont des HTTP GET avec l’en-tête X-API-Key, les réponses sont du JSON avec data et meta (format de réponse), et aucun SDK n’est nécessaire.
Publié pour les agents :
openapi.json— OpenAPI 3.1 : 37 opérations, schémas de réponse et plans dansx-genesis-plans;llms-full.txt— la documentation complète dans un seul fichier Markdown ;llms.txt— une présentation du site pour les modèles de langage ;/.well-known/api-catalog— un catalogue au sens de la RFC 9727 qui renvoie vers la spécification, la documentation et la page d’état.
Il n’existe ni serveur MCP officiel, ni WebSocket, ni endpoints de trading : l’agent lit les données, et les opérations restent à un humain. La mise en place pas à pas est décrite dans le guide Genesis API pour les agents IA.
Questions et réponses
Un agent IA peut-il trader des cryptos tout seul ?
Seulement si vous lui donnez une API de trading d’exchange, et c’est votre code et votre risque. Pas via Genesis API : elle ne fait que lire des données. La spécification MCP dit qu’un humain doit toujours pouvoir refuser un appel d’outil ; pour les opérations, posez la règle qu’un humain confirme chaque ordre.
De quel plan de Genesis API un agent IA a-t-il besoin ?
Trial, à 20 $ par mois, couvre les spreads CEX, le funding et l’open interest. Start ajoute les actions, les sections on-chain et l’arbitrage des marchés prédictifs dans les modes exact et dutch, tandis que Pro et Max ouvrent tout, y compris DEX et carnets d’ordres. La vitesse de réaction dépend de la limite par seconde et de la fraîcheur du plan ; le contenu des plans est sur la page tarifs de Genesis API.
Où obtenir la spécification de Genesis API pour un agent ?
OpenAPI 3.1 se trouve à genesisarbitrage.com/openapi.json, et la documentation pour le modèle à genesisarbitrage.com/llms-full.txt. Un agent peut aussi trouver les deux via le catalogue /.well-known/api-catalog.
Genesis API a-t-elle un serveur MCP ?
Il n’y en a pas d’officiel. Vous construisez le vôtre à partir des mêmes handlers : un outil MCP est une requête GET vers un endpoint avec la clé issue de l’environnement du serveur. Un exemple Python minimal se trouve dans l’entrée MCP du glossaire.