OpenUrzednik.Nbp 1.0.0

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package OpenUrzednik.Nbp --version 1.0.0
                    
NuGet\Install-Package OpenUrzednik.Nbp -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenUrzednik.Nbp" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OpenUrzednik.Nbp" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="OpenUrzednik.Nbp" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OpenUrzednik.Nbp --version 1.0.0
                    
#r "nuget: OpenUrzednik.Nbp, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OpenUrzednik.Nbp@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OpenUrzednik.Nbp&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=OpenUrzednik.Nbp&version=1.0.0
                    
Install as a Cake Tool

OpenUrzednik.Nbp

🇵🇱 Wersja polska (skrócona)

⚠️ Unofficial: OpenUrzednik.NET is a community project. It is not affiliated with, authorized or endorsed by Narodowy Bank Polski (NBP) or any other Polish public institution.

NBP (Narodowy Bank Polski, the National Bank of Poland) client for OpenUrzednik.NET: exchange rates and gold prices from the NBP API.

Part of OpenUrzednik.NET. See the main README for an overview of the project.

Installation

dotnet add package OpenUrzednik.Nbp

Requires OpenUrzednik.Core (NuGet installs it as a dependency).

Usage

The simplest case: the default NBP API address and the HttpClient's timeout.

using var httpClient = new HttpClient();
var client = new NbpGoldPriceClient(httpClient);

var result = await client.GetLatestAsync();
if (result.IsSuccess)
    Console.WriteLine($"{result.Value.Date:yyyy-MM-dd}: {result.Value.Price} zł");
else
    Console.WriteLine(result.Errors[0].Message);

Pass your own address (e.g. a proxy or an API gateway) and timeout in NbpOptions. The client doesn't change the HttpClient, so you can share it with other code:

var client = new NbpCurrencyExchangeRateClient(httpClient, new NbpOptions
{
    ApiUrl = "https://proxy.example.com/nbp/",
    Timeout = TimeSpan.FromSeconds(5),
});

With a DI container, use OpenUrzednik.Nbp.DependencyInjection: builder.Services.AddOpenUrzednikNbp() registers all three clients, and .AddStandardResilienceHandler() adds retries.

The client takes the API address from the first place that sets one: NbpOptions.ApiUrl, HttpClient.BaseAddress, and finally the default https://api.nbp.pl/api/. If you don't set NbpOptions.Timeout, the HttpClient's timeout applies (100 s by default). NbpOptions.Timeout can shorten that limit but not extend it, because HttpClient.Timeout still applies until the response headers arrive. The API address must be an absolute https URL without a query (?…) or a fragment (#…): the constructor throws an ArgumentException for any other scheme, for NbpOptions.ApiUrl and for HttpClient.BaseAddress alike.

Errors such as missing data, an exceeded rate limit, a timeout or an invalid currency code come back in the result, not as exceptions. If you prefer exceptions, call EnsureSuccess() on the result. A null currency code or an undefined TableType is a programming error: the method throws ArgumentNullException or ArgumentOutOfRangeException right away, before it returns a task. A resilience handler's rejections (timeout, open circuit breaker, rate limiter) become errors only when the clients are registered with AddOpenUrzednikNbp(); with your own HttpClient setup they come out as Polly exceptions.

Methods

Each client has the same groups of methods; every method takes a CancellationToken last. TableType is A (common currencies, the default for rates) or B (less common currencies); table C (buy and sell rates) has its own GetBuySell… methods.

Group NbpCurrencyExchangeRateClient NbpExchangeRateTableClient NbpGoldPriceClient
Latest GetLatestAsync(currency, table), GetBuySellLatestAsync(currency) GetLatestAsync(table), GetBuySellLatestAsync() GetLatestAsync()
Today GetTodayAsync(currency, table), GetBuySellTodayAsync(currency) GetTodayAsync(table), GetBuySellTodayAsync() GetTodayAsync()
One date GetAsync(currency, date, table), GetBuySellAsync(currency, date) GetAsync(table, date), GetBuySellAsync(date) GetAsync(date)
Date range GetAsync(currency, from, to, table), GetBuySellAsync(currency, from, to) GetAsync(table, from, to), GetBuySellAsync(from, to) GetAsync(from, to)
Last N GetTopCountAsync(currency, topCount, table), GetBuySellTopCountAsync(currency, topCount) GetTopCountAsync(table, topCount), GetBuySellTopCountAsync(topCount) GetTopCountAsync(topCount)
Last before a date GetLastPublishedBeforeAsync(currency, date, table), GetBuySellLastPublishedBeforeAsync(currency, date) GetLastPublishedBeforeAsync(table, date), GetBuySellLastPublishedBeforeAsync(date) GetLastPublishedBeforeAsync(date)

