Genesis Arbitrage

Genesis Arbitrage · · 11 min de lecture

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

FichierContenuÀ quoi ça sert
genesisarbitrage.com/openapi.jsonOpenAPI 3.1 : 37 opérations, paramètres, schémas de réponse, plans dans x-genesis-plans, en-têtes de rate limitImport dans un client d’API, génération de code, outils d’agents
genesisarbitrage.com/llms-full.txtLa référence complète dans un seul fichier Markdown : endpoints, paramètres, champs, exemples, limites, erreursContexte pour un modèle qui écrit du code ou répond à des questions sur l’API
genesisarbitrage.com/llms.txtAperçu du site : Genesis API, outils, Guide, cours, glossaire, blogPremier regard d’un modèle sur le site
genesisarbitrage.com/.well-known/api-catalogCatalogue d’API selon la RFC 9727 : liens vers la spécification, la documentation, les tarifs et le statutDé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

  1. 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’environnement GENESIS_API_KEY du serveur qui exécute l’agent. Le stockage et la réémission sont expliqués dans le guide de la clé API.

  2. 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 de servers, l’en-tête de la clé de ApiKeyAuth. La façon d’envoyer la clé est décrite dans Authentification.

  3. 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épondent 403 plan_restricted.

  4. 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.

  5. Vérifiez la clé avec un premier appel

    /account/usage renvoie 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 :

  1. 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.
  2. Le modèle répond par un appel : get_spreads avec les arguments {"coin": "TON", "min_spread": 0.5}.
  3. Votre serveur valide les arguments, fait un GET avec l’en-tête X-API-Key et réduit la réponse aux champs utiles.
  4. 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ègleComment
La clé reste sur le serveurUne variable d’environnement du handler ; pas de clé dans le prompt, le navigateur ni les journaux de chat
L’API ne fait que lireGenesis API ne passe aucun ordre ; un humain confirme tout trade sur l’exchange
Votre code fixe la cadenceCache 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 completcoin, min_spread, exchange ; jusqu’à 10 lignes et les champs utiles pour le modèle
L’heure des données dans chaque réponseupdated_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éeLe 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.