Referência da ferramenta de velas (OHLCV)

Esta página é a referência da ferramenta para recuperar dados de velas (OHLCV) do Cryptohopper Market Data MCP.

Nome da ferramenta

get_candles

Finalidade

Retorna uma série de velas OHLCV (Abertura, Máxima, Mínima, Fechamento, Volume) para um par especificado em uma corretora especificada em um período de tempo especificado. Suporta velas atuais (em tempo real) em todos os planos e velas históricas nos planos Explorer, Adventurer e Hero.

Argumentos

Argumento	Tipo	Obrigatório	Descrição
exchange	string	Sim	Identificador da corretora (minúsculas). Veja as corretoras suportadas.
pair	string	Sim	Par no formato BASE/QUOTE.
timeframe	string	Sim	Tamanho da barra. Veja os períodos de tempo suportados abaixo.
limit	integer	Não	Número de velas a retornar. O padrão e o máximo dependem do plano.
since	string (ISO-8601)	Não	Hora de início para consultas históricas. Se omitido, retorna as barras mais recentes até o limite.

Pode ser usado apenas limit (barras recentes) ou since + limit (intervalo histórico). O uso isolado de limit é o caso mais comum.

Períodos de tempo suportados

Valor	Duração
1m	1 minuto
5m	5 minutos
15m	15 minutos
1h	1 hora
4h	4 horas
1d	1 dia

Períodos semanais, mensais e outros aliases de períodos de tempo não são suportados e serão rejeitados. Nem todo período de tempo suportado está disponível em todas as corretoras. Combinações não suportadas retornam TIMEFRAME_NOT_SUPPORTED.

Esquema de resposta

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timeframe": "1h",
  "candles": [
    [1778540400000, 80214.00, 80820.50, 80120.00, 80651.42, 412.85, 318],
    [1778544000000, 80651.42, 80936.22, 80590.00, 80934.19, 298.12, 274]
  ]
}

Campos de nível superior

Campo	Tipo	Descrição
exchange	string	O identificador da corretora de onde os dados vieram.
pair	string	O par, no formato BASE/QUOTE.
timeframe	string	O tamanho da barra (ex: 1h).
candles	array	Array de registros OHLCV, ordenados cronologicamente (do mais antigo para o mais recente). Cada registro é em si um array de sete posições.

Campos do registro de vela

Cada vela é um array com as seguintes posições:

Índice	Campo	Tipo	Descrição
0	timestamp	number	Hora de abertura da barra (timestamp Unix em milissegundos).
1	open	number	Primeiro preço negociado na barra.
2	high	number	Maior preço negociado na barra.
3	low	number	Menor preço negociado na barra.
4	close	number	Último preço negociado na barra (ou preço atual, para uma barra aberta).
5	volume	number	Volume do ativo base negociado na barra.
6	count	number	Número de operações na barra.

Preços e volume são retornados como números JSON. Clientes que requerem precisão exata devem convertê-los para um tipo decimal imediatamente após a análise. Veja o modelo de dados.

Ordenação

As velas são retornadas em ordem cronológica — a barra mais antiga primeiro, a barra mais recente por último. Isso corresponde ao que a maioria das bibliotecas de indicadores espera como entrada.

Barras abertas vs. fechadas

O último elemento do array de velas é normalmente a barra atual e aberta — a barra cuja janela de tempo ainda não foi concluída. Seu valor de fechamento reflete o preço atual, não um fechamento finalizado. Todas as barras anteriores estão fechadas e imutáveis.

Aplicações que realizam cálculos de indicadores (RSI, MACD, médias móveis) devem normalmente operar apenas em barras fechadas, ignorando o último elemento. Usar a barra aberta introduz ruído de antecipação que pode desestabilizar os sinais.

Custo

Cenário	Custo no Pioneer	Custo no Explorer/Adventurer	Custo no Hero
Apenas barra atual (tempo real)	1	1	1
Consulta de histórico curto	N/A	5×	1×
Consulta de histórico longo	N/A	20×	1×

A fronteira entre consulta de histórico "curto" e "longo" é específica do plano. Veja os limites de taxa explicados para a matriz de custos exata e orientações sobre como manter a eficiência.

Acesso a dados históricos por plano

Plano	Consulta histórica
Pioneer	Não disponível — apenas barra atual
Explorer	Até 90 dias
Adventurer	Até 365 dias
Hero	Até 3 anos

Solicitações que excedem o histórico máximo do plano retornam HISTORY_LIMIT_EXCEEDED.

Orientação sobre consulta histórica

A maioria das análises requer muito menos velas do que os usuários intuitivamente solicitam. Consultas históricas sugeridas:

Indicador	Barras mínimas	Confortável
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Média móvel (período N)	N	N + 50
Bandas de Bollinger (20, 2?)	20	100
ATR(14)	14	100

Obter mais barras do que o necessário infla o custo (consultas históricas no Explorer/Adventurer podem custar até 20× uma chamada básica) sem melhorar a qualidade do indicador.

Exemplos de invocações

Barras recentes

Solicitado em um cliente MCP:

Obtenha as últimas 100 velas de 1 hora para ETH/USDT na Binance.

O agente invoca get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100).

Intervalo histórico

Obtenha velas diárias para BTC/USDT na Binance a partir de 01/01/2026.

O agente invoca get_candles(exchange="binance", pair="BTC/USDT", timeframe="1d", since="2026-01-01T00:00:00Z", limit=120).

Múltiplos períodos de tempo

Obtenha velas de 1h e 4h para SOL/USDT na Binance, últimas 100 de cada. Calcule o RSI em ambos os períodos de tempo.

O agente invoca get_candles duas vezes com valores diferentes de timeframe. O cálculo do RSI acontece no raciocínio do modelo, não em uma chamada de ferramenta.

Erros

Código de erro	Causa
UNAUTHORIZED	Chave de API inválida ou revogada.
EXCHANGE_NOT_SUPPORTED	Corretora não disponível no plano ativo.
PAIR_NOT_FOUND	Par não existe na corretora especificada.
TIMEFRAME_NOT_SUPPORTED	Período de tempo solicitado não é suportado para este par/corretora.
HISTORY_LIMIT_EXCEEDED	Consulta histórica solicitada excede o histórico máximo do plano.
INVALID_PARAMETER	Argumento falhou na validação (ex: limite fora do intervalo, alias de período de tempo não reconhecido).
EXCHANGE_UNAVAILABLE	Corretora upstream não está respondendo.
DATA_UNAVAILABLE	Velas solicitadas não estão disponíveis da corretora upstream para este intervalo.
RATE_LIMIT_EXCEEDED	Limite de taxa de intervalo curto atingido.
QUOTA_EXCEEDED	Cota semanal alcançada.