API REST

Snapshot

Un endpoint a la carta: nombras los campos y los devuelve todos en una sola petición. Es el punto de entrada adecuado para un panel o para alimentar un modelo: una llamada por ciclo en lugar de diez.

#El principio

GET/v1/snapshotdata_type · snapshot

Cada parámetro de la petición es un nombre de campo, y su valor la profundidad solicitada (un número de filas, de minutos o de segundos según el campo). Los campos que solo tienen un valor actual se piden con =1. symbol es obligatorio.

curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/snapshot?symbol=BTCUSDT\
&klines_1h=24\
&funding_rate_8h=1\
&oi_delta=60\
&liq_cumulative=120\
&cvd@1h=24\
&options=1\
&fear_greed=1"

Sin ningún campo solicitado, la respuesta devuelve un data vacío y la lista available_fields, útil para descubrir el catálogo desde un cliente.

#Los 61 campos

Cincuenta y tres campos se piden por su nombre sin más. La columna profundidad da la unidad y el límite; un campo sin límite indicado solo tiene un valor actual y se pide con =1.

Precio y volumen

Campo	Tipo	Descripción
`klines_1m … klines_1w`	1000 candles	Las ocho temporalidades. Cada fila: marca de tiempo, apertura, máximo, mínimo, cierre, volumen, taker_buy, taker_sell.
`taker_combined`	1440 minutes	Volumen comprador y vendedor por minuto, sumado en todos los exchanges.
`trades_raw`	3600 seconds	Agregado de operaciones por segundo: volumen total, número, desglose taker.
`spot_ticks`	10,000 rows	Operaciones spot individuales.
`futures_ticks`	10,000 rows	Operaciones de futuros individuales.
`price_change`	current value	Variación en % en las ocho temporalidades, calculada bajo demanda.

Derivados y posicionamiento

Campo	Tipo	Descripción
`oi_snapshots`	current value	Open interest total, sumado en los exchanges.
`oi_history`	1440 minutes	Historial del open interest total, por minuto.
`oi_delta`	60 minutes	Variación del open interest, con su porcentaje.
`funding_next`	current value	Próximo funding estimado, normalizado a un equivalente de 8 h.
`funding_rate_8h`	current value	Último tipo aplicado, ponderado por el open interest.
`funding_cumulative`	current value	Total acumulado en 24 h, suma de las tres últimas ventanas.
`liquidations`	1440 minutes	Eventos individuales en la ventana de búsqueda.
`liq_cumulative`	1440 minutes	Liquidaciones acumuladas en ventanas de 5 minutos.
`liq_ratio`	current value	Grandes liquidaciones frente a pequeñas.
`basis`	60 minutes	Diferencia futuros frente a spot, ponderada por el open interest.

Libro de órdenes y microestructura

Campo	Tipo	Descripción
`orderbook`	current value	Profundidad compradora y vendedora sumada, con el desequilibrio.
`vwap`	60 minutes	VWAP intradía, acumulado desde medianoche UTC.
`buysell_ratio`	current value	Ratio compras sobre ventas, ventana de 5 minutos.
`trade_size`	current value	Tamaño medio de las operaciones, ponderado por su número.
`heatmap`	current value	Clústeres de liquidaciones por encima y por debajo del precio.

Todo el mercado y satélites

Campo	Tipo	Descripción
`tokenomics`	current value	Oferta, capitalización y FDV del activo del símbolo.
`global_market`	current value	Capitalización total, volumen, dominancias de BTC y ETH.
`fear_greed`	current value	Índice de sentimiento 0-100 y su clasificación.
`options`	current value	Resumen de opciones del activo deducido del símbolo (solo BTC o ETH).
`macro, macro_correlations, net_liquidity, macro_momentum, macro_risk`	current value	Series macro y los cuatro indicadores derivados.
`btc_network, btc_mempool, btc_fees, btc_mining`	current value	Estado de la red Bitcoin.
`onchain_mvrv, onchain_nvt, onchain_active_addresses, onchain_miner_stress`	current value	Valoración on-chain de Bitcoin, datos diarios.
`eth_supply, eth_gas, eth_gas_momentum, eth_staking, eth_deflation, eth_defi, eth_squeeze, eth_ratio`	current value	Las ocho familias de Ethereum.

#Campos multitemporalidad

Ocho campos existen por temporalidad. Se piden con el sufijo @tf, obligatorio, y la clave vuelve tal cual en data (data["cvd@1h"]).

