GET /v1/fx/convert · All plans, subject to access to the selected market. Omitting via selects BCV, not the best market rate.
Request
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; configure COTIZAVE_API_KEY there.
Response
Illustrative response: figures and dates are not current quotes.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.
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 once and filter by base currency before calculating.
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 for authentication, quota and availability also apply. API error responses are JSON; branch on code, not on the text of message.
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.