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

# Conversión USD/EUR ↔ VES

> Convierte un monto usando BCV o un mercado compatible elegido explícitamente.

`GET /v1/fx/convert` · Todos los planes, sujeto al acceso al mercado elegido. **Sin `via` se usa BCV**, no la mejor tasa de mercado.

<span id="request" />

## Consulta

| Parámetro | Regla |
| - | - |
| `from`, `to` | Obligatorios. USD ↔ VES o EUR ↔ VES; un lado debe ser VES. |
| `amount` | Obligatorio; número finito mayor que 0 y como máximo `1e12`. |
| `via` | Mercado opcional. Por defecto `reference` para USD y `eur_reference` para EUR. |
| `market` | Alias de `via`. Si ambos tienen valor, gana `via`. |
| `format` | [Formato de respuesta](/api/formats). JSON por defecto. |

La moneda base del mercado debe coincidir: `eur_reference` no convierte USD. Los mercados `remittance` solo admiten la dirección hacia VES. Parámetros desconocidos producen `400 unknown_parameter`.

Los ejemplos se ejecutan en el servidor. JavaScript y Python usan los clientes del [inicio rápido](/api/quickstart#paso-2); configura allí `COTIZAVE_API_KEY`.

<CodeGroup>
  ```bash curl theme={null}
  curl --fail-with-body --max-time 10 "https://api.cotizave.com/v1/fx/convert?from=USD&to=VES&amount=100&via=parallel" \
    -H "X-API-Key: $COTIZAVE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { cotizave } from './cotizave.mjs';

  const data = await cotizave('/v1/fx/convert?from=USD&to=VES&amount=100&via=parallel');
  console.log(data);
  ```

  ```python Python theme={null}
  from cotizave import cotizave

  data = cotizave('/v1/fx/convert?from=USD&to=VES&amount=100&via=parallel')
  print(data)
  ```
</CodeGroup>

<span id="response" />

## Respuesta

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

```json theme={null}
{
  "from": {
    "currency": "USD",
    "amount": 100
  },
  "to": {
    "currency": "VES",
    "amount": 63887
  },
  "rate": 638.87,
  "market": "parallel",
  "type": "parallel",
  "updated_at": "2026-10-19T17:25:00Z",
  "staleness_sec": 255,
  "stale": false
}
```

`from` y `to` contienen `currency` y `amount`. `to.amount` se redondea a dos decimales. `rate` es la tasa `mid` en VES por unidad de la divisa. Para convertir hacia VES se multiplica; en sentido inverso se divide.

`market`, `type` y `updated_at` identifican la cotización aplicada. `effective_date` aparece cuando la tasa tiene fecha valor, como BCV. `staleness_sec` indica antigüedad en segundos y `stale` si supera el umbral de su fuente. Guarda estos datos con el resultado si necesitas trazabilidad.

<span id="casos-uso" />

## Elegir moneda y mercado

* BCV USD: `from=USD&to=VES&amount=100&via=reference`.
* BCV EUR: `from=EUR&to=VES&amount=100&via=eur_reference`.
* Inversa P2P: `from=VES&to=USD&amount=1000000&via=binance`.
* Para comparar varios mercados, obtén [todas las tasas](/api/endpoints/get-rates) una vez y filtra por moneda base antes de calcular.

<span id="errores" />

## Errores

`400 missing_field`, `invalid_format` o `unknown_parameter` señalan entradas inválidas; revisa `field`. Un mercado ausente puede devolver `404 resource_not_found`; uno restringido por plan, `402 feature_not_in_plan`. No cambies a otro mercado silenciosamente.

Además pueden producirse los [errores comunes](/api/errors) de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por `code`, no por el texto de `message`.

<span id="notas" />

## Frescura y precisión

Un BCV de varios días durante un fin de semana puede seguir vigente. `stale: false` tampoco acredita por sí solo la tasa requerida por una factura. Conserva `effective_date` y aplica la política de validación y redondeo de tu negocio. La API calcula importes con `mid`; no incluye comisiones ni garantiza ejecución.


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