Referencia de la herramienta de velas (OHLCV)

Esta página es la referencia de la herramienta para recuperar datos de velas (OHLCV) del MCP de datos de mercado de Cryptohopper.

Nombre de la herramienta

get_candles

Propósito

Devuelve una serie de velas OHLCV (Open, High, Low, Close, Volume) para un par especificado en un exchange especificado en un período de tiempo especificado. Soporta velas actuales (tiempo real) en todos los niveles y velas históricas en Explorer, Adventurer y Hero.

Argumentos

Argumento	Tipo	Requerido	Descripción
exchange	string	Sí	Identificador del exchange (minúsculas). Ver exchanges soportados.
pair	string	Sí	Par en formato BASE/QUOTE.
timeframe	string	Sí	Tamaño de barra. Ver períodos de tiempo soportados a continuación.
limit	integer	No	Número de velas a devolver. El valor predeterminado y máximo dependen del nivel.
since	string (ISO-8601)	No	Hora de inicio para consultas históricas. Si se omite, devuelve las barras más recientes según el límite.

Se puede usar solo limit (barras recientes) o since + limit (rango histórico). El uso de limit solo es el caso común.

Períodos de tiempo soportados

Valor	Duración
1m	1 minuto
5m	5 minutos
15m	15 minutos
1h	1 hora
4h	4 horas
1d	1 día

Los alias de períodos semanales, mensuales y otros no están soportados y serán rechazados. No todos los períodos de tiempo soportados están disponibles en todos los exchanges. Las combinaciones no soportadas devuelven TIMEFRAME_NOT_SUPPORTED.

Esquema de respuesta

{
  "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 nivel superior

Campo	Tipo	Descripción
exchange	string	El identificador del exchange del que provienen los datos.
pair	string	El par, en formato BASE/QUOTE.
timeframe	string	El tamaño de barra (ej. 1h).
candles	array	Arreglo de registros OHLCV, ordenados cronológicamente (el más antiguo primero). Cada registro es en sí mismo un arreglo de siete posiciones.

Campos de registro de vela

Cada vela es un arreglo con las siguientes posiciones:

Índice	Campo	Tipo	Descripción
0	timestamp	number	Hora de apertura de la barra (marca de tiempo Unix en milisegundos).
1	open	number	Primer precio negociado en la barra.
2	high	number	Precio más alto negociado en la barra.
3	low	number	Precio más bajo negociado en la barra.
4	close	number	Último precio negociado en la barra (o precio actual, para una barra abierta).
5	volume	number	Volumen del activo base negociado en la barra.
6	count	number	Número de operaciones en la barra.

Los precios y el volumen se devuelven como números JSON. Los clientes que requieren precisión exacta deben convertirlos a un tipo decimal inmediatamente después del análisis. Ver modelo de datos.

Ordenamiento

Las velas se devuelven en orden cronológico — la barra más antigua primero, la barra más reciente al final. Esto coincide con lo que la mayoría de las bibliotecas de indicadores esperan como entrada.

Barras abiertas vs. cerradas

El último elemento del arreglo de velas suele ser la barra abierta actual — la barra cuya ventana de tiempo aún no se ha completado. Su valor de cierre refleja el precio actual, no un cierre finalizado. Todas las barras anteriores están cerradas e inmutables.

Las aplicaciones que realizan cálculos de indicadores (RSI, MACD, medias móviles) normalmente deben operar solo con barras cerradas, ignorando el último elemento. Usar la barra abierta introduce ruido de anticipación que puede desestabilizar las señales.

Costo

Escenario	Costo en Pioneer	Costo en Explorer/Adventurer	Costo en Hero
Solo barra actual (tiempo real)	1	1	1
Retrospectiva de historial corto	N/A	5×	1×
Retrospectiva de historial largo	N/A	20×	1×

El límite entre retrospectiva "corta" y "larga" es específico del nivel. Ver límites de tasa explicados para la matriz de costos exacta y orientación sobre cómo mantenerse eficiente.

Acceso por nivel para datos históricos

Nivel	Retrospectiva histórica
Pioneer	No disponible — solo barra actual
Explorer	Hasta 90 días
Adventurer	Hasta 365 días
Hero	Hasta 3 años

Las solicitudes que excedan el historial máximo del nivel devuelven HISTORY_LIMIT_EXCEEDED.

Orientación sobre retrospectiva

La mayoría de los análisis requieren muchas menos velas de las que los usuarios solicitan intuitivamente. Retrospectivas sugeridas:

Indicador	Barras mínimas	Cómodo
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Media móvil (período N)	N	N + 50
Bandas de Bollinger (20, 2?)	20	100
ATR(14)	14	100

Extraer más barras de las necesarias infla el costo (las consultas históricas en Explorer/Adventurer pueden costar hasta 20× una llamada base) sin mejorar la calidad del indicador.

Ejemplos de invocaciones

Barras recientes

Solicitado en un cliente MCP:

Extrae las últimas 100 velas de 1 hora para ETH/USDT en Binance.

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

Rango histórico

Extrae velas diarias para BTC/USDT en Binance desde el 2026-01-01 en adelante.

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

Multi-período de tiempo

Extrae velas de 1h y 4h para SOL/USDT en Binance, las últimas 100 de cada una. Calcula RSI en ambos períodos de tiempo.

El agente invoca get_candles dos veces con valores de timeframe diferentes. El cálculo del RSI ocurre en el razonamiento del modelo, no en una llamada de herramienta.

Errores

Código de error	Causa
UNAUTHORIZED	Clave api inválida o revocada.
EXCHANGE_NOT_SUPPORTED	Exchange no disponible en el nivel activo.
PAIR_NOT_FOUND	El par no existe en el exchange especificado.
TIMEFRAME_NOT_SUPPORTED	El período de tiempo solicitado no está soportado para este par/exchange.
HISTORY_LIMIT_EXCEEDED	La retrospectiva solicitada excede el historial máximo del nivel.
INVALID_PARAMETER	El argumento falló la validación (ej. límite fuera de rango, alias de período de tiempo no reconocido).
EXCHANGE_UNAVAILABLE	Exchange upstream no responde.
DATA_UNAVAILABLE	Las velas solicitadas no están disponibles del exchange upstream para este rango.
RATE_LIMIT_EXCEEDED	Límite de tasa de intervalo corto alcanzado.
QUOTA_EXCEEDED	Cuota semanal alcanzada.