Riferimento strumento Candle (OHLCV)

Questa pagina è il riferimento dello strumento per** recuperare dati candle (OHLCV) dal Cryptohopper Market Data MCP**.

Nome dello strumento

get_candles

Scopo

Restituisce una serie di candele OHLCV (Open, High, Low, Close, Volume) per una coppia specificata su un exchange specificato con un timeframe specificato. Supporta candele correnti (in tempo reale) su tutti i livelli e candele storiche su Explorer, Adventurer e Hero.

Argomenti

Argomento	Tipo	Obbligatorio	Descrizione
exchange	string	Sì	Identificativo dell'exchange (minuscolo). Vedi exchange supportati.
pair	string	Sì	Coppia in formato BASE/QUOTE.
timeframe	string	Sì	Dimensione della barra. Vedi timeframe supportati sotto.
limit	integer	No	Numero di candele da restituire. Il valore predefinito e massimo dipendono dal livello.
since	string (ISO-8601)	No	Ora di inizio per query storiche. Se omesso, restituisce le ultime barre limit.

Può essere utilizzato solo limit (barre recenti) oppure since + limit (intervallo storico). Il solo limit è il caso più comune.

Timeframe supportati

Valore	Durata
1m	1 minuto
5m	5 minuti
15m	15 minuti
1h	1 ora
4h	4 ore
1d	1 giorno

Gli alias di timeframe settimanali, mensili e altri non sono supportati e verranno rifiutati. Non tutti i timeframe supportati sono disponibili su ogni exchange. Le combinazioni non supportate restituiscono TIMEFRAME_NOT_SUPPORTED.

Schema della risposta

{
  "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]
  ]
}

Campi di livello superiore

Campo	Tipo	Descrizione
exchange	string	L'identificativo dell'exchange da cui provengono i dati.
pair	string	La coppia, in formato BASE/QUOTE.
timeframe	string	La dimensione della barra (es. 1h).
candles	array	Array di record OHLCV, ordinati cronologicamente (dal più vecchio al più recente). Ogni record è esso stesso un array di sette posizioni.

Campi del record candela

Ogni candela è un array con le seguenti posizioni:

Indice	Campo	Tipo	Descrizione
0	timestamp	number	Orario di apertura della barra (timestamp Unix in millisecondi).
1	open	number	Primo prezzo scambiato nella barra.
2	high	number	Prezzo più alto scambiato nella barra.
3	low	number	Prezzo più basso scambiato nella barra.
4	close	number	Ultimo prezzo scambiato nella barra (o prezzo corrente, per una barra aperta).
5	volume	number	Volume dell'asset base scambiato nella barra.
6	count	number	Numero di trades nella barra.

I prezzi e il volume sono restituiti come numeri JSON. I client che richiedono precisione esatta dovrebbero convertirli in un tipo decimale immediatamente dopo il parsing. Vedi modello dati.

Ordinamento

Le candele sono restituite in ordine cronologico — la barra più vecchia per prima, la barra più recente per ultima. Questo corrisponde a ciò che la maggior parte delle librerie di indicatori si aspetta come input.

Barre aperte vs. chiuse

L'ultimo elemento dell'array candles è tipicamente la barra corrente, aperta — la barra la cui finestra temporale non è ancora completata. Il suo valore close riflette il prezzo corrente, non una chiusura finalizzata. Tutte le barre precedenti sono chiuse e immutabili.

Le applicazioni che eseguono calcoli di indicatori (RSI, MACD, medie mobili) dovrebbero tipicamente operare solo sulle barre chiuse, ignorando l'ultimo elemento. L'utilizzo della barra aperta introduce rumore look-ahead che può destabilizzare i segnali.

Costo

Scenario	Costo su Pioneer	Costo su Explorer/Adventurer	Costo su Hero
Solo barra corrente (tempo reale)	1	1	1
Lookback storico breve	N/A	5×	1×
Lookback storico lungo	N/A	20×	1×

Il confine tra lookback "breve" e "lungo" è specifico per livello. Vedi limiti di velocità spiegati per la matrice dei costi esatta e la guida per rimanere efficienti.

Accesso ai dati storici per livello

Livello	Lookback storico
Pioneer	Non disponibile — solo barra corrente
Explorer	Fino a 90 giorni
Adventurer	Fino a 365 giorni
Hero	Fino a 3 anni

Le richieste che superano la cronologia massima del livello restituiscono HISTORY_LIMIT_EXCEEDED.

Guida al lookback

La maggior parte delle analisi richiede molte meno candele di quelle che gli utenti intuitivamente richiedono. Lookback consigliati:

Indicatore	Barre minime	Confortevole
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Media mobile (periodo N)	N	N + 50
Bande di Bollinger (20, 2?)	20	100
ATR(14)	14	100

Recuperare più barre del necessario aumenta il costo (le query storiche su Explorer/Adventurer possono costare fino a 20× una chiamata di base) senza migliorare la qualità dell'indicatore.

Esempi di invocazione

Barre recenti

Richiesto in un client MCP:

Recupera le ultime 100 candele da 1 ora per ETH/USDT su Binance.

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

Intervallo storico

Recupera candele giornaliere per BTC/USDT su Binance dal 01-01-2026 in poi.

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

Multi-timeframe

Recupera candele 1h e 4h per SOL/USDT su Binance, ultime 100 ciascuna. Calcola RSI su entrambi i timeframe.

L'agente invoca get_candles due volte con valori timeframe diversi. Il calcolo RSI avviene nel ragionamento del modello, non in una chiamata dello strumento.

Errori

Codice errore	Causa
UNAUTHORIZED	Chiave API non valida o revocata.
EXCHANGE_NOT_SUPPORTED	Exchange non disponibile sul livello attivo.
PAIR_NOT_FOUND	La coppia non esiste sull'exchange specificato.
TIMEFRAME_NOT_SUPPORTED	Il timeframe richiesto non è supportato per questa coppia/exchange.
HISTORY_LIMIT_EXCEEDED	Il lookback richiesto supera la cronologia massima del livello.
INVALID_PARAMETER	L'argomento non ha superato la validazione (es. limit fuori intervallo, alias timeframe non riconosciuto).
EXCHANGE_UNAVAILABLE	L'exchange upstream non risponde.
DATA_UNAVAILABLE	Le candele richieste non sono disponibili dall'exchange upstream per questo intervallo.
RATE_LIMIT_EXCEEDED	Raggiunto il limite di velocità a breve intervallo.
QUOTA_EXCEEDED	Raggiunta la quota settimanale.