Convenciones de la API

Reglas comunes a todos los endpoints: estructura de las URL, envoltorio de la respuesta, símbolos, unidades, marcas de tiempo, paginación y caché.

URL base y versionado

Todos los endpoints cuelgan de una única URL base y se llaman con GET por HTTPS. Las rutas actuales corresponden a la versión v1. Dentro de v1 los cambios son aditivos: pueden añadirse campos y endpoints, y los campos existentes conservan su nombre, tipo y significado. Un cambio incompatible se publicaría bajo una ruta nueva y se anunciaría antes en el registro de cambios.

URL basehttps://www.coinboss.com/api

Envoltorio de la respuesta

Toda respuesta JSON tiene un indicador success en el nivel superior. Los endpoints de la capa de datos de recopilación propia (rutas bajo /api/sd) comparten además los mismos bloques adicionales:

Campo	Descripción
success	true cuando la llamada funcionó. Compruébelo siempre.
schema	Identificador y versión mayor de la estructura de la respuesta.
now	Hora del servidor en el momento de componer la respuesta, en milisegundos.
coverage	Qué exchanges están incluidos, cuáles no están disponibles y por qué, y cuáles se excluyeron por estar desactualizados.
method	La fórmula o regla que sustenta cada agregado de la respuesta.
meta	Fuentes, marcas de tiempo, ventana, calificación de calidad, indicador de desactualización, vida de la caché y comportamiento de respaldo.

Los endpoints más antiguos devuelven success junto con un campo data y pueden no incluir coverage, method ni meta. Sus páginas de referencia documentan los campos exactos.

Monedas, contratos y exchanges

Los parámetros coin reciben el símbolo base en mayúsculas, por ejemplo BTC o PEPE.
Los contratos con multiplicador, como 1000PEPE o kPEPE, se fusionan con su moneda base y sus cantidades se convierten.
Los identificadores de exchange van en minúsculas, por ejemplo binance, okx, bybit, hyperliquid.
Los símbolos de contrato se devuelven tal como los nombra el exchange. Los contratos con margen en USDT, en USDC y en moneda, y los futuros con vencimiento, se distinguen mediante un campo de tipo de contrato en los endpoints que los mezclan.
Los perpetuos de acciones tokenizadas y de materias primas que comparten ticker con un criptoactivo se excluyen de los agregados cripto.

Unidades

Los campos terminados en _usd son nocional en dólares estadounidenses.
Las tasas de financiación son fracciones, no porcentajes: 0.0001 significa 0.01%. Los campos terminados en _8h están normalizados a un intervalo de 8 horas; el intervalo original se devuelve junto a la tasa sin normalizar.
Los campos terminados en _pct son porcentajes: 1.5 significa 1.5%.
El interés abierto es nocional en USD contado por un solo lado, salvo que la descripción de un campo indique otra cosa. Los exchanges que publican cifras contadas por ambos lados se señalan en el bloque method.
Algunos endpoints heredados devuelven los decimales como cadenas para conservar la precisión. La tabla de campos muestra el tipo como string(decimal).

Marcas de tiempo

Las marcas de tiempo son milisegundos de época Unix en UTC, salvo que la descripción de un campo indique otra cosa.
observed_at es la marca de tiempo del propio exchange para el registro más reciente incluido, o null cuando el exchange no la proporciona.
received_at es el momento en que el recolector de CoinBoss almacenó ese registro.
fetched_at es el momento en que se compuso la respuesta. En una respuesta en caché es anterior a la hora de la llamada, como máximo en el TTL de la caché.
Las series diarias usan los límites del día en UTC.

Ventanas e intervalos

Los parámetros de ventana usan tokens cortos: 1h, 4h, 12h, 24h y, en algunos endpoints, 3d, 7d, 30d, 90d. La página de referencia indica los valores aceptados por cada endpoint.
Un valor de ventana desconocido se rechaza con INVALID_PARAM o se sustituye por el valor por defecto documentado, según se indique en cada parámetro.
El tamaño del tramo de las series temporales depende de la ventana y se indica en la página de referencia.

Paginación y ordenación

Los endpoints de listado usan limit y offset, o page y size, según se documente en cada endpoint. Los límites tienen un tope; un valor mayor se reduce al tope.
Cuando una respuesta incluye total, se trata del número de filas antes de la paginación.
El orden es fijo, salvo que el endpoint documente un parámetro sort.

Null, cero y ausente

null significa que el valor es desconocido o no está disponible. 0 significa un cero medido.
Los gráficos deben mostrar un hueco para null. No interpole.
Un campo marcado como «puede faltar» en una tabla de campos puede no aparecer en absoluto en el objeto; trátelo como null.

Caché

Cada endpoint tiene un TTL de caché del servidor, indicado en su página de referencia y en meta.cache_ttl_s. La cabecera X-Cache informa de HIT, STALE o MISS.
Delante de la mayoría de los endpoints GET hay una caché de borde de corta duración, de unos diez segundos.
Consultar con más frecuencia que el TTL devuelve datos idénticos y solo consume su límite de solicitudes.

WebSocket

WebSocketwss://www.coinboss.com/ws

El flujo es JSON de solo envío por parte del servidor. Cada mensaje tiene un campo type.
Tras una desconexión, reconecte con un retardo y recupere los datos perdidos desde el endpoint HTTP correspondiente.

Documentación legible por máquina

El catálogo, los parámetros y la tabla de campos de cada endpoint, el estado y la matriz de calidad están disponibles como JSON bajo /api/meta, y el catálogo completo como documento OpenAPI 3.