Data Model

Questa pagina descrive il modello di dati condiviso tra gli strumenti di dati di mercato dell'MCP di Cryptohopper. I tre tipi di dati principali — ticker, registro degli ordini e candela — hanno ciascuno la propria pagina di riferimento con lo schema di risposta esatto:

• Riferimento tool ticker
• Riferimento tool registro degli ordini
• Riferimento tool candela

Questa pagina documenta le convenzioni comuni a tutti e tre.

Convenzioni

Formato simbolo

Tutti i simboli delle coppie utilizzano il formato BASE/QUOTE:

Esempio	Base	Quote
BTC/USDT	BTC	USDT
ETH/USD	ETH	USD
SOL/USDC	SOL	USDC

Il formato è normalizzato lato server. Gli exchange upstream utilizzano una varietà di notazioni (ad es. BTCUSDT, BTC-USDT, tBTCUSDT); l'MCP presenta un formato BASE/QUOTE uniforme indipendentemente dalla convenzione upstream.

Vedi exchange supportati per l'elenco degli exchange che l'MCP può interrogare.

Identificatori exchange

I nomi degli exchange nelle richieste e nelle risposte utilizzano identificatori in minuscolo:

Identificatore	Exchange
binance	Binance
coinbase	Coinbase
kraken	Kraken
bybit	Bybit
okx	OKX

L'elenco completo è restituito dal tool list-exchanges ed è documentato in exchange supportati.

Timestamp

Tutti i timestamp nelle risposte sono in UTC e formattati ISO-8601: 2026-04-24T14:03:00Z

I timestamp numerici, dove esposti (ad esempio, all'interno dei record delle candele), sono timestamp Unix in millisecondi.

Codifica decimale

I valori di prezzo e dimensione sono restituiti come numeri JSON (float). Esempi da ciascun tool:

// Ticker
{
  "last": 80934.19,
  "baseVolume": 11744.6152
}

// Orderbook level
[80934.18, 5.32816]

// Candle record
[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

Poiché i numeri JSON vengono analizzati come floating-point IEEE-754 nella maggior parte dei linguaggi, i client che richiedono precisione esatta (ad esempio, quando calcolano le dimensioni degli ordini) dovrebbero convertire questi valori in un tipo decimale immediatamente dopo l'analisi — ad esempio, Decimal di Python, BigNumber.js di JavaScript o un equivalente.

Campi opzionali

Alcuni campi sono opzionali e potrebbero essere assenti dalle risposte quando l'exchange upstream non li fornisce. I client dovrebbero trattare i campi mancanti come null piuttosto che come errore.

Campi comuni

Tre campi appaiono nella maggior parte delle risposte:

Campo	Tipo	Descrizione
exchange	string	L'identificatore dell'exchange da cui provengono i dati.
pair	string	La coppia in formato BASE/QUOTE.
timestamp	string (ISO-8601)	Il momento in cui i dati sono stati acquisiti.

I campi rimanenti dipendono dal tool. Gli schemi completi seguono.

Schema ticker (riepilogo)

Una risposta ticker è un singolo oggetto che descrive lo stato attuale di un mercato. I nomi dei campi seguono le convenzioni CCXT.

I campi includono:

• last — ultimo prezzo scambiato
• bid — miglior prezzo bid
• ask — miglior prezzo ask
• bidVolume — dimensione alla miglior offerta
• askVolume — dimensione alla miglior richiesta
• high — massimo delle 24 ore
• low — minimo delle 24 ore
• open — prezzo di apertura per la finestra di 24 ore
• close — prezzo di chiusura per la finestra di 24 ore (tipicamente uguale a last)
• previousClose — prezzo di chiusura della finestra di 24 ore precedente
• average — media di apertura e chiusura
• vwap — prezzo medio ponderato per volume delle 24 ore
• baseVolume — volume delle 24 ore nell'asset base
• quoteVolume — volume delle 24 ore nell'asset di quotazione
• change — variazione assoluta di prezzo delle 24 ore
• percentage — variazione percentuale delle 24 ore

Vedi riferimento tool ticker per lo schema completo e i tipi di campo.

Schema registro degli ordini (riepilogo)

Una risposta del registro degli ordini contiene due array — bids e asks — ciascun elemento è una tupla [prezzo, dimensione]:

• bids — array di coppie [prezzo, dimensione], ordinate per prezzo decrescente (miglior offerta per prima)
• asks — array di coppie [prezzo, dimensione], ordinate per prezzo crescente (miglior richiesta per prima)

La profondità di ciascun lato dipende dall'exchange upstream. Vedi riferimento tool registro degli ordini per i dettagli.

Schema candela (riepilogo)

Una risposta candela è un array di record OHLCV, ordinati cronologicamente (il più vecchio per primo per impostazione predefinita). Ogni record è a sua volta un array con sette posizioni:

Indice	Campo	Descrizione
0	timestamp	Ora di apertura della barra (timestamp Unix in millisecondi)
1	open	Prezzo di apertura
2	high	Prezzo più alto nella barra
3	low	Prezzo più basso nella barra
4	close	Prezzo di chiusura
5	volume	Volume dell'asset base scambiato nella barra
6	count	Numero di trades nella barra

Esempio:

[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

Vedi riferimento tool candela per lo schema completo, i timeframe supportati e la semantica di lookback.

Risposte di errore

Quando l'invocazione di un tool fallisce, la risposta segue l'envelope di errore MCP:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Weekly call limit reached",
  "details": {
    "reset_at": "2026-04-25T00:00:00Z"
  }
}