Market spread

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

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; configure COTIZAVE_API_KEY there.

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"

import { cotizave } from './cotizave.mjs';

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

from cotizave import cotizave

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

Response

Illustrative response: figures and dates are not current quotes.

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

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.

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 for authentication, quota and availability also apply. API error responses are JSON; branch on code, not on the text of message.

Interpretation

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

Documentation

Get started

API

Venezuela: endpoints

Indices

Guides

Request

Response

Indicators and alerts

Errors

Interpretation

​Request

​Response

​Indicators and alerts

​Errors

​Interpretation

Request

Response

Indicators and alerts

Errors

Interpretation