> ## 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.

# Market spread

> Compare BCV USD/VES with another market using the same base currency.

`GET /v1/fx/spread` · **Esencial or higher**. Compares BCV with another market; it is not an exchange’s bid/ask spread.

<span id="request" />

## Request

`against` is optional and defaults to `parallel`. `base` only accepts `USD` (the default). Do not compare against `reference` or `eur_reference`. Supports `format` and only the documented parameters.

Run these examples on your server. JavaScript and Python use the clients in the [quickstart](/en/api/quickstart#paso-2); configure `COTIZAVE_API_KEY` there.

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

## Response

Illustrative response: figures and dates are not current quotes.

```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`, rounded to 4 decimal places. `percentage = absolute / reference.value × 100`, calculated before rounding and returned with 2 decimal places. `direction` is `higher`, `lower` or `equal`; `absolute` can be negative.

<span id="casos-uso" />

## Indicators and alerts

Display the spread with both `updated_at` values; sources have different update frequencies. To compare several markets in a UI, you can use one snapshot and apply the same formula to USD quotes.

<span id="errores" />

## Errors

| Status / code | Cause |
| - | - |
| `400 invalid_base` | Base other than USD. |
| `400 invalid_against` | Self-comparison, unknown market or incompatible base. |
| `400 unknown_parameter` | Unsupported parameter. |
| `402 feature_not_in_plan` | Missing access to spread or the market. |
| `422 reference_unavailable` | No valid BCV rate. |
| `422 compared_unavailable` | Market exists but has no positive quote. |

The [common errors](/en/api/errors) for authentication, quota and availability also apply. API error responses are JSON; branch on `code`, not on the text of `message`.

<span id="notas" />

## Interpretation

A positive spread does not guarantee profit or arbitrage: reference quotes exclude fees, liquidity and execution conditions.


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