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
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. |
via | string | No | reference | Qué tasa usar: reference, parallel, binance, bybit, okx, bitget, mexc |
Ejemplos de request
Convertir 100 USD a VES con tasa de referencia (BCV, default):
Convertir 50 USD a VES con tasa paralela:
Convertir 200.000 VES a USD con Binance P2P:
Response
200 OK
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 | number | Valor de la tasa mid aplicada |
market | string | Market usado (el valor del parámetro via) |
type | string | Tipo de tasa (reference, parallel, p2p) |
updated_at | string (ISO 8601) | Cuándo se actualizó la tasa aplicada |
Casos de uso típicos
Usando la tasa BCV oficial
Para documentos importantes que requieren la tasa BCV oficial:
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:
Convertir de VES a USD
Si quieres saber cuántos USD son 1.000.000 VES según Binance P2P:
Comparar entre markets
Para mostrar al usuario cuánto recibiría con distintas tasas, haz múltiples llamadas:
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 | invalid_format | amount no es un número válido (field: amount) |
401 | invalid_api_key | API Key inválida, faltante o revocada |
429 | rate_limit_exceeded | Cuota mensual agotada |
500 | internal_error | Error inesperado del lado de Cotizave |
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):
Ejemplo: USD → VES con tasa paralela 638.87:
100 × 638.87 = 63887.00
Si from → to va en dirección inversa (ej: VES → USD):
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/ratesy 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ú.