The currency client returns one currency's rates (CurrencyExchangeRates, with a Rates list), the table client whole tables (ExchangeRateTable) and the gold client gold prices (GoldPrice). A range keeps the order NBP returns, which today is ascending by date. GetLastPublishedBeforeAsync returns a single item: one table, one gold price, or a CurrencyExchangeRates with exactly one rate.

Data availability and limits

Publication. Times are Europe/Warsaw time.

  • Table A: business days, between 11:45 and 12:15.
  • Table B: Wednesdays, between 11:45 and 12:15, or the previous business day when Wednesday is a holiday.
  • Table C (buy and sell): business days, between 7:45 and 8:15.
  • Gold prices: business days, at about 8:00. NBP doesn't document this hour. We observed it on the API.

Get…TodayAsync returns a NotFoundError until the day's publication, and on days without one. GetLatestAsync returns the most recent published value.

Limits. The client checks these before it sends a request; a violation comes back as a ValidationError.

What Limit
Earliest date 2002-01-02 for rates and tables, 2013-01-02 for gold
Latest date Today's date in Europe/Warsaw, not in the caller's time zone or UTC
Top count 1 to 255 for rates and gold; for tables, 1 to 67 for A and C, 1 to 14 for B
Date range to - from at most 367 days for rates and gold, 93 days for tables
Currency code 3 letters, upper or lower case

In a range method, from may be earlier than the earliest date: only to is checked against the earliest date and against today. from later than to is a validation error. In Get…LastPublishedBeforeAsync, the client checks the day before date the same way, so date must be later than the earliest date and not later than tomorrow. With tomorrow, the result is today's publication once it is out (see the publication times above), and the one before until then.

Empty answers. A date or range with no publication (a weekend, a holiday, a date before the table existed) is a NotFoundError: NBP answers it with an HTTP 404 (the error then carries the status code) or with an empty list. See Errors for the other error types. NBP describes its API in the official documentation.

Currency names before 2004-05-04. Tables A and C published before 2004-05-04 (up to 85/A/NBP/2004 and 85/C/NBP/2004) give the country, not the currency name, so CurrencyName is an empty string there; CurrencyCode and the rates are filled in as usual. Table B always has the name. In CurrencyExchangeRates and BuySellExchangeRates, NBP takes the name from the earliest rate in the answer: a range or a Get…LastPublishedBeforeAsync window whose earliest rate was published before 2004-05-04 has an empty name for all its rates, including the later ones.

The last rate before a date

Many Polish tax and accounting rules use the NBP rate from the last business day before a given day, for example the day of an invoice or a payment. GetLastPublishedBeforeAsync returns the last publication before date, never the one on date itself: for a Monday you usually get the previous Friday's rate, even after NBP has published Monday's.

var result = await client.GetLastPublishedBeforeAsync("USD", new DateTime(2026, 3, 16));
if (result.IsSuccess)
{
    var rate = result.Value.Rates[0];
    Console.WriteLine($"{rate.TableId}, {rate.PublicationDate:yyyy-MM-dd}: {rate.Price}");
}
else
{
    Console.WriteLine(result.Errors[0].Message);
}

The client sends one range request that ends the day before date and returns the item with the latest publication date. The range covers 14 days for tables A and C and for gold, and 28 days for table B, which NBP publishes once a week. No gap between NBP publications is that long, so a NotFoundError means NBP published nothing in the range, for example before the first table or gold price.

For table B, pass TableType.B. For buy and sell rates, call GetBuySellLastPublishedBeforeAsync(currency, date); the rate has Ask and Bid. The table and gold clients have the same methods. Only the date part of date counts, as in every other method.

HttpClient and thread safety

The clients don't own the HttpClient, never change it and aren't IDisposable. Create one HttpClient for the application, or take it from IHttpClientFactory (the DependencyInjection package does that), and share it. Don't create an HttpClient per request: it exhausts sockets.

The clients are thread-safe: create one client per HttpClient and share it across threads and concurrent calls.

Compatibility

Minor versions may add methods to the client interfaces, properties to the models and options to NbpOptions (ADR-0011). The clients and NbpOptions are sealed: to swap or wrap a client, use its interface (INbpGoldPriceClient and the others). If you implement an interface yourself, a new method breaks your build until you add it; a throw new NotImplementedException(); stub is enough for methods you don't call. An implementation compiled against an older version, e.g. in another package, has to be rebuilt. New model properties are init properties (set them in an object initializer or with with); the positional constructors and Deconstruct don't change.

