How currency conversion works

Write the units before calculating

Start with the amount you have, the currency you want and the direction of the rate. In this illustrative example, the source is EUR, the target is USD and the rate is 1.08765 USD per EUR. This is a made-up rate for demonstrating the calculation.

Source amount:       250.00 EUR
Rate:                1.08765 USD/EUR
Unrounded result:    271.91250 USD
Two-decimal result:  271.91 USD

If the rate points the other way, divide

If you have USD 250 and the only available quote is 1.25 USD per EUR, divide 250 by 1.25 to obtain EUR 200. Multiplying would answer the wrong question.

A quick reasonableness check catches many direction errors: at that illustrative rate, one euro costs more than one dollar, so the euro amount should be smaller than the dollar amount.

Request a conversion from Narwhal

The conversion endpoint takes from, to and a positive decimal amount. The currencies must differ. It returns the input amount, selected rate, converted amount, timestamp, stale state and market session. The actual response depends on the accepted observation at request time.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/convert?from=USD&to=JPY&amount=100.00" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Keep calculation and payment amounts separate

An indicative conversion is useful for comparison or display. The amount a payment service delivers can differ because it applies its own rate, fee and rounding rules. The ECB, for example, labels its reference rates informational and discourages using them for transactions.

Here is an illustrative fee calculation with the fee explicitly deducted in the source currency before conversion. A fee charged after conversion would need a different formula.

Source balance:             100.00 USD
Fee deducted before FX:        2.00 USD
Amount actually converted:    98.00 USD
Provider rate:                 0.90 EUR/USD
Recipient amount:             88.20 EUR

Round the result once

Narwhal’s conversion contract uses decimal arithmetic and half-even rounding to the target currency’s ISO 4217 minor unit. Rate precision and currency amount precision serve different purposes: do not first shorten the rate to the number of decimals used for money.

Preserve the returned rate and converted amount together. Recalculating from a rounded display rate can produce a visible discrepancy with the API result.

Validate the input and save the result context

Before presenting a conversion as current, check the returned timestamp and stale flag. A successful request does not mean the rate was observed at the moment you clicked.

• Send an unformatted decimal string, not a number with currency symbols or thousands separators.
• Confirm the source and target codes before calculation.
• Handle unsupported currencies and invalid amounts as errors; do not substitute a rate of one.
• Save the amount, selected rate, converted result and observation context when reproducibility matters.