GET /v1/fx/rates

Devuelve un snapshot con todas las tasas disponibles de bolívar venezolano frente a la moneda base.

Es el endpoint principal y el más usado. Una sola llamada te da todo lo que necesitas.

Request

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

Parámetros de query

Este endpoint no acepta parámetros de query. Devuelve siempre el snapshot completo con USD como moneda base.

Ejemplo de request

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

const res = await fetch('https://api.cotizave.com/v1/fx/rates', {
  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',
    headers={'X-API-Key': os.environ['COTIZAVE_API_KEY']}
)
data = r.json()

Response

200 OK

{
  "country": "VE",
  "currency": "VES",
  "base": "USD",
  "rates": [
    {
      "market": "reference",
      "type": "reference",
      "mid": 475.0083,
      "updated_at": "2026-04-08T14:00:00Z"
    },
    {
      "market": "parallel",
      "type": "parallel",
      "ask": 640.12,
      "bid": 637.63,
      "mid": 638.87,
      "updated_at": "2026-04-08T17:25:00Z"
    },
    {
      "market": "binance",
      "type": "p2p",
      "ask": 639.24,
      "bid": 636.50,
      "mid": 637.87,
      "updated_at": "2026-04-08T17:29:00Z"
    },
    {
      "market": "bybit",
      "type": "p2p",
      "ask": 639.88,
      "bid": 637.12,
      "mid": 638.50,
      "updated_at": "2026-04-08T17:29:00Z"
    },
    {
      "market": "okx",
      "type": "p2p",
      "ask": 635.80,
      "bid": 632.70,
      "mid": 634.25,
      "updated_at": "2026-04-08T17:29:00Z"
    },
    {
      "market": "bitget",
      "type": "p2p",
      "ask": 636.10,
      "bid": 632.86,
      "mid": 634.48,
      "updated_at": "2026-04-08T17:29:00Z"
    },
    {
      "market": "mexc",
      "type": "p2p",
      "ask": 650.50,
      "bid": 647.54,
      "mid": 649.02,
      "updated_at": "2026-04-08T17:28:00Z"
    }
  ],
  "index": {
    "value": 521.3842,
    "version": "v1",
    "as_of": "2026-04-08T17:29:15Z",
    "weights": { "bcv": 0.30, "paralelo": 0.20, "p2p": 0.50 },
    "components": { "bcv": 475.0083, "paralelo": 638.87, "p2p": 637.87 },
    "p2p_median": 637.87,
    "p2p_count": 5,
    "flags": {}
  },
  "fetched_at": "2026-04-08T17:29:15Z"
}

Schema de respuesta

Campo	Tipo	Descripción
`country`	string	Siempre `"VE"` (ISO 3166-1 alpha-2 de Venezuela)
`currency`	string	Siempre `"VES"` (ISO 4217 del bolívar soberano)
`base`	string	Moneda base usada en las tasas (`USD` o `EUR`)
`rates`	array	Lista de cotizaciones
`rates[].market`	string	Identificador del mercado (ver tabla abajo)
`rates[].type`	string	Tipo de tasa: `reference`, `parallel` o `p2p`
`rates[].ask`	number \| null	Precio de venta. Presente solo en `parallel` y `p2p`.
`rates[].bid`	number \| null	Precio de compra. Presente solo en `parallel` y `p2p`.
`rates[].mid`	number	Precio promedio. Siempre presente.
`rates[].updated_at`	string (ISO 8601)	Cuándo se actualizó esta cotización específica
`index`	object	Cotizave Index calculado al momento del snapshot. Mismo shape que GET /v1/fx/index. Siempre presente.
`index.value`	number	VES por 1 USD — el índice ponderado (BCV 30 % + paralela 20 % + P2P 50 %).
`fetched_at`	string (ISO 8601)	Cuándo Cotizave ensambló esta respuesta

Markets disponibles

Market	Tipo	Fuente	Frecuencia
`reference`	reference	BCV	Cuando BCV publica (típicamente 1/día)
`parallel`	parallel	Monitor Dólar	~25 minutos
`binance`	p2p	Binance P2P USDT/VES	~25 minutos
`bybit`	p2p	Bybit P2P USDT/VES	~25 minutos
`okx`	p2p	OKX P2P USDT/VES	~25 minutos
`bitget`	p2p	Bitget P2P USDT/VES	~25 minutos
`mexc`	p2p	MEXC P2P USDT/VES	~25 minutos

Tasas `reference` vs `parallel` vs `p2p`

reference (BCV): la tasa oficial publicada por BCV. Úsala para:

Documentos oficiales y presupuestos
Reportes contables y financieros
Contratos y acuerdos comerciales
Análisis de auditoría

parallel (paralela): el promedio de mercado del paralelo. Úsala para:

Mostrar "la tasa real" en apps consumer
Remesas informales
Conversiones rápidas en la vida diaria
Comparación contra la oficial

p2p (exchanges): cotizaciones reales de USDT/VES en cada exchange. Úsalas para:

Apps de trading o wallet crypto
Comparación de precios entre exchanges
Análisis de spreads
Estrategias de arbitraje

Casos de uso típicos

Mostrar el tipo de cambio en tu app

Trae el snapshot completo, localiza la tasa BCV y muéstrasela al usuario:

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

const bcv = data.rates.find(r => r.market === 'reference')
console.log(`Tasa BCV: ${bcv.mid} Bs/USD`)

Widget de conversión multi-mercado

Deja que el usuario elija el mercado y muestra todas las tasas side-by-side con una sola llamada:

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

// Renderiza cada market con su mid
data.rates.forEach(r => {
  console.log(`${r.market}: ${r.mid} Bs/USD`)
})

Monitoreo de spreads entre mercados

Consulta periódicamente y compara bid/ask entre mercados P2P para detectar oportunidades:

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

const p2p = data.rates.filter(r => r.type === 'p2p')
p2p.forEach(r => {
  const spread = r.ask - r.bid
  console.log(`${r.market} — bid: ${r.bid}, ask: ${r.ask}, spread: ${spread.toFixed(2)}`)
})

Errores posibles

Código	`error.code`	Causa
`401`	`invalid_api_key`	API Key inválida, faltante o revocada
`429`	`rate_limit_exceeded`	Cuota mensual agotada
`500`	`internal_error`	Error inesperado del lado de Cotizave
`503`	`service_unavailable`	Servicio temporalmente no disponible

Notas importantes

Fuentes temporalmente caídas

En casos excepcionales, una fuente upstream puede estar temporalmente caída. En ese caso:

El campo updated_at refleja la edad real del dato (puede ser más viejo de lo habitual)
Si una fuente está caída por más de 10 minutos, la excluimos de la respuesta en lugar de devolver datos peligrosamente desactualizados

Recomendación: siempre revisa updated_at antes de confiar en un dato para operaciones críticas.

Orden de los rates

El orden del array rates no está garantizado. No dependas de que reference siempre esté primero. Usa el campo market para identificar cada cotización:

const bcv = data.rates.find(r => r.market === 'reference')
const paralela = data.rates.find(r => r.market === 'parallel')

Precisión numérica

Los valores son números JSON estándar (double-precision floating point). Para operaciones financieras críticas, considera:

Redondear a 2-4 decimales antes de mostrar al usuario
Usar bibliotecas de aritmética decimal (decimal.js, BigDecimal en Java, Decimal en Python) si haces cálculos complejos
No comparar montos exactos con === (usar tolerancia)

← AnteriorErrores Siguiente →Tasa por mercado