Riferimento strumento Orderbook
Questa pagina è il riferimento dello strumento per recuperare snapshot del registro degli ordini dal Cryptohopper Market Data MCP. Per la guida concettuale, vedi una guida pratica ai dati del registro degli ordini crypto.
Nome dello strumento
get_orderbook
Scopo
Restituisce uno snapshot puntuale del registro degli ordini per una coppia specificata su un exchange specificato. Contiene i bid e gli ask correnti con prezzo e dimensione per livello.
Argomenti
| Argomento | Tipo | Richiesto | Descrizione |
|---|---|---|---|
| exchange | string | Sì | Identificativo exchange (minuscolo). |
| pair | string | Sì | Coppia in formato BASE/QUOTE (es. BTC/USDT). |
| depth | integer | No | Numero massimo di livelli da restituire per lato. Il valore predefinito dipende dall'exchange. Il limite superiore dipende dall'upstream. |
Schema della risposta
{
"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]
]
}
Campi
| Campo | Tipo | Descrizione |
|---|---|---|
| exchange | string | L'identificativo exchange da cui provengono i dati. |
| pair | string | La coppia, in formato BASE/QUOTE. |
| timestamp | string (ISO-8601) | Momento di acquisizione dello snapshot. |
| bids | array | Array di tuple [prezzo, dimensione], ordinati per prezzo decrescente (miglior offerta per prima). |
| asks | array | Array di tuple [prezzo, dimensione], ordinati per prezzo crescente (miglior richiesta per prima). |
I prezzi e le dimensioni sono restituiti come numeri JSON. I client che richiedono precisione esatta per calcoli relativi all'esecuzione dovrebbero convertirli in un tipo decimale immediatamente dopo il parsing. Vedi modello dati per le convenzioni.
Ordinamento
- i bids sono ordinati in modo decrescente per prezzo. La prima voce è la miglior offerta (prezzo più alto che un acquirente sta offrendo).
- gli asks sono ordinati in modo crescente per prezzo. La prima voce è la miglior richiesta (prezzo più basso che un venditore sta richiedendo).
Lo spread è la differenza tra asks[0] e bids[0]. Il punto medio è la loro media.
Profondità
La profondità del registro degli ordini varia in base all'exchange. L'MCP restituisce ciò che l'exchange upstream espone tramite la sua API pubblica.
| Profondità tipica (livelli per lato) | Exchange |
|---|---|
| 100 | Maggior parte degli exchange principali come valore predefinito |
| Fino a 500 o più | Alcuni exchange, quando viene richiesta la profondità |
Le richieste di maggiore profondità rispetto a quella supportata dall'upstream vengono limitate al massimo upstream. L'argomento depth è best-effort, non garantito.
Aggiornamento
I registri degli ordini vengono acquisiti al momento della richiesta. Il campo timestamp riflette quando lo snapshot è stato letto dall'exchange upstream.
I registri degli ordini diventano obsoleti molto rapidamente — tipicamente entro secondi sulle coppie liquide. I client non dovrebbero memorizzare nella cache le risposte del registro degli ordini per decisioni di esecuzione.
Costo
| Aspetto | Costo |
|---|---|
| Per invocazione | 1 unità di chiamata su tutti i livelli |
| Variante storica | Non supportato — la cronologia del registro degli ordini non è disponibile tramite l'MCP |
Esempi di invocazione
Snapshot di base
Richiesto in un client MCP:
Mostrami il registro degli ordini corrente per BTC/USDT su Binance.
L'agente invoca get_orderbook(exchange="binance", pair="BTC/USDT") e restituisce uno snapshot.
Profondità personalizzata
Recupera i primi 50 livelli del registro degli ordini ETH/USDT su Kraken.
L'agente invoca get_orderbook(exchange="kraken", pair="ETH/USDT", depth=50).
Metriche derivate
L'MCP restituisce i livelli grezzi; le metriche derivate (spread, profondità entro X%, slippage per una data dimensione d'ordine) sono calcolate dal modello o dal codice chiamante.
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. |
| INVALID_PARAMETER | L'argomento ha fallito la validazione (es. simbolo coppia malformato, profondità negativa). |
| EXCHANGE_UNAVAILABLE | L'exchange upstream non risponde. |
| RATE_LIMIT_EXCEEDED | Limite di velocità a breve intervallo raggiunto. |
| QUOTA_EXCEEDED | Quota settimanale raggiunta. |
Accesso livello
Le query del registro degli ordini sono disponibili su tutti i livelli (Pioneer, Explorer, Adventurer, Hero).
Si applica la restrizione di copertura exchange: su Pioneer, le query del registro degli ordini sono limitate a Binance, Coinbase e Kraken. Su Explorer e superiori, sono disponibili più exchange.