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

shell

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

Query parameters

Parámetro	Tipo	Requerido	Default	Descripción
`against`	string	No	`parallel`	Contra qué market calcular el spread. Valores: `parallel`, `binance`, `bybit`, `okx`, `bitget`, `mexc`, etc.
`base`	string	No	`USD`	Moneda base. Solo se soporta `USD` (`EUR` aún no disponible).

Ejemplos de request

Spread BCV vs paralela (default):

cURL

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

Spread BCV vs Binance:

shell

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

Response

200 OK

json

{ "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

Campo	Tipo	Descripción
`reference.market`	string	Siempre `"reference"` (BCV)
`reference.value`	number	Valor de la tasa BCV
`reference.updated_at`	string	Timestamp de actualización del BCV
`compared.market`	string	Market contra el que se comparó
`compared.value`	number	Valor de la tasa del market comparado
`compared.updated_at`	string	Timestamp de actualización del market comparado
`spread.absolute`	number	Diferencia absoluta: `compared.value - reference.value`
`spread.percentage`	number	Diferencia porcentual respecto al BCV: `(compared - reference) / reference × 100`
`spread.direction`	string	`"higher"` si compared > reference, `"lower"` si compared < reference, `"equal"` si son iguales
`fetched_at`	string	Timestamp del cálculo

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:

javascript

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:

javascript

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:

javascript

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:

javascript

// 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

Código	`error.code`	Causa
`400`	`invalid_against`	El market especificado no existe o es `reference` (no puedes comparar BCV contra sí mismo)
`400`	`invalid_base`	`base` no es `USD`
`401`	`unauthorized`	API Key inválida
`422`	`reference_unavailable`	No hay datos del BCV disponibles (muy raro)
`422`	`compared_unavailable`	No hay datos del market comparado disponibles
`429`	`rate_limit_exceeded`	Cuota mensual agotada

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 5 minutos

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:

javascript

const data = await fetch('https://api.cotizave.com/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.

← AnteriorConversión Siguiente →Histórico