GET /v1/fx/spread

Calcula el spread (brecha) entre la tasa oficial del BCV y otra tasa de mercado. Útil para análisis económico, reportes y dashboards.

Request

GET /v1/fx/spread HTTP/1.1
Host: api.cotizave.com
X-API-Key: nd-tu-api-key-aqui

Query parameters

Ejemplos de request

Spread BCV vs paralela (default):

curl https://api.cotizave.com/v1/fx/spread \
  -H "X-API-Key: nd-tu-api-key-aqui"

Spread BCV vs Binance:

curl "https://api.cotizave.com/v1/fx/spread?against=binance" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Response

200 OK

{
  "reference": {
    "market": "reference",
    "value": 475.0083,
    "updated_at": "2026-04-08T14:00:00Z"
  },
  "compared": {
    "market": "parallel",
    "value": 638.87,
    "updated_at": "2026-04-08T17:25:00Z"
  },
  "spread": {
    "absolute": 163.8617,
    "percentage": 34.49,
    "direction": "higher"
  },
  "fetched_at": "2026-04-08T17:29:15Z"
}

Schema de respuesta

Interpretación del spread

direction: "higher" (el caso más común): el market comparado vale más que la tasa oficial. Esto es lo normal en Venezuela, donde el paralelo y los P2P suelen estar por encima del BCV.

direction: "lower" (raro): el market comparado vale menos que la tasa oficial. Esto puede pasar muy ocasionalmente cuando el BCV sube bruscamente y los otros markets todavía no se ajustaron.

direction: "equal" (muy raro): ambas tasas son iguales. Solo puede pasar momentáneamente durante transiciones.

Ejemplo: spread del 34.49%

En el ejemplo:

• BCV: 475.01 Bs/USD
• Paralela: 638.87 Bs/USD
• Diferencia absoluta: 163.86 Bs
• Spread porcentual: 34.49% (el paralelo está 34.49% por encima del BCV)

Casos de uso típicos

Dashboard de salud económica

Mostrar el spread BCV/paralela como indicador de la brecha cambiaria:

const spread = await fetchSpread('parallel')
console.log(`Brecha BCV/paralela: ${spread.spread.percentage.toFixed(2)}%`)
// Output: "Brecha BCV/paralela: 34.49%"

Alertas de movimientos bruscos

Si el spread crece o decrece significativamente en un período corto, puede indicar tensión cambiaria:

const current = await fetchSpread('parallel')
const lastKnown = await db.get('last_spread')

if (lastKnown && Math.abs(current.spread.percentage - lastKnown) > 5) {
  await sendAlert(`Spread cambió ${current.spread.percentage - lastKnown}% en la última hora`)
}
await db.set('last_spread', current.spread.percentage)

Comparación de exchanges P2P vs BCV

Para ver cuál exchange P2P tiene la menor brecha con la tasa oficial:

const markets = ['binance', 'bybit', 'okx', 'bitget', 'mexc']
const spreads = await Promise.all(
  markets.map(async m => ({
    market: m,
    spread: (await fetchSpread(m)).spread.percentage
  }))
)

spreads.sort((a, b) => a.spread - b.spread)
console.log('Menor brecha con BCV:', spreads[0])

Reportes mensuales

Para generar un reporte mensual de evolución del spread, combina este endpoint con un almacenamiento propio de series temporales:

// Cron job diario que guarda el spread en tu DB
const spread = await fetchSpread('parallel')
await db.query(`
  INSERT INTO spread_history (date, bcv, parallel, spread_pct)
  VALUES ($1, $2, $3, $4)
`, [new Date(), spread.reference.value, spread.compared.value, spread.spread.percentage])

Errores posibles

Notas importantes

Frescura de los datos

Recuerda que las fuentes se actualizan con frecuencias distintas:

• BCV: cuando publica (típicamente una vez al día)
• Paralela: cada 5 minutos
• P2P: cada minuto

Esto significa que el spread calculado puede comparar una tasa BCV del día y una paralela de hace 3 minutos. La diferencia temporal entre los datos es natural y esperable.

Si necesitas comparar dos momentos exactos del mismo timestamp, tendrías que guardar las tasas a lo largo del tiempo y calcularlo tú mismo.

Alternativa: calcular el spread manualmente

Si ya tienes el snapshot de /v1/fx/rates, puedes calcular el spread sin una llamada adicional:

const data = await fetch('/v1/fx/rates').then(r => r.json())
const bcv = data.rates.find(r => r.market === 'reference').mid
const parallel = data.rates.find(r => r.market === 'parallel').mid
const spreadPct = ((parallel - bcv) / bcv) * 100

Usar /v1/fx/spread es más conveniente si solo necesitas el spread y no las tasas individuales.