Référence de l'outil carnet d'ordres

Cette page est la référence de l'outil pour récupérer des instantanés de carnets d'ordres depuis le Cryptohopper Market Data MCP. Pour le guide conceptuel, voir un guide pratique des données de carnets d'ordres crypto.

Nom de l'outil

get_orderbook

Objectif

Renvoie un instantané ponctuel du carnet d'ordres pour une paire spécifiée sur un exchange spécifié. Contient les offres et demandes actuelles en attente avec le prix et la taille par niveau.

Arguments

Argument	Type	Requis	Description
exchange	string	Oui	Identifiant de l'exchange (minuscules).
pair	string	Oui	Paire au format BASE/QUOTE (par ex. BTC/USDT).
depth	integer	Non	Nombre maximum de niveaux à renvoyer par côté. Par défaut, dépend de l'exchange. La limite supérieure dépend de la source en amont.

Schéma de réponse

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timestamp": "2026-04-24T14:03:00Z",
  "bids": [
    [80934.18, 5.32816],
    [80930.05, 1.10000],
    [80925.40, 3.40000]
  ],
  "asks": [
    [80936.22, 1.20000],
    [80940.00, 2.50000],
    [80945.75, 0.80000]
  ]
}

Champs

Champ	Type	Description
exchange	string	L'identifiant de l'exchange d'où proviennent les données.
pair	string	La paire, au format BASE/QUOTE.
timestamp	string (ISO-8601)	Heure de capture de l'instantané.
bids	array	Tableau de tuples [prix, taille], triés par prix décroissant (offre la plus élevée en premier).
asks	array	Tableau de tuples [prix, taille], triés par prix croissant (demande la plus basse en premier).

Les prix et les tailles sont renvoyés sous forme de nombres JSON. Les clients qui nécessitent une précision exacte pour les calculs liés à l'exécution doivent les convertir en type décimal immédiatement après l'analyse. Voir modèle de données pour les conventions.

Ordre

• Les bids sont triés par prix décroissant. La première entrée est la meilleure offre (le prix le plus élevé qu'un acheteur propose).
• Les asks sont triés par prix croissant. La première entrée est la meilleure demande (le prix le plus bas qu'un vendeur propose).

Le spread est la différence entre asks[0] et bids[0]. Le point médian est leur moyenne.

Profondeur

La profondeur du carnet d'ordres varie selon l'exchange. Le MCP renvoie ce que l'exchange en amont expose via son API publique.

Profondeur typique (niveaux par côté)	Exchanges
100	La plupart des exchanges majeurs par défaut
Jusqu'à 500 ou plus	Certains exchanges, lorsque la profondeur est demandée

Les demandes pour plus de profondeur que ce que la source en amont prend en charge sont limitées au maximum en amont. L'argument depth est au mieux de nos efforts, non garanti.

Fraîcheur

Les carnets d'ordres sont capturés au moment de la demande. Le champ timestamp reflète le moment où l'instantané a été lu depuis l'exchange en amont.

Les carnets d'ordres deviennent obsolètes très rapidement — généralement en quelques secondes sur les paires liquides. Les clients ne doivent pas mettre en cache les réponses de carnets d'ordres pour les utiliser dans les décisions d'exécution.

Coût

Aspect	Coût
Par invocation	1 unité d'appel sur tous les tiers
Variante historique	Non pris en charge — l'historique des carnets d'ordres n'est pas disponible via le MCP

Exemples d'invocations

Instantané de base

Demandé dans un client MCP :

Montre-moi le carnet d'ordres actuel pour BTC/USDT sur Binance.

L'agent invoque get_orderbook(exchange="binance", pair="BTC/USDT") et renvoie un instantané.

Profondeur personnalisée

Récupère les 50 premiers niveaux du carnet d'ordres ETH/USDT sur Kraken.

L'agent invoque get_orderbook(exchange="kraken", pair="ETH/USDT", depth=50).

Métriques dérivées

Le MCP renvoie des niveaux bruts ; les métriques dérivées (spread, profondeur dans X%, slippage pour une taille d'ordre donnée) sont calculées par le modèle ou par le code appelant.

Erreurs

Code d'erreur	Cause
UNAUTHORIZED	Clé API invalide ou révoquée.
EXCHANGE_NOT_SUPPORTED	Exchange non disponible sur le tier actif.
PAIR_NOT_FOUND	La paire n'existe pas sur l'exchange spécifié.
INVALID_PARAMETER	L'argument a échoué la validation (par ex. symbole de paire mal formé, profondeur négative).
EXCHANGE_UNAVAILABLE	L'exchange en amont ne répond pas.
RATE_LIMIT_EXCEEDED	Limite de taux à court intervalle atteinte.
QUOTA_EXCEEDED	Quota hebdomadaire atteint.

Accès par tier

Les requêtes de carnets d'ordres sont disponibles sur tous les tiers (Pioneer, Explorer, Adventurer, Hero).

La restriction de couverture de l'exchange s'applique : sur Pioneer, les requêtes de carnets d'ordres sont limitées à Binance, Coinbase et Kraken. Sur Explorer et au-dessus, davantage d'exchanges sont disponibles.