Limites de taux et facteurs de coût

Cette page documente comment le MCP de données de marché Cryptohopper compte les appels, applique les limites de taux et facture les multiplicateurs de coût pour les données historiques. Il s'agit de la référence technique ; pour le résumé des niveaux, consulte les niveaux d'abonnement.

Deux limites indépendantes

Le MCP applique deux limites distinctes sur chaque compte :

• Limite d'appels hebdomadaire. Un quota hebdomadaire glissant d'appels, spécifique au niveau.
• Limite de taux. Un plafond à court intervalle sur la rapidité avec laquelle les appels peuvent être effectués.

Les deux limites sont appliquées par compte. La création de clés API supplémentaires ne multiplie aucune des deux limites.

Limite d'appels hebdomadaire

Niveau	Appels hebdomadaires
Pioneer	6 000
Explorer	30 000
Adventurer	150 000
Hero	1 250 000

Le compteur se réinitialise chaque vendredi à une heure fixe par compte. Le dépassement de la limite renvoie une erreur QUOTA_EXCEEDED jusqu'à la prochaine réinitialisation.

L'utilisation actuelle et le temps jusqu'à la réinitialisation peuvent être interrogés à tout moment. Consulte utilisation et limites.

Limite de taux

En plus de la limite hebdomadaire, une limite de taux à court intervalle empêche les rafales rapides. La fenêtre exacte et le seuil sont appliqués uniformément sur tous les niveaux et peuvent être ajustés sans préavis pour maintenir la stabilité du service.

Le dépassement de la limite de taux renvoie une erreur RATE_LIMIT_EXCEEDED. Réessayer après un court délai réussit généralement.

Conseil : Si ton flux de travail implique de nombreux appels séquentiels (par exemple, balayer les tickers sur toutes les paires d'un exchange), ajoute un petit délai entre les appels — de l'ordre de dizaines à centaines de millisecondes — pour rester sous la limite de taux. Les clients MCP le font automatiquement dans la plupart des cas.

Unité de coût

Une unité d'appel est la charge de base pour une seule invocation d'outil. La limite d'appels hebdomadaire est exprimée en unités.

La plupart des invocations d'outils comptent pour 1 unité. Les requêtes de chandeliers historiques peuvent compter pour plus d'1 unité, comme décrit ci-dessous.

Facteur de coût : données historiques

Les requêtes de chandeliers historiques comportent un multiplicateur de coût sur les niveaux Explorer et Adventurer. Le multiplicateur dépend de la profondeur de rétrospective :

Profondeur de rétrospective	Multiplicateur de coût
Historique court (barres récentes dans une fenêtre courte)	5×
Historique long (barres atteignant l'historique maximum du niveau)	20×

La frontière entre « court » et « long » est spécifique au niveau et peut être ajustée. En règle générale, les requêtes extrayant environ les ~10 % les plus récents de l'allocation historique du niveau sont facturées à 5× ; les requêtes plus profondes sont facturées à 20×.

Sur le palier Hero, toutes les requêtes historiques sont facturées à 1× quelle que soit la profondeur de rétrospection.

Les requêtes de tick et de carnets d'ordre sont toujours facturées à 1× sur tous les paliers.

Exemples

Requête	Niveau	Coût unitaire
Ticker BTC/USDT actuel sur Binance	Tous	1
Instantané complet du carnet d'ordres pour ETH/USDT sur Kraken	Tous	1
Derniers 100 × chandeliers 1h pour SOL/USDT sur Binance (récent)	Explorer	5
Derniers 500 × chandeliers 1h remontant à ~3 semaines	Explorer	5
Derniers 1 000 × chandeliers 1h remontant vers la limite de 90 jours	Explorer	20
Derniers 1 000 × chandeliers 4h (rétrospective profonde)	Adventurer	20
Derniers 3 000 × chandeliers 1h (rétrospective de 3 ans)	Hero	1

Le coût exact d'une requête spécifique peut être prévisualisé en appelant le point de terminaison d'utilisation après la requête — le delta dans calls_used est le coût unitaire.

Conseils de budgétisation

Quelques règles pratiques pour rester dans le quota :

• Privilégie les tickers pour les balayages larges. Un balayage de 200 paires de tickers coûte 200 unités. Le même balayage via les carnets d'ordres coûte 200 unités (bien que chaque appel transfère beaucoup plus de données). Le même balayage via un historique profond de chandeliers peut coûter des milliers d'unités.
• Garde la rétrospective des chandeliers serrée. La plupart des indicateurs (RSI, MACD, moyennes mobiles jusqu'à 200 périodes) n'ont pas besoin de plus de 150-200 chandeliers de contexte. Extraire 1 000 chandeliers par défaut est la cause la plus fréquente de dépense de quota inutile.
• Mets en cache quand cela a du sens. Les carnets d'ordres deviennent obsolètes en quelques secondes, donc mettre en cache les instantanés de carnets d'ordres est rarement utile. Les données de chandeliers plus anciennes que la barre actuelle sont immuables, donc mettre en cache ou persister les chandeliers historiques est approprié.
• Utilise Hero lorsque la profondeur historique est structurellement requise. Si ton flux de travail extrait régulièrement de longs historiques de chandeliers, le facteur de coût fixe de 1× sur Hero est généralement plus économique que d'extraire les mêmes données sur Adventurer à 20×.

Quota pour les déploiements multi-agents

Si plusieurs agents partagent un compte, tous les agents puisent dans le même quota hebdomadaire. Pour séparer les agents :

• Crée des clés API supplémentaires (dans la limite d'allocation de clés du niveau). Chaque clé consomme du quota partagé mais peut être révoquée ou renouvelée indépendamment.
• Implémente une limitation au niveau de l'application par clé pour empêcher un agent d'épuiser le quota pour les autres.

Consulte comment exécuter plusieurs agents avec plusieurs clés API pour les modèles.

Gestion des erreurs

Erreurs liées aux limites renvoyées par le MCP :

Code d'erreur	Signification
QUOTA_EXCEEDED	Limite d'appels hebdomadaire atteinte. Se réinitialise à la prochaine heure de réinitialisation.
RATE_LIMIT_EXCEEDED	Limite de taux à court intervalle atteinte. Réessaye après un court délai.
HISTORY_LIMIT_EXCEEDED	La rétrospective demandée dépasse l'historique maximum du niveau.
EXCHANGE_NOT_SUPPORTED	L'exchange demandé n'est pas dans la liste autorisée du niveau.

Référence complète des erreurs : référence des erreurs.

Vérifier l'utilisation actuelle

Le MCP expose un outil d'inspection d'utilisation qui renvoie :

• tier — le niveau d'abonnement actif.
• calls_used — unités utilisées dans le cycle hebdomadaire actuel.
• calls_limit — la limite hebdomadaire du niveau.
• reset_at — horodatage ISO-8601 de la prochaine réinitialisation.