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&via=reference HTTP/1.1
Host: api.cotizave.com
X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=100&via=reference" \
  -H "X-API-Key: $COTIZAVE_API_KEY"

const params = new URLSearchParams({ from: 'USD', to: 'VES', amount: '100', via: 'reference' })
const res = await fetch(`https://api.cotizave.com/v1/fx/convert?${params}`, {
  headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY }
})
const data = await res.json()
// data.to.amount → monto en VES

import os, requests

r = requests.get(
    'https://api.cotizave.com/v1/fx/convert',
    params={'from': 'USD', 'to': 'VES', 'amount': 100, 'via': 'reference'},
    headers={'X-API-Key': os.environ['COTIZAVE_API_KEY']}
)
data = r.json()
# data['to']['amount'] → monto en VES

Query parameters

Ejemplos de request

Convertir 100 USD a VES con tasa de referencia (BCV, default):

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

Convertir 50 USD a VES con tasa paralela:

curl "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=50&via=parallel" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

Convertir 200.000 VES a USD con Binance P2P:

curl "https://api.cotizave.com/v1/fx/convert?from=VES&to=USD&amount=200000&via=binance" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

Response

200 OK

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

Schema de respuesta

Casos de uso típicos

Usando la tasa BCV oficial

Para documentos importantes que requieren la tasa BCV oficial:

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

Esto te devuelve la conversión con la tasa BCV del día, confiable y oficial.

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&via=parallel" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

Convertir de VES a USD

Si quieres saber cuántos USD son 1.000.000 VES según Binance P2P:

curl "https://api.cotizave.com/v1/fx/convert?from=VES&to=USD&amount=1000000&via=binance" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

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&via=${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

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 (ej: USD → VES):

to.amount = from.amount × rate

Ejemplo: USD → VES con tasa paralela 638.87:

• 100 × 638.87 = 63887.00

Si from → to va en dirección inversa (ej: VES → USD):

to.amount = from.amount / rate

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:

1. Usar convert: es más simple, te garantiza el cálculo correcto, incluye validaciones, y te devuelve exactamente qué tasa se aplicó.
2. 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ú.