GET /v1/fx/rates/:market/history
Devuelve el histórico de tasas de un market específico. Útil para reportes contables, auditoría, backfill de datos y análisis retrospectivo. El query string elige el modo, y la forma de la respuesta cambia en consecuencia:
?date=YYYY-MM-DD→ un punto: la cotización vigente en esa fecha (devuelve 1 objeto).- sin parámetros → toda la serie dentro de la retención de tu plan (devuelve un array).
?from=&to=→ un rango de fechas (devuelve un array).
En modo punto, el endpoint busca el registro más cercano a esa fecha o anterior (no posterior). Esto es importante: en días no hábiles del BCV, el valor "vigente" es el último publicado.
Request
Path parameters
| Parámetro | Tipo | Requerido | Valores aceptados |
|---|---|---|---|
market | string | Sí | reference, parallel, binance, bybit, okx, bitget, mexc |
Query parameters
| Parámetro | Tipo | Requerido | Formato | Descripción |
|---|---|---|---|---|
date | string | No | YYYY-MM-DD | Modo punto. Fecha de la cotización buscada (UTC). No puede estar en el futuro. Si se omite, el endpoint entra en modo colección. |
from | string | No | YYYY-MM-DD | Modo colección. Inicio del rango (inclusive). Por defecto, el más antiguo que tu plan permite. No puede ser más viejo que la retención de tu plan. |
to | string | No | YYYY-MM-DD | Modo colección. Fin del rango (inclusive). Por defecto, hoy. Una fecha futura se ajusta a hoy. |
granularity | string | No | daily · raw | Modo colección. daily (default): un punto de cierre por día. raw: cada captura, hasta 5.000 puntos (luego truncated: true). |
Ejemplos de request
Tasa BCV del 1 de marzo de 2026:
Tasa Binance P2P del 15 de enero de 2026:
Toda la serie disponible (un punto diario por toda tu retención):
Un rango de fechas (diario):
Detalle intradía (cada captura, no solo el cierre): agrega granularity=raw. Para un solo día, usa el mismo valor en from y to:
Response
200 OK
Schema de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
market | string | Identificador del market consultado |
date | string | Fecha pedida en el query (eco) |
rate | number | Cotización vigente (mid). VES por unidad de USD. |
updated_at | string (ISO 8601) | Cuándo se actualizó la fuente original (BCV, exchange, etc.) |
captured_at | string (ISO 8601) | Cuándo Cotizave persistió el snapshot |
200 OK — modo colección
Cuando no envías date, la respuesta es un objeto con metadata del rango y un array points:
| Campo | Tipo | Descripción |
|---|---|---|
from · to | string | Rango efectivo resuelto por el servidor (UTC) |
granularity | string | daily o raw |
count | number | Cantidad de elementos en points |
truncated | boolean | Solo en raw: true si se superó el tope de 5.000 puntos |
points[] | array | Cada punto: date, rate, updated_at, captured_at. Orden cronológico. |
updated_at vs captured_at
Los dos timestamps suelen ser distintos:
updated_at: cuándo el dato fue producido por la fuente original. Para BCV es la hora de publicación oficial; para P2P, la hora del último trade observado.captured_at: cuándo Cotizave consumió e indexó ese dato. Suele estar dentro de los siguientes minutos.
Para auditoría contable normalmente importa updated_at. Para reproducir "qué sabíamos en ese momento", importa captured_at.
Comportamiento "closest-or-before"
El endpoint devuelve el registro más cercano a la fecha pedida, pero nunca posterior. Ejemplos:
- Si pides BCV del domingo y BCV no publicó, recibes el valor del viernes previo.
- Si pides una fecha previa al primer registro disponible, recibes 404
resource_not_found. - Si pides una fecha en el futuro, recibes 400
invalid_format.
Esto es a propósito: para reportes legales y contables el valor "vigente" en un día no hábil del BCV es el último publicado, no una proyección.
Errores posibles
| Código | error.code | Causa |
|---|---|---|
400 | missing_field | Falta el path market |
400 | invalid_format | date/from/to no respeta YYYY-MM-DD, fecha futura, from posterior a to, o granularity inválida |
403 | feature_not_in_plan · history_out_of_retention | Tu plan no incluye histórico (Free/Hobby/Starter), o la fecha pedida es más vieja que la retención de tu plan |
401 | invalid_api_key | API Key inválida o faltante |
404 | resource_not_found | No hay registros para ese market en esa fecha o anterior |
429 | rate_limit_exceeded | Cuota mensual agotada |
503 | service_unavailable | Histórico no disponible (configuración del entorno) |
Casos de uso típicos
Reproducir una factura emitida en el pasado
Para auditar o reemitir una factura con la tasa BCV original:
Backfill de series temporales
Para reconstruir tu propia tabla de tasas mensual:
Notas importantes
Zona horaria
El parámetro date se interpreta en UTC. Si tu negocio opera en huso horario VET (UTC-4), considera que "hoy" en VET puede ser "ayer" en UTC para algunas horas del día.
Profundidad histórica y retención por plan
Cuánto histórico puedes consultar depende de tu plan:
| Plan | Retención de histórico |
|---|---|
| Free · Hobby · Starter | Sin acceso a histórico |
| Indie | 90 días |
| Pro | 1 año |
El modo colección sin parámetros devuelve exactamente esa ventana. Además, el histórico se persiste a partir de la incorporación de cada market al producto: si pides una fecha previa a esa incorporación, recibes resource_not_found. Para BCV (reference) la profundidad es la mayor del producto.