← Volver a docs

GET /v1/fx/rates/:market

Devuelve la cotización actualizada de un market específico. Útil cuando solo necesitas una tasa puntual y no quieres traer todas.

Request

shell
GET /v1/fx/rates/:market HTTP/1.1 Host: api.cotizave.com X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d

Path parameters

ParámetroTipoRequeridoValores aceptados
marketstringSíreference, parallel, binance, bybit, okx, bitget, mexc

Query parameters

Este endpoint no acepta parámetros de query.

Ejemplos de request

Paralela:

cURL
curl https://api.cotizave.com/v1/fx/rates/parallel \ -H "X-API-Key: $COTIZAVE_API_KEY"

Binance P2P:

shell
curl https://api.cotizave.com/v1/fx/rates/binance \ -H "X-API-Key: $COTIZAVE_API_KEY"

Response

200 OK (ejemplo con BCV)

json
{ "market": "reference", "type": "reference", "mid": 475.0083, "updated_at": "2026-04-08T14:00:00Z" }

200 OK (ejemplo con Binance P2P)

json
{ "market": "binance", "type": "p2p", "ask": 639.24, "bid": 636.50, "mid": 637.87, "updated_at": "2026-04-08T17:29:00Z" }

Schema de respuesta

CampoTipoDescripción
marketstringIdentificador del mercado consultado
typestringTipo: reference, parallel o p2p
asknumberPrecio de venta. Omitido si la fuente no lo provee (ej: reference).
bidnumberPrecio de compra. Omitido si la fuente no lo provee.
midnumberPrecio promedio. Siempre presente.
updated_atstring (ISO 8601)Cuándo se actualizó esta cotización

Cuándo usar este endpoint vs /v1/fx/rates

Usa /v1/fx/rates/:market cuando:

  • Solo necesitas una tasa específica y no quieres payload adicional
  • Tu app muestra solo una cotización (ej: "Tasa BCV: Bs. 475")
  • Estás construyendo un endpoint interno que consulta una tasa puntual
  • Necesitas el mínimo payload posible para eficiencia de red

Usa /v1/fx/rates cuando:

  • Necesitas varias tasas al mismo tiempo (ej: mostrar un dashboard comparativo)
  • Quieres una sola llamada que traiga todo (más eficiente que N llamadas individuales)

Regla práctica: si vas a mostrar más de 2 tasas, usa /v1/fx/rates. Si vas a mostrar 1 o 2 específicas, usa los endpoints individuales.

Casos de uso típicos

Tasa BCV en tiempo real

Consulta solo la tasa BCV en un intervalo y muéstrala al usuario sin traer el snapshot completo:

javascript
async function fetchBCV() { const res = await fetch('https://api.cotizave.com/v1/fx/rates/reference', { headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY } }) const data = await res.json() return data.mid // Bs/USD } // Actualizar cada 5 minutos setInterval(async () => { const rate = await fetchBCV() document.getElementById('bcv-rate').textContent = rate.toFixed(2) }, 5 * 60 * 1000)

Mostrar solo la paralela

Payload mínimo cuando solo necesitas la tasa paralela, sin datos extra:

javascript
const res = await fetch('https://api.cotizave.com/v1/fx/rates/parallel', { headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY } }) const { mid, updated_at } = await res.json() console.log(`Paralela: ${mid} Bs/USD (actualizada ${updated_at})`)

Integración con facturación en bolívares

Para facturas denominadas en VES según BCV, consulta solo el market reference antes de emitir:

javascript
const res = await fetch('https://api.cotizave.com/v1/fx/rates/reference', { headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY } }) const { mid, updated_at } = await res.json() const amountVES = invoiceUSD * mid console.log(`Monto factura: Bs. ${amountVES.toFixed(2)} (tasa BCV del ${updated_at})`)

Errores posibles

Códigoerror.codeCausa
400missing_fieldEl path param market está vacío
401invalid_api_keyAPI Key inválida, faltante o revocada
404resource_not_foundEl market solicitado no existe en el snapshot
429rate_limit_exceededCuota mensual agotada
500internal_errorError inesperado del lado de Cotizave

Ejemplo: market inexistente

shell
curl https://api.cotizave.com/v1/fx/rates/coinbase \ -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"
json
{ "code": "resource_not_found", "message": "The requested resource was not found." }

Usa solo los markets listados en la tabla de path parameters. Si el market no está en el snapshot actual, recibirás también resource_not_found.

← AnteriorConsulta completaSiguiente →Conversión