GratisGET

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 Gratis. 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 lleva tanto tiempo sin publicar que ningún feriado lo explica (más de 132 horas), 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 lleva más de 132 horas sin renovarse — es decir, más de lo que puede justificar cualquier fin de semana o feriado del calendario venezolano
`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	Anclaje legal. Necesario para cualquier contexto formal sin ser el dominante.
paralelo	20%	Mercado paralelo (informal)	Termómetro social del mercado informal. Limitado para evitar doble conteo con P2P.
p2p	50%	Mediana de Binance, Bybit, OKX, Bitget, MEXC, BingX, Saldo	Capa más transaccional: refleja los precios de compra/venta USDT/VES que cada exchange publica.

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('El BCV lleva sin publicar más de lo que explica el calendario — 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