GET /v1/fx/convert

Convierte un monto entre monedas usando la tasa que elijas. Si no especificas una tasa, Cotizave usa la “mejor disponible” para tu caso.

Request

GET /v1/fx/convert?from=USD&to=VES&amount=100 HTTP/1.1
Host: api.cotizave.com
X-API-Key: nd-tu-api-key-aqui

Query parameters

Parámetro	Tipo	Requerido	Default	Descripción
`from`	string	Sí	—	Moneda origen: `USD`, `EUR`, `VES`
`to`	string	Sí	—	Moneda destino: `USD`, `EUR`, `VES`
`amount`	number	Sí	—	Monto a convertir. Debe ser mayor a 0.
`market`	string	No	`parallel`	Qué tasa usar: `reference`, `parallel`, `binance`, `bybit`, `okx`, etc.
`side`	string	No	`mid`	Lado de la tasa: `ask`, `bid`, `mid`

Ejemplos de request

Convertir 100 USD a VES con tasa paralela (default):

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=100" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Convertir 50 USD a VES con tasa BCV (para facturación electrónica):

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=50&market=reference" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Convertir 200.000 VES a USD con Binance P2P usando el precio ask:

curl "https://api.cotizave.com/v1/fx/convert?from=VES&to=USD&amount=200000&market=binance&side=ask" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Convertir 100 EUR a VES:

curl "https://api.cotizave.com/v1/fx/convert?from=EUR&to=VES&amount=100" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Response

200 OK

{
  "from": {
    "currency": "USD",
    "amount": 100
  },
  "to": {
    "currency": "VES",
    "amount": 63887.00
  },
  "rate": {
    "market": "parallel",
    "type": "parallel",
    "side": "mid",
    "value": 638.87,
    "updated_at": "2026-04-08T17:25:00Z"
  },
  "fetched_at": "2026-04-08T17:29:15Z"
}

Schema de respuesta

Campo	Tipo	Descripción
`from.currency`	string	Moneda origen
`from.amount`	number	Monto de entrada
`to.currency`	string	Moneda destino
`to.amount`	number	Monto convertido
`rate.market`	string	Market usado
`rate.type`	string	Tipo de tasa (`reference`, `parallel`, `p2p`)
`rate.side`	string	Lado de la tasa aplicado (`ask`, `bid`, `mid`)
`rate.value`	number	Valor exacto de la tasa aplicada
`rate.updated_at`	string (ISO 8601)	Cuándo se actualizó esta tasa
`fetched_at`	string (ISO 8601)	Cuándo se procesó esta conversión

Casos de uso típicos

Facturación electrónica (SENIAT)

Para facturar en Venezuela usando la tasa oficial del BCV:

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=250&market=reference" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Esto te devuelve la conversión con la tasa BCV del día, que es la que el SENIAT reconoce para facturación electrónica.

Remesas

Para mostrar al usuario cuánto recibiría en bolívares:

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=500&market=parallel" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Cálculo de “cuánto necesito vender”

Si quieres obtener 1.000.000 VES y necesitas saber cuántos USDT vender en Binance al precio bid:

curl "https://api.cotizave.com/v1/fx/convert?from=VES&to=USD&amount=1000000&market=binance&side=bid" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Comparar entre markets

Para mostrar al usuario cuánto recibiría con distintas tasas, haz múltiples llamadas:

const markets = ['reference', 'parallel', 'binance', 'bybit']
const results = await Promise.all(
  markets.map(m =>
    fetch(`https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=100&market=${m}`, {
      headers: { 'X-API-Key': key }
    }).then(r => r.json())
  )
)

O más eficiente: trae todas las tasas con /v1/fx/rates y haz el cálculo del lado del cliente.

Errores posibles

Código	`error.code`	Causa
`400`	`missing_parameter`	Falta `from`, `to` o `amount`
`400`	`invalid_currency`	`from` o `to` no es una moneda soportada
`400`	`same_currency`	`from` y `to` son iguales
`400`	`invalid_amount`	`amount` no es un número válido o es ≤ 0
`400`	`invalid_market`	El `market` especificado no existe
`400`	`invalid_side`	`side` no es `ask`, `bid` ni `mid`
`401`	`unauthorized`	API Key inválida
`422`	`side_not_available`	Pediste `ask` o `bid` en una tasa `reference` (que solo tiene `mid`)
`429`	`rate_limit_exceeded`	Cuota mensual agotada
`502`	`upstream_error`	El market solicitado está temporalmente caído

Ejemplo de error: `side_not_available`

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=100&market=reference&side=ask" \
  -H "X-API-Key: nd-tu-api-key-aqui"

{
  "code": "side_not_available",
  "message": "Market 'reference' only provides 'mid' side. 'ask' and 'bid' are not available for this market type."
}

Por qué: la tasa reference (BCV) es una tasa oficial única, no tiene spread de compra/venta como las tasas de mercado.

Notas importantes

Precisión decimal

Los cálculos internos usan aritmética de punto flotante de doble precisión. Para operaciones críticas:

El resultado puede tener más decimales de los que esperas
Redondea antes de mostrar al usuario (típicamente 2 decimales para VES)
Si haces operaciones contables, considera redondeo bancario (half-to-even)

¿Cómo se calcula `to.amount`?

Si from → to va en la misma dirección que el market:

to.amount = from.amount × rate.value

Ejemplo: USD → VES con tasa paralela 638.87:

100 × 638.87 = 63887.00

Si from → to va en dirección inversa al market:

to.amount = from.amount / rate.value

Ejemplo: VES → USD con tasa Binance 637.87:

1000000 / 637.87 = 1567.60

Ventaja de usar el endpoint `convert` vs hacer el cálculo tú mismo

Ambas opciones funcionan:

Usar convert: es más simple, te garantiza el cálculo correcto, incluye validaciones, y te devuelve exactamente qué tasa se aplicó.
Usar /v1/fx/rates y calcular del lado tuyo: es más eficiente si haces muchas conversiones, porque una sola llamada te trae todas las tasas.

Regla práctica: si haces <10 conversiones por minuto, usa convert. Si haces más, trae las tasas con /v1/fx/rates y calcula tú.