Developer reference
Exchange-rate evidence
Distinguish reference quotes, provider refresh and actual exchanged account amounts.
Reference quotes help explain multi-currency answers. They are not the same as the amounts your bank actually exchanged.
Registered quote operations
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/v2/fx-quote | read:finance |
| POST | /api/v1/v2/fx-refresh | write:finance |
Quote availability depends on supported pairs, provider availability and stored freshness. Use the actual validated endpoint fields; a refresh command does not guarantee every pair is available.
Read a quote with its basis
A displayed conversion needs the base currency, quote currency, rate and observation time. Stale or unsupported evidence must remain explicit. Do not silently use a one-to-one fallback.
For a fictional example, a dated EGP/USD reference quote can help read an EGP balance in USD, but it does not prove the bank exchanged those funds at that rate.
Record an actual exchange
A conversion command uses both actual outgoing and received amounts against their accounts. It creates balanced entries for both currencies and requires an idempotency key. A later market quote must not replace the actual exchange facts.
Keep original foreign purchase evidence distinct from settled account money as well. See money and currencies, exchange semantics and idempotency.