> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotizave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brecha entre mercados

> Compara BCV USD/VES con otro mercado en la misma moneda base.

`GET /v1/fx/spread` · **Esencial o superior**. Compara BCV con un mercado; no es el spread bid/ask de un exchange.

<span id="request" />

## Consulta

`against` es opcional y vale `parallel` por defecto. `base` solo acepta `USD` (por defecto). No compares con `reference` ni `eur_reference`. Se admiten `format` y únicamente los parámetros documentados.

Los ejemplos se ejecutan en el servidor. JavaScript y Python usan los clientes del [inicio rápido](/api/quickstart#paso-2); configura allí `COTIZAVE_API_KEY`.

<CodeGroup>
  ```bash curl theme={null}
  curl --fail-with-body --max-time 10 "https://api.cotizave.com/v1/fx/spread?against=parallel&base=USD" \
    -H "X-API-Key: $COTIZAVE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { cotizave } from './cotizave.mjs';

  const data = await cotizave('/v1/fx/spread?against=parallel&base=USD');
  console.log(data);
  ```

  ```python Python theme={null}
  from cotizave import cotizave

  data = cotizave('/v1/fx/spread?against=parallel&base=USD')
  print(data)
  ```
</CodeGroup>

<span id="response" />

## Respuesta

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

```json theme={null}
{
  "reference": {
    "market": "reference",
    "value": 475.0083,
    "updated_at": "2026-10-19T04:00:00Z"
  },
  "compared": {
    "market": "parallel",
    "value": 638.87,
    "updated_at": "2026-10-19T17:25:00Z"
  },
  "spread": {
    "absolute": 163.8617,
    "percentage": 34.5,
    "direction": "higher"
  },
  "fetched_at": "2026-10-19T17:29:15Z"
}
```

`absolute = compared.value - reference.value`, redondeado a 4 decimales. `percentage = absolute / reference.value × 100`, calculado antes del redondeo y devuelto con 2 decimales. `direction` es `higher`, `lower` o `equal`; `absolute` puede ser negativo.

<span id="casos-uso" />

## Indicadores y alertas

Muestra la brecha junto con los dos `updated_at`; las fuentes tienen frecuencias distintas. Para comparar varios mercados en una interfaz puedes partir de un único snapshot y aplicar la misma fórmula a cotizaciones USD.

<span id="errores" />

## Errores

| Estado / código | Causa |
| - | - |
| `400 invalid_base` | Base distinta de USD. |
| `400 invalid_against` | Comparación consigo mismo, mercado desconocido o base incompatible. |
| `400 unknown_parameter` | Parámetro no admitido. |
| `402 feature_not_in_plan` | Falta acceso a spread o al mercado. |
| `422 reference_unavailable` | No hay BCV válido. |
| `422 compared_unavailable` | El mercado existe pero no tiene cotización positiva. |

Además pueden producirse los [errores comunes](/api/errors) de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por `code`, no por el texto de `message`.

<span id="notas" />

## Interpretación

Una brecha positiva no garantiza beneficio ni arbitraje: las referencias no incluyen comisiones, liquidez o condiciones de ejecución.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.