The .NET builds (net8.0, net10.0) are trimming- and Native AOT-compatible: publishing an app with trimming or Native AOT gives no warning from this package. CI checks it on every change (ADR-0014). The netstandard2.0 build (.NET Framework) isn't covered.

API gateways

For most gateways in front of the NBP API, NbpOptions.ApiUrl is enough: the client appends the NBP paths (e.g. exchangerates/rates/a/USD) to it. If the gateway renames paths or needs a query parameter, rewrite the request in a DelegatingHandler. The paths the client builds aren't configurable in any other way.

sealed class NbpGatewayHandler : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var uri = new UriBuilder(request.RequestUri!);
        uri.Path = uri.Path.Replace("/exchangerates/", "/fx/");
        uri.Query = string.IsNullOrEmpty(uri.Query) ? "api-version=1" : uri.Query.TrimStart('?') + "&api-version=1";
        request.RequestUri = uri.Uri;
        return base.SendAsync(request, cancellationToken);
    }
}
using var httpClient = new HttpClient(new NbpGatewayHandler { InnerHandler = new HttpClientHandler() });
var client = new NbpCurrencyExchangeRateClient(httpClient, new NbpOptions { ApiUrl = "https://gateway.example.com/nbp/" });
// GetLatestAsync("USD") requests https://gateway.example.com/nbp/fx/rates/a/USD?api-version=1

With AddOpenUrzednikNbp(), add the handler with .AddHttpMessageHandler(() => new NbpGatewayHandler()). Spans still show the NBP path (url.path) and the configured host and port (server.address, server.port), because the client tags them before the handler runs; error messages show the rewritten address.

Dates and .NET Framework

Dates are DateTime on every target: methods take a DateTime and the models return one (e.g. GoldPrice.Date). Only the date counts: the client ignores the time of day and DateTime.Kind, and returned dates have the time 00:00 and DateTimeKind.Unspecified. On .NET 8 and later you can also pass a DateOnly (extension methods in OpenUrzednik.Nbp).

The package also runs on .NET Framework 4.7.2 or later (through netstandard2.0) with the same API, so a netstandard2.0 library that uses it works in .NET Framework and .NET apps alike.

Logging and tracing

The clients take optional logger and traceSource parameters. Without a logger they log nothing. Without a trace source, on .NET 8 and later they record spans on the OpenUrzednik.Nbp ActivitySource (NbpTelemetry.SourceName), which costs nothing while no one listens to it; on .NET Framework they record none. To use ILogger and OpenTelemetry, install the OpenUrzednik.Extensions.Logging and OpenUrzednik.Diagnostics adapters:

using OpenUrzednik.Diagnostics;
using OpenUrzednik.Extensions.Logging;
using OpenUrzednik.Nbp;

var client = new NbpGoldPriceClient(httpClient,
    logger: loggerFactory.CreateOpenUrzednikLogger<NbpGoldPriceClient>(),
    traceSource: ActivityTraceSource.GetShared(NbpTelemetry.SourceName));

On .NET 8 and later the traceSource line is optional; to turn spans off, pass NullOpenUrzednikTraceSource.Instance. Subscribe with AddSource("OpenUrzednik.*") or AddSource(NbpTelemetry.SourceName). Logs go to a category named after the client's full type name (e.g. OpenUrzednik.Nbp.NbpGoldPriceClient).

The clients use their own interfaces (IOpenUrzednikLogger, IOpenUrzednikTraceSource from OpenUrzednik.Core), not ILogger and ActivitySource. So this package needs neither Microsoft.Extensions.Logging.Abstractions nor any other logging or tracing package. Only the adapters connect it to ILogger and ActivitySource.

Telemetry reference

Within a major version, the names below don't change: the source, span names, tags, error.type values, logger categories and event ids. Minor versions may add spans, tags and events. Log message text and properties may change in any version, so filter logs by event id, not by text.

Spans

Each client method starts one span on the OpenUrzednik.Nbp source, with the HTTP request as its child nbp.http.get. All spans are of kind Internal.

