Limiti di velocità e fattori di costo

Questa pagina documenta come il Cryptohopper Market Data MCP conta le chiamate, applica i limiti di velocità e addebita moltiplicatori di costo per i dati storici. È il riferimento tecnico; per il riepilogo dei livelli, vedi livelli di abbonamento.

Due limiti indipendenti

L'MCP applica due limiti separati su ogni account:

• Limite di chiamate settimanali. Una quota settimanale progressiva di chiamate, specifica per livello.
• Limite di velocità. Un limite a breve intervallo sulla rapidità con cui possono essere effettuate le chiamate.

Entrambi i limiti sono applicati per account. La creazione di chiavi API aggiuntive non moltiplica nessuno dei due limiti.

Limite chiamate settimanali

Livello	Chiamate settimanali
Pioneer	6.000
Explorer	30.000
Adventurer	150.000
Hero	1.250.000

Il contatore si ripristina ogni venerdì a un orario fisso per account. Il superamento del limite restituisce un errore QUOTA_EXCEEDED fino al ripristino successivo.

L'utilizzo corrente e il tempo fino al ripristino possono essere interrogati in qualsiasi momento. Vedi utilizzo e limiti.

Limite di velocità

Oltre al limite settimanale, un limite di velocità a breve intervallo previene picchi rapidi. La finestra esatta e la soglia sono applicate uniformemente su tutti i livelli e possono essere modificate senza preavviso per mantenere la stabilità del servizio.

Il superamento del limite di velocità restituisce un errore RATE_LIMIT_EXCEEDED. Riprovare dopo un breve ritardo in genere ha successo.

Indicazione: Se il tuo flusso di lavoro prevede molte chiamate sequenziali (ad esempio, scansionare i ticker su tutte le coppie di un exchange), aggiungi un piccolo ritardo tra le chiamate — dell'ordine di decine o centinaia di millisecondi — per rimanere sotto il limite di velocità. I client MCP lo fanno automaticamente nella maggior parte dei casi.

Unità di costo

Un'unità di chiamata è l'addebito base per una singola invocazione di strumento. Il limite di chiamate settimanali è espresso in unità.

La maggior parte delle invocazioni di strumenti conta come 1 unità. Le query di candele storiche possono contare come più di 1 unità, come descritto di seguito.

Fattore di costo: dati storici

Le query di candele storiche comportano un moltiplicatore di costo sui livelli Explorer e Adventurer. Il moltiplicatore dipende dalla profondità retrospettiva:

Profondità retrospettiva	Moltiplicatore di costo
Cronologia breve (barre recenti entro una finestra breve)	5×
Cronologia lunga (barre che si estendono verso la cronologia massima del livello)	20×

Il confine tra "breve" e "lungo" è specifico per livello e può essere modificato. Come regola pratica, le query che recuperano approssimativamente il ~10% più recente della cronologia consentita dal livello vengono addebitate a 5×; le query più profonde vengono addebitate a 20×.

Sul livello Hero, tutte le query storiche vengono addebitate a 1× indipendentemente dalla profondità del lookback.

Le query di ticker e registro degli ordini vengono sempre addebitate a 1× su tutti i livelli.

Esempi

Query	Livello	Costo unitario
Ticker BTC/USDT corrente su Binance	Qualsiasi	1
Snapshot completo registro degli ordini per ETH/USDT su Kraken	Qualsiasi	1
Ultime 100 × 1h candele per SOL/USDT su Binance (recente)	Explorer	5
Ultime 500 × 1h candele che risalgono a ~3 settimane	Explorer	5
Ultime 1.000 × 1h candele che si avvicinano al limite di 90 giorni	Explorer	20
Ultime 1.000 × 4h candele (retrospezione profonda)	Adventurer	20
Ultime 3.000 × 1h candele (retrospezione di 3 anni)	Hero	1

Il costo esatto di una query specifica può essere visualizzato in anteprima chiamando l'endpoint di utilizzo dopo la query — il delta in calls_used è il costo unitario.

Indicazioni per il budget

Alcune regole pratiche per rimanere entro la quota:

• Preferisci i ticker per scansioni ampie. Una scansione di 200 coppie tramite ticker costa 200 unità. La stessa scansione tramite registri degli ordini costa 200 unità (anche se ogni chiamata trasferisce molti più dati). La stessa scansione tramite cronologia profonda delle candele può costare migliaia di unità.
• Mantieni stretta la retrospezione delle candele. La maggior parte degli indicatori (RSI, MACD, medie mobili fino a 200 periodi) non necessita di più di 150-200 candele di contesto. Recuperare 1.000 candele per impostazione predefinita è la causa più comune di spesa di quota non necessaria.
• Usa la cache dove ha senso. I registri degli ordini diventano obsoleti entro pochi secondi, quindi memorizzare nella cache gli snapshot dei registri degli ordini è raramente utile. I dati delle candele più vecchi della barra corrente sono immutabili, quindi memorizzare nella cache o persistere le candele storiche è appropriato.
• Usa Hero quando la profondità storica è strutturalmente richiesta. Se il tuo flusso di lavoro recupera regolarmente lunghe cronologie di candele, il fattore di costo fisso di 1× su Hero è tipicamente più economico che recuperare gli stessi dati su Adventurer a 20×.

Quota per deployment multi-agente

Se più agenti condividono un account, tutti gli agenti attingono dalla stessa quota settimanale. Per separare gli agenti:

• Crea chiavi API aggiuntive (entro l'allowance di chiavi del livello). Ogni chiave consuma dalla quota condivisa ma può essere revocata o ruotata indipendentemente.
• Implementa il throttling a livello di applicazione per chiave per impedire a un agente di esaurire la quota per gli altri.

Vedi come eseguire più agenti con più chiavi API per i pattern.

Gestione degli errori

Errori relativi ai limiti restituiti dall'MCP:

Codice errore	Significato
QUOTA_EXCEEDED	Limite di chiamate settimanali raggiunto. Si ripristina al prossimo orario di ripristino.
RATE_LIMIT_EXCEEDED	Limite di velocità a breve intervallo raggiunto. Riprova dopo un breve ritardo.
HISTORY_LIMIT_EXCEEDED	La retrospezione richiesta supera la cronologia massima del livello.
EXCHANGE_NOT_SUPPORTED	L'exchange richiesto non è nell'elenco consentito del livello.

Riferimento completo degli errori: riferimento errori.

Verifica dell'utilizzo corrente

L'MCP espone uno strumento di ispezione dell'utilizzo che restituisce:

• tier — il livello di abbonamento attivo.
• calls_used — unità utilizzate nel ciclo settimanale corrente.
• calls_limit — il limite settimanale del livello.
• reset_at — timestamp ISO-8601 del prossimo ripristino.