Référence de l'outil Chandelier (OHLCV)

Cette page est la référence de l'outil pour** récupérer les données de chandelier (OHLCV) depuis le MCP de données de marché Cryptohopper**.

Nom de l'outil

get_candles

Objectif

Renvoie une série de chandeliers OHLCV (Ouverture, Haut, Bas, Clôture, Volume) pour une paire spécifiée sur un exchange spécifié à une période de temps spécifiée. Prend en charge les chandeliers actuels (en temps réel) sur tous les niveaux et les chandeliers historiques sur Explorer, Adventurer et Hero.

Arguments

Argument	Type	Requis	Description
exchange	string	Oui	Identifiant de l'exchange (en minuscules). Voir les exchanges pris en charge.
pair	string	Oui	Paire au format BASE/QUOTE.
timeframe	string	Oui	Taille de la barre. Voir les périodes de temps prises en charge ci-dessous.
limit	integer	Non	Nombre de chandeliers à renvoyer. La valeur par défaut et le maximum dépendent du niveau.
since	string (ISO-8601)	Non	Heure de début pour les requêtes historiques. Si omis, renvoie les limit barres les plus récentes.

Soit limit seul (barres récentes) ou since + limit (plage historique) peut être utilisé. limit seul est le cas le plus courant.

Périodes de temps prises en charge

Valeur	Durée
1m	1 minute
5m	5 minutes
15m	15 minutes
1h	1 heure
4h	4 heures
1d	1 jour

Les alias de période de temps hebdomadaire, mensuelle et autres ne sont pas pris en charge et seront rejetés. Toutes les périodes de temps prises en charge ne sont pas disponibles sur chaque exchange. Les combinaisons non prises en charge renvoient TIMEFRAME_NOT_SUPPORTED.

Schéma de réponse

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timeframe": "1h",
  "candles": [
    [1778540400000, 80214.00, 80820.50, 80120.00, 80651.42, 412.85, 318],
    [1778544000000, 80651.42, 80936.22, 80590.00, 80934.19, 298.12, 274]
  ]
}

Champs de niveau supérieur

Champ	Type	Description
exchange	string	L'identifiant de l'exchange d'où proviennent les données.
pair	string	La paire, au format BASE/QUOTE.
timeframe	string	La taille de la barre (par exemple 1h).
candles	array	Tableau d'enregistrements OHLCV, classés par ordre chronologique (du plus ancien au plus récent). Chaque enregistrement est lui-même un tableau de sept positions.

Champs d'enregistrement de chandelier

Chaque chandelier est un tableau avec les positions suivantes :

Index	Champ	Type	Description
0	timestamp	number	Heure d'ouverture de la barre (horodatage Unix en millisecondes).
1	open	number	Premier prix négocié dans la barre.
2	high	number	Prix négocié le plus élevé dans la barre.
3	low	number	Prix négocié le plus bas dans la barre.
4	close	number	Dernier prix négocié dans la barre (ou prix actuel, pour une barre ouverte).
5	volume	number	Volume de l'actif de base négocié dans la barre.
6	count	number	Nombre de transactions dans la barre.

Les prix et le volume sont renvoyés sous forme de nombres JSON. Les clients nécessitant une précision exacte doivent les convertir en type décimal immédiatement après l'analyse. Voir le modèle de données.

Ordre

Les chandeliers sont renvoyés dans l'ordre chronologique — la barre la plus ancienne en premier, la barre la plus récente en dernier. Cela correspond à ce que la plupart des bibliothèques d'indicateurs attendent en entrée.

Barres ouvertes vs. fermées

Le dernier élément du tableau de chandeliers est généralement la barre actuelle, ouverte — la barre dont la fenêtre de temps n'est pas encore terminée. Sa valeur de clôture reflète le prix actuel, pas une clôture finalisée. Toutes les barres antérieures sont fermées et immuables.

Les applications effectuant des calculs d'indicateurs (RSI, MACD, moyennes mobiles) doivent généralement opérer uniquement sur des barres fermées, en ignorant le dernier élément. L'utilisation de la barre ouverte introduit un bruit de look-ahead qui peut déstabiliser les signaux.

Coût

Scénario	Coût sur Pioneer	Coût sur Explorer/Adventurer	Coût sur Hero
Barre actuelle uniquement (temps réel)	1	1	1
Consultation d'historique court	N/A	5×	1×
Consultation d'historique long	N/A	20×	1×

La frontière entre consultation d'historique "court" et "long" est spécifique au niveau. Voir les limites de taux expliquées pour la matrice de coût exacte et des conseils pour rester efficace.

Accès aux niveaux pour les données historiques

Niveau	Consultation d'historique
Pioneer	Non disponible — barre actuelle uniquement
Explorer	Jusqu'à 90 jours
Adventurer	Jusqu'à 365 jours
Hero	Jusqu'à 3 ans

Les requêtes dépassant l'historique maximum du niveau renvoient HISTORY_LIMIT_EXCEEDED.

Guide de consultation

La plupart des analyses nécessitent beaucoup moins de chandeliers que ce que les utilisateurs demandent intuitivement. Consultations suggérées :

Indicateur	Barres minimum	Confortable
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Moyenne mobile (période N)	N	N + 50
Bandes de Bollinger (20, 2?)	20	100
ATR(14)	14	100

Récupérer plus de barres que nécessaire augmente le coût (les requêtes historiques sur Explorer/Adventurer peuvent coûter jusqu'à 20× un appel de base) sans améliorer la qualité de l'indicateur.

Exemples d'invocations

Barres récentes

Demandé dans un client MCP :

Récupère les 100 derniers chandeliers d'1 heure pour ETH/USDT sur Binance.

L'agent invoque get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100).

Plage historique

Récupère les chandeliers journaliers pour BTC/USDT sur Binance à partir du 01/01/2026.

L'agent invoque get_candles(exchange="binance", pair="BTC/USDT", timeframe="1d", since="2026-01-01T00:00:00Z", limit=120).

Multi-périodes

Récupère les chandeliers 1h et 4h pour SOL/USDT sur Binance, 100 derniers pour chacun. Calcule le RSI sur les deux périodes de temps.

L'agent invoque get_candles deux fois avec des valeurs de timeframe différentes. Le calcul du RSI se produit dans le raisonnement du modèle, pas dans un appel d'outil.

Erreurs

Code d'erreur	Cause
UNAUTHORIZED	Clé API invalide ou révoquée.
EXCHANGE_NOT_SUPPORTED	Exchange non disponible sur le niveau actif.
PAIR_NOT_FOUND	La paire n'existe pas sur l'exchange spécifié.
TIMEFRAME_NOT_SUPPORTED	La période de temps demandée n'est pas prise en charge pour cette paire/exchange.
HISTORY_LIMIT_EXCEEDED	La consultation demandée dépasse l'historique maximum du niveau.
INVALID_PARAMETER	L'argument a échoué à la validation (par exemple limit hors limites, alias de période de temps non reconnu).
EXCHANGE_UNAVAILABLE	L'exchange en amont ne répond pas.
DATA_UNAVAILABLE	Les chandeliers demandés ne sont pas disponibles depuis l'exchange en amont pour cette plage.
RATE_LIMIT_EXCEEDED	Limite de taux à intervalle court atteinte.
QUOTA_EXCEEDED	Quota hebdomadaire atteint.