Convenciones de la API para código y LLM

#Símbolos

Se siguen 104 activos: 102 perpetuos USDT-M y dos stablecoins, estas últimas solo en spot. La lista viva la sirve /v1/symbols, y esa es la que manda.

#Temporalidades

En la mayoría de las rutas por intervalos, siete valores:

1m5m15m30m1h4h1d

Las velas (/v1/klines) y los indicadores técnicos aceptan un octavo, la semana (que empieza el lunes a las 00:00 UTC), porque se construyen directamente sobre las velas:

1m5m15m30m1h4h1d1w

Las excepciones: las rutas de opciones rechazan 1m (sus instantáneas llegan aproximadamente una vez por minuto), los instrumentos macro intradía rechazan 30m, y el paso opcional de /v1/btc/fees/history y /v1/global/history es 1h, 4h o 1d. El contrato da a cada ruta su lista exacta (un enum), y el catálogo de la familia (/v1/macro/intraday/series) las temporalidades de cada instrumento.

Un valor fuera de la lista devuelve 422 invalid_timeframe con los valores aceptados, nunca una alternativa silenciosa a otra temporalidad. Todo error de validación es un 422, incluidos el cuerpo de POST /v1/indicators y los historiales de opciones. Decide según error.code: indica qué parámetro falla. Como symbol, timeframe y order no distinguen mayúsculas (1H equivale a 1h), salvo 1M: en otros sitios es un mes, aquí se rechaza, ya que 1m es un minuto.

#Agregación multimercado

Ninguna respuesta nombra su mercado. Las métricas multimercado llegan ya fusionadas: es el contrato de la plataforma, y la razón por la que varias integraciones se convierten en una. Tres reglas de fusión, según la naturaleza de la magnitud:

Una sola excepción en todo BytNode: /v1/spread/interexchange nombra los mercados, ya que un diferencial no tiene sentido sin ellos. En todos los demás casos el parámetro exchange no existe: pasarlo devuelve 422.

#Velas cerradas y periodo en curso

Toda ruta que sirve datos cortados en ventanas lleva un booleano is_closed en cada fila, lo hayas pedido o no: velas, velas de trades, CVD, ratio compra/venta, tamaño de los trades, liquidaciones grandes/pequeñas, el libro de órdenes, los spreads entre mercados — y cada fila de cada ruta /history (basis, open interest, funding, liquidaciones, macro, on-chain…). Su último valor es el último bucket CERRADO de timeframe (obligatorio). Un último valor calculado sobre una ventana MÓVIL (liquidaciones acumuladas, variación del open interest, funding acumulado, variación del open interest de opciones) siempre es definitivo y no lleva is_closed: time es el final de su ventana, window_start_at y window_s dan su inicio y su duración.

Por defecto solo se sirven las ventanas cerradas. Para ver el periodo en curso, añade ?live=1:

# The latest CLOSED hourly candle: its value will not move again.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h"

# The candle IN PROGRESS: provisional, flagged is_closed: false.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h&live=1"

#Unidades y escalas

Una proporción nunca se escribe de dos maneras. El sufijo de un campo indica su escala, y la regla vale en todas las familias, del núcleo de mercado a los satélites:

#Marcas de tiempo y orden

• Las marcas de tiempo de los datos están en ISO 8601, en UTC, con el sufijo Z y tres dígitos fijos de milisegundos: 2026-08-29T11:38:00.000Z. time está SIEMPRE en este formato, series diarias incluidas (un día se fecha a medianoche UTC) y no hay una clave date aparte; una fecha sola (2026-08-29) solo aparece en las claves que designan un día de negocio, como filed_date o oldest_input_date. time sigue una de dos reglas, y la referencia de cada ruta dice cuál: en una serie por buckets (velas, CVD, libro por bucket, funding por periodo de 8 h) es el inicio del bucket, nunca su final; en un valor puntual (último valor, ventana móvil, previsión, compuesto) es el instante al que se refiere el valor: el final de una ventana móvil, la liquidación a la que apunta una previsión, la entrada más reciente de un compuesto (que también da oldest_input_date). El valor actual de una ruta en buckets es su último bucket CERRADO, fechado en su inicio como la primera fila de su /history: /v1/klines, /v1/cvd, /v1/buy-sell-ratio, /v1/trades/avg-size, /v1/liquidations/big-small-ratio, /v1/orderbook (todas exigen timeframe). El envoltorio de /v1/options/max-pain/history repite expiry como el día de vencimiento (YYYY-MM-DD), sea cual sea la forma enviada.
• Los límites de la petición (since_ms, until_ms y before_ms) están en milisegundos desde la época Unix. since_ms y until_ms son inclusivos (al milisegundo), before_ms es exclusivo. since_ms=0 significa el inicio de los datos. Un límite negativo, un since_ms mayor que until_ms (igual lee ese milisegundo) o mayor o igual que before_ms, until_ms y before_ms juntos, un límite en segundos, microsegundos o nanosegundos, o cualquier otro límite anterior al 2009-01-03 (el primer bloque de Bitcoin) devuelve 422 antes de ejecutar nada.
• Los arrays de valores (la serie de un indicador, la serie interna de un CVD) van del más antiguo al más reciente.
• Las listas de historial se devuelven del más reciente al más antiguo por defecto —la fila más fresca va primero—, o del más antiguo al más reciente con order=asc.
• El día empieza a medianoche UTC: es la alineación de las series diarias.