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

# USD/EUR ↔ VES conversion

> Convert an amount using BCV or an explicitly selected compatible market.

`GET /v1/fx/convert` · All plans, subject to access to the selected market. **Omitting `via` selects BCV**, not the best market rate.

<span id="request" />

## Request

| Parameter | Rule |
| - | - |
| `from`, `to` | Required. USD ↔ VES or EUR ↔ VES; one side must be VES. |
| `amount` | Required; finite number greater than 0 and at most `1e12`. |
| `via` | Optional market. Defaults to `reference` for USD and `eur_reference` for EUR. |
| `market` | Alias for `via`. When both have a value, `via` wins. |
| `format` | [Response format](/en/api/formats). Defaults to JSON. |

The market base currency must match: `eur_reference` cannot convert USD. Markets with type `remittance` only support conversion to VES. Unknown parameters produce `400 unknown_parameter`.

Run these examples on your server. JavaScript and Python use the clients in the [quickstart](/en/api/quickstart#paso-2); configure `COTIZAVE_API_KEY` there.

<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" />

## Response

Illustrative response: figures and dates are not current quotes.

```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` and `to` contain `currency` and `amount`. `to.amount` is rounded to two decimal places. `rate` is the `mid` quote in VES per unit of the foreign currency. Conversion to VES multiplies; the reverse direction divides.

`market`, `type` and `updated_at` identify the applied quote. `effective_date` is present when the rate has a value date, such as BCV. `staleness_sec` is its age in seconds and `stale` indicates whether it exceeds its source threshold. Store this metadata with the result when you need traceability.

<span id="casos-uso" />

## Choose a currency and market

* BCV USD: `from=USD&to=VES&amount=100&via=reference`.
* BCV EUR: `from=EUR&to=VES&amount=100&via=eur_reference`.
* Reverse P2P: `from=VES&to=USD&amount=1000000&via=binance`.
* To compare markets, fetch [all rates](/en/api/endpoints/get-rates) once and filter by base currency before calculating.

<span id="errores" />

## Errors

`400 missing_field`, `invalid_format` or `unknown_parameter` indicates invalid input; check `field`. A missing market may return `404 resource_not_found`; a plan-restricted market returns `402 feature_not_in_plan`. Do not silently switch markets.

The [common errors](/en/api/errors) for authentication, quota and availability also apply. API error responses are JSON; branch on `code`, not on the text of `message`.

<span id="notas" />

## Freshness and precision

A BCV rate several days old over a weekend may still apply. Conversely, `stale: false` alone does not establish the rate required for an invoice. Keep `effective_date` and apply your business validation and rounding policy. The API uses `mid`; it excludes fees and does not guarantee execution.


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