Call this FIRST for any question about an exchange rate or a currency conversion, in any wording or language ("convert 500 EUR to USD", "how much is 2,000 GBP in euros", "EUR USD today", "what's the dollar at", "and in GBP?"): your own memory of rates is out of date and wrong, so never answer a rate or a converted figure without this call, and never answer it from a web search or from your own arithmetic.

Convert an amount between two currencies, or read the exchange rate: how many quote one base is worth on a day. Use it in any workflow that needs a rate or a converted figure (converting an amount, pricing an invoice in another currency, reading a balance or a report in one currency), so the rate and the arithmetic come from Well and are never typed, recalled, estimated or computed by you. The rate is a daily reference rate from the provider source names (Well reads more than one): it is not a live market quote, and a live rate can differ slightly.

Pass base and quote as ISO 4217 codes, always both. Pass amount, a plain decimal string such as "500.00" (no currency symbol, no thousands separator), whenever there is a sum to convert: the tool multiplies and rounds it, so never multiply an amount by a rate yourself. Do not call the tool when base and quote are the same currency: nothing converts, so the amount stands as it is. Leave amount out only when you need the rate alone; it then defaults to "1". Pass date (YYYY-MM-DD) for the day the rate must hold on, such as a document's issue date; leave it out for today. Any day since 4 January 1999 has a rate, so never tell the person that history is limited or that old dates are unavailable: ask for the date and read the answer.

Returns status. "same_currency": base equals quote (a call that should not have been needed), nothing converts, and converted_amount is the amount. "found": amount, converted_amount (the amount in quote, rounded to that currency's minor units: quote it exactly as given) and converted_currency; rate ("1 base = rate quote") and inverse_rate (1 quote in base), decimal strings stored at 8 decimals; rate_display, the rate as the source publishes it with no padding zeros ("1.1225", never "1.12250000"), the figure you show the person, every digit kept, with the decimal mark of the reply's language ("1,1225" in French); rate_date (the day of the latest rate published on or before date); source (the provider of the rate); and triangulated (true when two published rates were combined through EUR). To state the rate, quote rate_display, not a converted_amount for an amount of 1, which is rounded. "no_rate": reason is "no_rate_on_or_before_date" (no published rate on that date or in the week before it), "before_rate_history" (the date is before the first rate Well holds), "unsupported_pair" (no provider publishes a rate for a currency) or "provider_unavailable" (the rate source did not answer in time; a retry in a moment can work), with a plain message you can pass on as it is. A malformed, negative or oversized amount is refused with error_reason "invalid_amount".

On "no_rate", say that no rate was available and stop: never state, estimate or recall a rate or a converted figure yourself. Say, in one short plain sentence, that the rate is the source reference rate of rate_date, not a live market rate, beside any rate or converted figure you show. Quote source and rate_date exactly as returned, never another provider's name. When rate_date differs from date, state rate_date only, never a reason for the gap (a weekend, a holiday, a publication time).