Span Client and methods Tags
nbp.currency.latest, .today NbpCurrencyExchangeRateClient.GetLatestAsync, GetTodayAsync nbp.currency, nbp.table
nbp.currency.top_count GetTopCountAsync nbp.currency, nbp.table, nbp.top_count
nbp.currency.date GetAsync(currency, date) nbp.currency, nbp.table, nbp.date
nbp.currency.range GetAsync(currency, from, to) nbp.currency, nbp.table, nbp.from, nbp.to
nbp.currency.last_published_before GetLastPublishedBeforeAsync(currency, date) nbp.currency, nbp.table, nbp.date
nbp.currency.buy_sell_latest, .buy_sell_today GetBuySellLatestAsync, GetBuySellTodayAsync nbp.currency
nbp.currency.buy_sell_top_count GetBuySellTopCountAsync nbp.currency, nbp.top_count
nbp.currency.buy_sell_date GetBuySellAsync(currency, date) nbp.currency, nbp.date
nbp.currency.buy_sell_range GetBuySellAsync(currency, from, to) nbp.currency, nbp.from, nbp.to
nbp.currency.buy_sell_last_published_before GetBuySellLastPublishedBeforeAsync(currency, date) nbp.currency, nbp.date
nbp.table.latest, .today NbpExchangeRateTableClient.GetLatestAsync, GetTodayAsync nbp.table
nbp.table.top_count GetTopCountAsync nbp.table, nbp.top_count
nbp.table.date GetAsync(table, date) nbp.table, nbp.date
nbp.table.range GetAsync(table, from, to) nbp.table, nbp.from, nbp.to
nbp.table.last_published_before GetLastPublishedBeforeAsync(table, date) nbp.table, nbp.date
nbp.table.buy_sell_latest, .buy_sell_today GetBuySellLatestAsync, GetBuySellTodayAsync none
nbp.table.buy_sell_top_count GetBuySellTopCountAsync nbp.top_count
nbp.table.buy_sell_date GetBuySellAsync(date) nbp.date
nbp.table.buy_sell_range GetBuySellAsync(from, to) nbp.from, nbp.to
nbp.table.buy_sell_last_published_before GetBuySellLastPublishedBeforeAsync(date) nbp.date
nbp.gold.latest, .today NbpGoldPriceClient.GetLatestAsync, GetTodayAsync none
nbp.gold.top_count GetTopCountAsync nbp.top_count
nbp.gold.date GetAsync(date) nbp.date
nbp.gold.range GetAsync(from, to) nbp.from, nbp.to
nbp.gold.last_published_before GetLastPublishedBeforeAsync(date) nbp.date
nbp.http.get the request of any method http.request.method, server.address (e.g. api.nbp.pl, or the ApiUrl host), server.port (always set, e.g. 443), url.path (e.g. /api/cenyzlota), http.response.status_code

Tag values: nbp.currency is the code as passed (e.g. USD), nbp.table the table (A or B), nbp.top_count a number, and nbp.date, nbp.from and nbp.to dates as yyyy-MM-dd. In the last_published_before spans, nbp.date is the date passed to the method, not the end of the requested range. A failed span has the Error status and an error.type tag with the error code (see Errors).

Log events

Every entry has an event id; NbpLogEvents lists them as constants, and the event name is the constant's name (EventId(1001, "RequestTimedOut")). The ids are the same in every client. The {provider} property is nbp.

Id Name Level When
1001 RequestTimedOut Warning A request timed out (NbpOptions.Timeout, HttpClient.Timeout or a resilience handler's timeout).
1002 ConnectionFailed Warning The API couldn't be reached (DNS, TLS, connection) or the body read broke.
1003 RequestRejected Warning A resilience handler rejected the request (open circuit breaker, rate limiter).
1101 NotFound Debug The API returned 404.
1102 BadRequest Warning The API returned 400.
1103 Unauthorized Warning The API returned 401 or 403.
1104 RequestTimeoutStatus Warning The API returned 408.
1105 RateLimited Warning The API returned 429.
1106 ServiceUnavailable Warning The API returned a 5xx status.
1107 UnexpectedStatus Warning The API returned another non-success status.
1108 ErrorResponse Warning Reserved for providers that map error bodies themselves; NBP doesn't.
1109 ErrorBodyUnreadable Debug The body of an error response couldn't be read.
1201 EmptyResponse Error A success response had no payload.
1202 DeserializationFailed Error A success response wasn't the expected JSON.
1203 DecodingFailed Error A success response declared a charset that can't be decoded.
2001 ValidationFailed Debug The arguments failed validation; no request was sent.
2002 NoData Debug The API returned an empty array: no data for the date or range.
2003 MappingFailed Error A response lacked data the model needs.
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on OpenUrzednik.Nbp:

Package Downloads
OpenUrzednik.Nbp.DependencyInjection

Unofficial Microsoft.Extensions.DependencyInjection registration for the OpenUrzednik.NET NBP clients: typed HttpClients, validated options, logging and tracing; ready for AddStandardResilienceHandler() on .NET 8 and later.

GitHub repositories

This package is not used by any popular GitHub repositories.