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, bingx, coinex, saldo |
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), 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 | Sin acceso a histórico |
| Indie | 90 días |
| Pro | 1 año |
El modo colección sin parámetros devuelve exactamente esa ventana.
Disponibilidad por market
La retención de tu plan define hasta dónde puedes consultar. Cada market además tiene su propia fecha de inicio de serie:
| Market | Histórico disponible |
|---|---|
reference · eur_reference | Toda la retención de tu plan |
yadio | Toda la retención de tu plan |
parallel | Desde febrero 2026 |
binance · bybit · okx · bitget · mexc · bingx · saldo | Desde mayo 2026 |
paypal · zelle | Desde agosto 2026 |
cash · cucuta · syklo · zoom · western_union | Desde agosto 2026 |
Si pides una fecha anterior al inicio de la serie de un market, recibes 404 resource_not_found. Si pides una anterior a la retención de tu plan, recibes 403 history_out_of_retention. No son lo mismo: el primero significa que el dato no existe; el segundo, que existe pero tu plan no alcanza.