FX methodology

Rate meaning, freshness, history, conversion, sources, and limits.

Narwhal publishes current indicative rates, decimal-safe conversion, and historical observations through matching REST and MCP contracts. It keeps rate direction and time semantics explicit instead of presenting a number without context.

History contains genuine observation dates

Historical results are oldest-first and contain only dates with stored observations. Narwhal does not create weekend or holiday rows and does not forward-fill a weekly currency across otherwise daily history.

A date may contain only a subset of the requested currencies. This is expected when their publication cadence or historical coverage differs. The Interface returns the current accepted historical series, not every earlier publication vintage.

One base unit equals the quoted rate

For a base of USD and a returned EUR rate of 0.92, one US dollar equals 0.92 euros. Rates are decimal strings, and selected currencies are returned as explicit records rather than dynamic object keys.

Updates and freshness stay visible

Narwhal checks for new upstream observations about once per minute on trading days. A customer request reads the latest accepted observation; it does not wait for an upstream call.

Each rate has its own timestamp and stale state. market_session reports open, weekend, or interbank_closed. On weekends and market closures, the latest accepted observation can remain available with its original timestamp and honest session context.

Conversion uses one selected rate

The conversion endpoint uses decimal arithmetic, then rounds once to the target currency's ISO 4217 minor unit using half-even rounding. It returns the input amount, selected rate, converted amount, timestamp, stale state, and market session.

Licensed and approved data providers

Narwhal uses licensed or otherwise approved upstream providers and keeps provider identity, routing, licensing records, and derivation details in its internal audit trail. Those operational provenance fields are deliberately not included in the public rate response.

This policy keeps the customer contract stable if an approved upstream route changes, while Narwhal retains the evidence needed to audit each accepted observation.

Current limitations

Rates and conversions are indicative, not executable dealer quotes, settlement values, or official fixings.
Current rates, conversion, and historical observations are public. Volatility calculations are not.
A missing, malformed, or unavailable selected rate fails closed instead of being estimated or silently omitted.
Basic and Pro include a 99.5% uptime SLA; see the terms. Narwhal data is not financial, investment, legal, or tax advice.

See the live FX API or make a request from the quickstart.