通貨換算の仕組み

計算前に単位を書く

手元の金額、換算先の通貨、レートの方向から確認します。この例では、換算元はEUR、換算先はUSD、レートは1 EUR当たり1.08765 USDです。計算方法を示すための架空のレートです。

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

レートが逆方向なら割る

USD 250を持っていて、利用できる提示レートが1 EUR当たり1.25 USDだけの場合、250を1.25で割るとEUR 200になります。掛け算では求めたい換算結果になりません。

妥当性の簡単な確認で方向の誤りを多く見つけられます。この例示レートでは1ユーロは1ドルより高いため、ユーロの金額はドルの金額より小さくなるはずです。

Narwhal から換算をリクエストする

換算エンドポイントはfrom、to、正の小数の金額を受け取ります。換算元と換算先の通貨は異なる必要があります。入力金額、選択したレート、換算金額、タイムスタンプ、データが古いかどうかを示す状態、市場セッションを返します。実際のレスポンスは、リクエスト時点で受け入れ済みの観測値によって決まります。

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

計算額と支払額を分けて扱う

参考レートによる換算は、比較や表示に役立ちます。決済サービスが実際に支払う金額は、独自のレート、手数料、丸め規則を適用するため異なる場合があります。例えばECBは参考レートを情報提供用とし、取引への使用を推奨していません。

ここでは、換算前に元通貨から手数料を明示的に差し引く例示計算を示します。換算後に手数料を請求する場合は別の式が必要です。

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

結果は一度だけ丸める

Narwhalの換算仕様では、10進演算と偶数丸めを使い、換算先通貨のISO 4217最小単位に丸めます。レートの精度と金額の精度は目的が異なります。金額に使う小数桁数に合わせて、先にレートの桁数を減らさないでください。

返されたレートと換算金額を一緒に保持してください。丸めた表示レートから再計算すると、API結果との差が見えることがあります。

入力を検証し、結果の文脈を保存する

換算を現在の値として表示する前に、返されたタイムスタンプとstaleフラグを確認してください。リクエストが成功しても、クリックした瞬間に観測されたレートとは限りません。

• 通貨記号や桁区切りのある数値ではなく、書式化していない小数文字列を送信してください。
• 計算前に元通貨コードと対象通貨コードを確認してください。
• 未対応通貨や無効な金額はエラーとして扱い、レート1で代用しないでください。
• 再現性が必要な場合は、金額、選択レート、換算結果、観測コンテキストを保存してください。