GET /v1/fx/index
El Cotizave Index condensa el mercado cambiario venezolano en una sola cifra: cuántos bolívares (VES) vale un dólar (USD) combinando la tasa oficial del BCV, el mercado paralelo y la mediana real de operaciones P2P en 7 exchanges.
Disponible para todos los planes, incluyendo Free. Cuenta como 1 unidad de quota mensual.
Request
GET /v1/fx/index HTTP/1.1
Host: api.cotizave.com
X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3dNo acepta parámetros. La respuesta es determinista dado el snapshot subyacente.
Ejemplo
curl https://api.cotizave.com/v1/fx/index \ -H "X-API-Key: $COTIZAVE_API_KEY"
Response
200 OK — caso normal
{
"value": 521.3842,
"version": "v1",
"as_of": "2026-05-10T14:32:11Z",
"weights": {
"bcv": 0.30,
"paralelo": 0.20,
"p2p": 0.50
},
"components": {
"bcv": 475.0083,
"paralelo": 538.87,
"p2p": 544.20
},
"p2p_median": 544.20,
"p2p_count": 7,
"flags": {},
"methodology_url": "https://cotizave.com/docs/cotizave-index"
}200 OK — con flags activos
Cuando el BCV tiene más de 26 horas sin actualizarse, su peso se redistribuye y se activa el flag bcv_stale:
{
"value": 542.1100,
"version": "v1",
"as_of": "2026-05-10T14:32:11Z",
"weights": {
"bcv": 0,
"paralelo": 0.2857,
"p2p": 0.7143
},
"components": {
"paralelo": 538.87,
"p2p": 544.20
},
"p2p_median": 544.20,
"p2p_count": 7,
"flags": {
"bcv_stale": true
},
"methodology_url": "https://cotizave.com/docs/cotizave-index"
}200 OK — outlier excluido
Si un exchange P2P reporta una tasa anómala (más del 50% alejada de la mediana del grupo), se excluye automáticamente:
{
"value": 518.9920,
"version": "v1",
"as_of": "2026-05-10T14:32:11Z",
"weights": {
"bcv": 0.30,
"paralelo": 0.20,
"p2p": 0.50
},
"components": {
"bcv": 475.0083,
"paralelo": 538.87,
"p2p": 543.10
},
"p2p_median": 543.10,
"p2p_count": 6,
"flags": {
"outliers_excluded": ["saldo"]
},
"methodology_url": "https://cotizave.com/docs/cotizave-index"
}200 OK — modo degradado
Cuando quedan menos de 4 exchanges P2P activos, el Index se marca como degradado pero sigue funcionando:
{
"value": 508.7400,
"version": "v1",
"as_of": "2026-05-10T14:32:11Z",
"weights": {
"bcv": 0.30,
"paralelo": 0.20,
"p2p": 0.50
},
"components": {
"bcv": 475.0083,
"paralelo": 538.87,
"p2p": 527.50
},
"p2p_median": 527.50,
"p2p_count": 3,
"flags": {
"degraded": true
},
"methodology_url": "https://cotizave.com/docs/cotizave-index"
}Schema de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
value | number | VES por 1 USD — el valor canónico del Index (4 decimales) |
version | string | Versión de la metodología. Actualmente "v1" |
as_of | string (ISO 8601) | Timestamp del snapshot subyacente. Distinto al momento del request si el snapshot está en cache. |
weights | object | Pesos efectivos usados en el cálculo. Pueden diferir de los nominales (30/20/50) cuando un componente está ausente. |
components | object | Valor de cada componente antes de aplicar pesos. Solo aparecen los componentes disponibles. |
p2p_median | number | Mediana de los exchanges P2P que contribuyeron (después de excluir outliers) |
p2p_count | integer | Número de exchanges P2P que contribuyeron al cálculo. Máximo 7. |
flags.bcv_stale | boolean (omitempty) | Presente si la tasa BCV tiene más de 26 horas sin actualizarse |
flags.degraded | boolean (omitempty) | Presente si menos de 4 exchanges P2P están disponibles |
flags.missing_sources | string[] (omitempty) | Componentes ausentes del snapshot. Su peso fue redistribuido. |
flags.outliers_excluded | string[] (omitempty) | Exchanges P2P excluidos por desviación extrema (>50% de la mediana del grupo) |
methodology_url | string | URL a la documentación pública de la metodología |
Metodología
Fórmula base
Index = BCV × 0.30 + Paralelo × 0.20 + MedianaP2P × 0.50| Componente | Peso v1 | Fuente | Por qué |
|---|---|---|---|
| bcv | 30% | BCV oficial vía DolarAPI | Anclaje legal. Necesario para cualquier contexto formal sin ser el dominante. |
| paralelo | 20% | Monitor Dólar vía DolarAPI | Termómetro social del mercado informal. Limitado para evitar doble conteo con P2P. |
| p2p | 50% | Mediana de Binance, Bybit, OKX, Bitget, MEXC, BingX, Saldo (vía CriptoYa) | Capa más transaccional: precios reales de compra/venta USDT/VES con libro de órdenes verificable. |
Por qué mediana y no promedio en P2P
La mediana de los 7 exchanges es resistente a manipulación: aunque un exchange reporte un precio anómalo (stale, glitch de API, o intento deliberado de sesgar), la mediana no se mueve mientras la mayoría de exchanges reporte valores normales. Un promedio simple, en cambio, puede ser distorsionado por un solo valor extremo.
Renormalización de pesos
Cuando un componente no está disponible, su peso se redistribuye proporcionalmente entre los restantes. Los pesos efectivos siempre suman 1.0 y aparecen en el campo weights de la respuesta.
Casos de uso
Cita en periodismo y análisis económico
Cuando necesitas una sola cifra representativa del tipo de cambio venezolano sin tomar partido entre BCV, paralela o P2P:
const idx = await fetch('https://api.cotizave.com/v1/fx/index', {
headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY }
}).then(r => r.json())
console.log(`El Cotizave Index es ${idx.value.toFixed(2)} Bs/USD (v${idx.version})`)
// "El Cotizave Index es 521.38 Bs/USD (v1)"Dashboard fintech
Mostrar una tasa única en lugar de múltiples cotizaciones que confunden al usuario:
const idx = await getIndex()
const display = {
rate: idx.value,
label: 'Cotizave Index',
isStale: idx.flags.bcv_stale ?? false,
isDegraded: idx.flags.degraded ?? false,
sources: Object.keys(idx.components).join(', ')
}Referencia para estimaciones internas
Para valorar activos, calcular presupuestos o estimar costos en VES sin comprometerse con una sola fuente:
// Valorar un activo de USD 50,000 al Cotizave Index
const idx = await getIndex()
const vesValue = 50_000 * idx.value
console.log(`Valor estimado: ${vesValue.toLocaleString()} VES`)
console.log(`Referencia: Cotizave Index v${idx.version}, as_of ${idx.as_of}`)Detectar anomalías del mercado
Los flags te permiten alertar cuando la calidad de la tasa es reducida:
const idx = await getIndex()
if (idx.flags.bcv_stale) {
console.warn('BCV sin actualizar por más de 26h — tasa calculada sin componente oficial')
}
if (idx.flags.degraded) {
console.warn(`Solo ${idx.p2p_count} exchanges P2P disponibles — Index menos confiable`)
}
if (idx.flags.outliers_excluded?.length) {
console.info(`Outliers excluidos: ${idx.flags.outliers_excluded.join(', ')}`)
}Disclaimer
Tasa de referencia informativa
El Cotizave Index es una tasa de referencia informativa. NO debe usarse para liquidar transacciones financieras, contratos, declaraciones fiscales, ni como tasa oficial de ningún tipo. Para efectos legales en Venezuela, la tasa vigente es la publicada por el Banco Central de Venezuela (BCV). El uso del Index para cualquier finalidad regulatoria o contractual es responsabilidad exclusiva del usuario.
Errores posibles
| Código HTTP | error.code | Causa |
|---|---|---|
401 | unauthorized | API Key inválida o revocada |
429 | rate_limit_exceeded | Cuota mensual agotada |
503 | service_unavailable | Ningún componente disponible en el snapshot (extremadamente raro) |