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

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

Path parameters

Parámetro	Tipo	Requerido	Valores aceptados
`market`	string	Sí	`reference`, `parallel`, `binance`, `bybit`, `okx`, `bitget`, `mexc`

Query parameters

Este endpoint no acepta parámetros de query.

Ejemplos de request

Paralela:

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

const res = await fetch('https://api.cotizave.com/v1/fx/rates/parallel', {
  headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY }
})
const data = await res.json()

import os, requests

r = requests.get(
    'https://api.cotizave.com/v1/fx/rates/parallel',
    headers={'X-API-Key': os.environ['COTIZAVE_API_KEY']}
)
data = r.json()

Binance P2P:

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

Response

200 OK (ejemplo con BCV)

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

200 OK (ejemplo con Binance P2P)

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

Schema de respuesta

Campo	Tipo	Descripción
`market`	string	Identificador del mercado consultado
`type`	string	Tipo: `reference`, `parallel` o `p2p`
`ask`	number	Precio de venta. Omitido si la fuente no lo provee (ej: `reference`).
`bid`	number	Precio de compra. Omitido si la fuente no lo provee.
`mid`	number	Precio promedio. Siempre presente.
`updated_at`	string (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

Widget de tasa BCV en tiempo real

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

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:

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:

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ódigo	`error.code`	Causa
`400`	`missing_field`	El path param `market` está vacío
`401`	`invalid_api_key`	API Key inválida, faltante o revocada
`404`	`resource_not_found`	El `market` solicitado no existe en el snapshot
`429`	`rate_limit_exceeded`	Cuota mensual agotada
`500`	`internal_error`	Error inesperado del lado de Cotizave

Ejemplo: market inexistente

curl https://api.cotizave.com/v1/fx/rates/coinbase \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

{
  "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 completa Siguiente →Conversión