FreeGET

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

shell

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

No acepta parámetros. La respuesta es determinista dado el snapshot subyacente.

Ejemplo

cURL

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

Response

200 OK — caso normal

json

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

json

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

json

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

json

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

código

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:

javascript

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:

javascript

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:

javascript

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

javascript

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

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)

← AnteriorDiferencial Siguiente →Histórico