Limites de taxa e fatores de custo

Esta página documenta como o MCP de Dados de Mercado do Cryptohopper conta chamadas, aplica limites de taxa e cobra multiplicadores de custo para dados históricos. Esta é a referência técnica; para o resumo dos planos, consulte planos de assinatura.

Dois limites independentes

O MCP aplica dois limites separados em cada conta:

• Limite semanal de chamadas. Uma cota semanal contínua de chamadas, específica por plano.
• Limite de taxa. Um limite de intervalo curto sobre a velocidade com que as chamadas podem ser feitas.

Ambos os limites são aplicados por conta. Criar chaves de API adicionais não multiplica nenhum dos limites.

Limite semanal de chamadas

Plano	Chamadas semanais
Pioneer	6.000
Explorer	30.000
Adventurer	150.000
Hero	1.250.000

O contador é reiniciado toda sexta-feira em um horário fixo por conta. Exceder o limite retorna um erro QUOTA_EXCEEDED até a próxima reinicialização.

O uso atual e o tempo até a reinicialização podem ser consultados a qualquer momento. Consulte uso e limites.

Limite de taxa

Além do limite semanal, um limite de taxa de intervalo curto impede picos rápidos. A janela exata e o limite são aplicados uniformemente em todos os planos e podem ser ajustados sem aviso prévio para manter a estabilidade do serviço.

Exceder o limite de taxa retorna um erro RATE_LIMIT_EXCEEDED. Tentar novamente após um breve intervalo normalmente funciona.

Orientação: Se seu fluxo de trabalho envolve muitas chamadas sequenciais (por exemplo, varrer tickers em todos os pares de moedas de uma corretora), adicione um pequeno intervalo entre as chamadas — na ordem de dezenas a centenas de milissegundos — para ficar abaixo do limite de taxa. Os clientes MCP fazem isso automaticamente na maioria dos casos.

Unidade de custo

Uma unidade de chamada é a cobrança base para uma única invocação de ferramenta. O limite semanal de chamadas é expresso em unidades.

A maioria das invocações de ferramentas conta como 1 unidade. Consultas de velas históricas podem contar como mais de 1 unidade, conforme descrito abaixo.

Fator de custo: dados históricos

Consultas de velas históricas têm um multiplicador de custo nos planos Explorer e Adventurer. O multiplicador depende da profundidade do histórico:

Profundidade do histórico	Multiplicador de custo
Histórico curto (barras recentes dentro de uma janela curta)	5×
Histórico longo (barras chegando ao histórico máximo do plano)	20×

A fronteira entre "curto" e "longo" é específica por plano e pode ser ajustada. Como regra prática, consultas que buscam aproximadamente os ~10% mais recentes do histórico permitido do plano são cobradas a 5×; consultas mais profundas são cobradas a 20×.

No nível Hero, todas as consultas históricas são cobradas a 1× independentemente da profundidade de retrospectiva.

Consultas de ticker e livro de ofertas são sempre cobradas a 1× em todos os níveis.

Exemplos

Consulta	Plano	Custo unitário
Ticker atual de BTC/USDT na Binance	Qualquer	1
Captura completa do livro de ofertas para ETH/USDT na Kraken	Qualquer	1
Últimas 100 × velas de 1h para SOL/USDT na Binance (recente)	Explorer	5
Últimas 500 × velas de 1h retrocedendo ~3 semanas	Explorer	5
Últimas 1.000 × velas de 1h retrocedendo até o limite de 90 dias	Explorer	20
Últimas 1.000 × velas de 4h (histórico profundo)	Adventurer	20
Últimas 3.000 × velas de 1h (histórico de 3 anos)	Hero	1

O custo exato de uma consulta específica pode ser visualizado chamando o endpoint de uso após a consulta — o delta em calls_used é o custo unitário.

Orientação para orçamento

Algumas regras práticas para ficar dentro da cota:

• Prefira tickers para varreduras amplas. Uma varredura de 200 pares de moedas via ticker custa 200 unidades. A mesma varredura via livros de ofertas custa 200 unidades (embora cada chamada transfira muito mais dados). A mesma varredura via histórico profundo de velas pode custar milhares de unidades.
• Mantenha o histórico de velas restrito. A maioria dos indicadores (RSI, MACD, médias móveis até 200 períodos) não precisa de mais de 150-200 velas de contexto. Buscar 1.000 velas por padrão é a causa mais comum de gasto desnecessário de cota.
• Use cache quando fizer sentido. Livros de ofertas ficam desatualizados em segundos, então armazenar capturas de livros de ofertas raramente é útil. Dados de velas mais antigos que a barra atual são imutáveis, então armazenar em cache ou persistir velas históricas é apropriado.
• Use Hero quando a profundidade histórica for estruturalmente necessária. Se seu fluxo de trabalho rotineiramente busca históricos longos de velas, o fator de custo fixo de 1× no Hero geralmente é mais econômico do que buscar os mesmos dados no Adventurer a 20×.

Cota para implantações multi-agente

Se múltiplos agentes compartilham uma conta, todos os agentes consomem da mesma cota semanal. Para separar agentes:

• Crie chaves de API adicionais (dentro da permissão de chaves do plano). Cada chave consome da cota compartilhada, mas pode ser revogada ou rotacionada independentemente.
• Implemente limitação em nível de aplicação por chave para evitar que um agente esgote a cota dos outros.

Consulte como executar múltiplos agentes com múltiplas chaves de API para padrões.

Tratamento de erros

Erros relacionados a limites retornados pelo MCP:

Código de erro	Significado
QUOTA_EXCEEDED	Limite semanal de chamadas atingido. Reinicia no próximo horário de reinicialização.
RATE_LIMIT_EXCEEDED	Limite de taxa de intervalo curto atingido. Tente novamente após breve intervalo.
HISTORY_LIMIT_EXCEEDED	O histórico solicitado excede o histórico máximo do plano.
EXCHANGE_NOT_SUPPORTED	A corretora solicitada não está na lista permitida do plano.

Referência completa de erros: referência de erros.

Verificando o uso atual

O MCP expõe uma ferramenta de inspeção de uso que retorna:

• tier — o plano de assinatura ativo.
• calls_used — unidades usadas no ciclo semanal atual.
• calls_limit — o limite semanal do plano.
• reset_at — timestamp ISO-8601 da próxima reinicialização.