apyhub
Back

Convert Currency Amount API

What it does

The Convert Currency Amount API converts an amount from one currency to another at daily reference rates. Send an amount, a from code and a to code, and get back the converted value, the rate used and the date of that rate.

Choose from and to from 12 major currencies: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, KRW and MXN. Codes must be uppercase. Set amount between 0.000001 and 1,000,000,000,000. The API rounds the result to 2 decimals, or to 6 decimals when it is below 0.01.

Every response carries ratesAsOf, the date of the rate set. The rates are published once per working day, so they are usually from the previous working day. The stale flag tells you if older backup rates were used, and every response includes a short notice that the rates are indicative.

Teams use this convert currency API to show prices in a shopper's currency, to convert expense and invoice totals for reports, and to add a simple currency converter to a dashboard or chatbot.

These are reference rates, not live trading prices, so don't use them for payments or settlement. Your input is not stored.

To add tax after converting, use the Calculate VAT and GST API or the US Sales Tax Calculator API. To convert into several currencies in one call, use the Multi-Currency Converter API.

POST
Convert an amount between 12 major currencies
https://api.eu.apyhub.com/freedailypro/convert-currency-amount/converters/major/currency

QUICKSTART

GUIDE

Quickstart

Convert 100 US dollars to euros at the latest daily reference rate.

curl -X POST "https://api.eu.apyhub.com/freedailypro/convert-currency-amount/converters/major/currency" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "from": "USD", "to": "EUR"}'

What you'll get back

Returns a JSON object with a result object holding the converted value, the rate, the rate date and notes on the rates.

{
  "result": {
    "amount": 100,
    "from": "USD",
    "to": "EUR",
    "converted": 91.17,
    "rate": 0.91174,
    "ratesAsOf": "2026-11-18",
    "rateSource": "Publicly available reference rates",
    "rateSourceId": "reference-daily",
    "sourceId": "reference-daily",
    "live": false,
    "stale": false,
    "disclaimer": "Indicative rates, not for real transactions",
    "note": "Daily reference rates, not live trading rates: they are published once on each working day, are not live market rates and are not the rate a bank or card will give you."
  }
}
TRY ITLIVE · 10 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
Currency to convert to, as an uppercase code.
Currency to convert from, as an uppercase code.
The amount to convert, from 0.000001 to 1e12.

About this endpoint

What it does

Converts an amount from one of 12 major currencies to another at the latest daily reference rate. Returns the converted value, the rate, the date of the rate and notes on how fresh it is.

Request Body

ParameterTypeDescription
amountNumberRequired. The amount to convert. Range: 0.000001 to 1000000000000 (1e12).
fromENUMRequired. Currency to convert from, as an uppercase code. Allowed values: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, KRW, MXN.
toENUMRequired. Currency to convert to. Same allowed values as from.

Only these three fields are accepted. Any other field, such as date, returns a 400 error.

Response

Returns a JSON object with a result object holding the conversion and details about the rate it used.

ParameterTypeDescription
result.amountNumberThe amount you sent.
result.fromStringThe currency you converted from.
result.toStringThe currency you converted to.
result.convertedNumberThe converted amount. Rounded to 2 decimals, or to 6 decimals when below 0.01.
result.rateNumberThe rate used: 1 unit of from in to. 1 when from and to are the same.
result.ratesAsOfStringDate of the rate set used, in YYYY-MM-DD format.
result.rateSourceStringWhere the rates come from, for example Publicly available reference rates.
result.rateSourceIdStringShort ID of the rate source. reference-daily for the daily feed, built-in-snapshot when backup rates are used.
result.sourceIdStringSame value as rateSourceId.
result.liveBooleanAlways false: the rates are daily reference rates, not live market rates.
result.staleBooleantrue when backup rates were used because the daily feed was unavailable.
result.fallbackBooleanOnly present when backup rates were used. Then true.
result.warningStringOnly present when backup rates were used. Says which rate date was used and why.
result.disclaimerStringUse notice: Indicative rates, not for real transactions.
result.noteStringExplains that the rates are published once per working day and differ from bank or card rates.

Notes

  • Rates are published once per working day, so ratesAsOf is usually the previous working day.
  • Error responses: 400 with code: amount_out_of_range when amount is outside the range; 400 with error: Invalid input and a details.fieldErrors object when a field is missing, has the wrong type or uses a code outside the list (lowercase codes fail too); 400 when an unknown field is sent.
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.