Bodu.Financial.ExchangeRates.Imf 0.7.2

Bodu.Financial.ExchangeRates.Imf

API stability - Experimental. The public API surface and behaviour are still evolving and may change or be removed without a major-version bump.

No published API. The IMF publishes the Representative Exchange Rates, but it does not document the tab-separated export of the monthly report that this provider downloads. The export can change or disappear without notice, and the provider would then stop working with no change on the Bodu side. Pair it with a Stable provider, such as the ECB, Bank of England, RBA or FRED providers.

A Bodu.Financial exchange-rate provider backed by the IMF (International Monetary Fund) Representative Exchange Rates - the daily rates each issuing central bank reports to the Fund, published as a monthly report.

It downloads the IMF's monthly tab-separated report (every reported currency across each business day of the month), parses it, and serves the results as Bodu.Financial.ExchangeRates.ExchangeRate values through the standard IDatedRateProvider and IRateProvider contracts - so it composes with Money.ConvertTo, the caching and aggregating providers, and the rest of the Bodu.Financial FX stack. The same interfaces and DI shape as every other provider, a different data source.

using Bodu.Financial.ExchangeRates;

// The provider builds and owns its HttpClient from the options; dispose it to release the client.
// The IMF report is keyless - no API key is required.
using var provider = new ImfRateProvider(new ImfRateProviderOptions());

// Warm the in-memory store for a range (recommended), then look rates up synchronously.
await provider.LoadRangeAsync(new DateOnly(2026, 4, 1), new DateOnly(2026, 4, 30));

RateLookupResult jpy = provider.GetRate("USD", "JPY", new DateOnly(2026, 4, 1));
// jpy.Rate.Rate is the number of Japanese yen per US dollar on that date.

RateLookupResult usd = provider.GetRate("JPY", "USD", new DateOnly(2026, 4, 1)); // inverted

// Discover what pairs the loaded data supports.
foreach (ImfSeriesInfo info in provider.GetAvailablePairs())
    Console.WriteLine($"{info.Pair.From}/{info.Pair.To}");

Behaviour and limitations

• USD-anchored. Every rate the report publishes quotes a currency against the US dollar, so only USD→X and X→USD lookups are serviceable; a cross-currency pair (for example GBP/EUR) is rejected with RateSeriesNotFoundException. The reverse (X→USD) direction is served by the inverse-lookup fallback.
• Bulk, month-based loading. One download covers every reported currency for every business day of a month, so a request for any date in a month loads the whole month at once. LoadRangeAsync, LoadMonthAsync, and PreloadAsync (current month) warm the store; a range spanning several months downloads each covering month, up to four at once, publishing each only after the months before it. An on-demand lookup loads every month its DefaultLookback window (seven days by default) reaches, so a date in the first days of a month also loads the month before it.
• Direction auto-normalized. The report quotes most currencies as units per US dollar, but marks a few (labelled (1), for example Euro(1), U.K. pound(1)) as US dollars per unit. Both are normalized on ingest, so the stored rate is always units of the quote currency per one US dollar.
• Keyless. The report requires no API key; there is no ApiKey option.
• Currency-name mapping. The report labels currencies by name (Japanese yen, Chinese yuan, …). CurrencyNames maps each label to its ISO 4217 code; a label absent from the map is resolved directly against the ISO catalogue, and one that resolves neither way is skipped. Extend CurrencyNames to add labels not seeded by default.
• Monthly cache. Downloaded reports are cached on disk (configurable). A report downloaded after its month closed is immutable and is served from cache indefinitely; a report downloaded while its month was still growing is refreshed on a TTL (RefreshInterval), even once the month has closed. In memory, likewise, a request that reaches a day the IMF had not yet published when its month was loaded downloads the month again once RefreshInterval has passed. For a durable, cross-provider cache, compose with AddCachedRateProvider<…> from the Bodu.Financial.ExchangeRates.Caching package.

Endpoint configuration

ImfRateProviderOptions carries working defaults and binds through Microsoft.Extensions.Options.

HTTP client and lifetime

The provider is IDisposable and offers two construction styles:

• new ImfRateProvider(options, ...) - the provider builds, owns, and disposes its own HttpClient, created via RateProviderHttpClientFactory.Create from the configured user agent and timeout. Dispose the provider (for example with using) to release the client.
• new ImfRateProvider(httpClient, options, ...) - you supply the client and own its lifetime; the provider never disposes a client it did not create. This is the form the DI registration uses, backed by IHttpClientFactory.

Dependency injection

The package ships its own AddImfExchangeRates registration in the Bodu.Financial.ExchangeRates namespace - there is no separate *.DependencyInjection package.

services
    .AddFinancialService(configuration)
    .AddImfExchangeRates(configuration);

Part of the Bodu utility library.