1m5m15m30m1h4h1d

Campo	Tipo	Descripción
`cvd@tf`	200 windows	Delta de volumen acumulado y su serie interna.
`orderbook_aggregated@tf`	1000 windows	Libro agregado: media, mín., máx. y desviación típica del desequilibrio.
`vwap_window@tf`	1000 windows	VWAP de la ventana, distinto del VWAP intradía.
`spread_interexchange@tf`	50 windows	Prima de cada exchange. El único campo que nombra los exchanges.
`trade@tf`	1440 candles	Velas de operaciones, spot y futuros sumados.
`trade_spot@tf`	1440 candles	Velas de operaciones, solo spot.
`trade_future@tf`	1440 candles	Velas de operaciones, solo futuros.
`ls_ratio@tf`	500 windows	Ratio long/short compuesto. Sin 1m.

Pedir un campo multitemporalidad sin su sufijo devuelve 422, y lo contrario también: un campo de forma única con el sufijo @1h se rechaza.

#Las claves adicionales

partial

Siempre presente. Pasa a true en cuanto una parte de la respuesta no ha podido construirse: el campo afectado vale entonces {"error": "..."} y los demás responden con normalidad. Un fallo local sigue siendo local: nunca obtienes una respuesta vacía porque una familia de siete no estaba disponible.

unavailable

Presente solo si al menos un campo solicitado está vacío. Dice por qué, algo que un null por sí solo no puede hacer.

Respuesta

{
  "data": { "funding_rate_8h": null, "options": null, "heatmap": [] },
  "unavailable": {
    "funding_rate_8h": "not_applicable",
    "options": "not_applicable",
    "heatmap": "no_data"
  }
}

Tres valores, por orden de prioridad: not_applicable (el fenómeno no existe para este activo), no_api_key (la fuente de origen no está conectada, nunca se ha recopilado nada), no_data (una ausencia real en la ventana). Solo el tercero permite una conclusión de mercado.

coverage

Cuántos exchanges han producido la cifra y el efecto de una ausencia. El recuento real viaja fila por fila en venue_count; coverage lleva lo que es constante en todas las filas. El detalle de los valores se describe en la página Convenciones.

out_of_plan_fields

El snapshot devuelve el contenido de las demás familias y está filtrado según tu plan: un campo cuya familia no está en el plan se elimina de data y su nombre aparece en out_of_plan_fields, presente solo en ese caso. Los demás campos responden con normalidad; la petición no se rechaza.

Respuesta

{
  "status": "ok",
  "data_type": "snapshot",
  "partial": false,
  "data": {
    "funding_rate_8h": { "bucket": "...", "rate": 0.000082, "apr": 0.0898 },
    "basis": [ { "timestamp": "...", "basis_pct": 0.059 } ]
  },
  "out_of_plan_fields": ["fear_greed", "onchain_mvrv"]
}

Sin ningún campo solicitado, available_fields solo lista los campos de tu plan. Un snapshot cuyos campos están todos fuera del plan devuelve un data vacío con la lista completa en out_of_plan_fields, nunca un resultado vacío sin explicación. La correspondencia entre familias y planes está en la página de planes; el snapshot en sí está disponible a partir de Traders.

#Errores

Caso	Código
Falta `symbol`	`422`
Símbolo desconocido o desactivado	`400` con la lista de símbolos activos
Campo multitemporalidad sin sufijo, o lo contrario	`422`
Temporalidad desconocida	`422`
Profundidad no entera o inferior a 1	`400`
Profundidad por encima del límite del campo	`400` en un campo de forma única, `422` en uno multitemporalidad
Profundidad más allá de la ventana de historial del plan	`403`, con el `limit` máximo en `detail`
Campo de una familia fuera del plan	no es un error: el campo se elimina y se lista en `out_of_plan_fields`

La ventana de historial del plan se aplica a los campos con fecha igual que a las rutas REST: klines_1m=1000 pide dieciséis horas de velas de 1 min, algo que Free (una hora en 1m) rechaza con un 403 explícito en lugar de devolver sesenta velas bajo el nombre de mil.

403

{
  "detail": "Profondeur d'historique hors offre : 16 heure(s) demandes en 1m, votre offre en autorise 1 heure(s) (soit limit=60 au maximum sur ce timeframe, et aucune borne since_ms/until_ms au-dela de cette fenetre)."
}