kzt-rates

A TypeScript wrapper around the National Bank of Kazakhstan RSS currency rates feed (nationalbank.kz).

Installation

npm install kzt-rates

Requires Node.js 18 or later (the package uses the built-in fetch API).

Programmatic API

import { KztRatesClient } from "kzt-rates";

const client = new KztRatesClient();

// All current rates
const snapshot = await client.getAllRates();
console.log(snapshot.rates.USD);
// { code: "USD", fullName: "", rate: 478.5, quant: 1, trend: "UP", change: 1.2 }

// Rate for a specific date
const historical = await client.getRatesForDate(new Date(2026, 4, 15));

// Rates for a date range (sequential requests, aggregated result)
const range = await client.getRatesForRange(new Date(2026, 4, 1), new Date(2026, 4, 7));
console.log(range.snapshots.length, range.errors);

// Convert tenge to a currency
const inUsd = await client.convertFromTenge(10_000, "USD");
console.log(inUsd.amount);

// Convert a currency to tenge
const inTenge = await client.convertToTenge(100, "EUR");
console.log(inTenge.amount);

Client options

new KztRatesClient({
  baseUrl: "https://nationalbank.kz/rss", // default
  retries: 3, // default
  retryDelayMs: 250, // default, doubles on each retry
  timeoutMs: 10_000, // default
  ttlMs: 300_000, // default cache TTL, 5 minutes; 0 disables caching
});

Methods

| Method | Description | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | getAllRates() | Fetches and parses rates_all.xml, returning a RatesSnapshot. | | getRatesForDate(date) | Fetches the rate for a single date via get_rates.cfm. | | getRatesForRange(from, to) | Fetches each date in the range sequentially and aggregates results, collecting per-date errors instead of failing the whole call. | | convertFromTenge(amount, code, snapshot?) | Converts an amount in KZT to the given currency. Uses getAllRates() when no snapshot is passed. | | convertToTenge(amount, code, snapshot?) | Converts an amount in the given currency to KZT. | | clearCache() | Clears the in-memory cache. |

Standalone functions (parseAllRatesXml, parseRatesForDateXml, fetchAllRatesXml, fetchRatesForDateXml, convertFromTenge, convertToTenge, TtlCache) are also exported for lower-level use.

Errors

All errors extend KztRatesError:

• NetworkError - request failed after exhausting retries
• HttpStatusError - the server returned a non-2xx status
• ParseError - the XML response could not be parsed at all
• CurrencyNotFoundError - a conversion referenced an unknown currency code
• InvalidDateError - an invalid date range was passed to getRatesForRange

CLI

npx kzt-rates                          # show all current rates
npx kzt-rates USD                      # show the current rate for USD
npx kzt-rates EUR --date=15.05.2026    # show the rate for EUR on a date
npx kzt-rates convert 100 USD KZT      # convert 100 USD to KZT
npx kzt-rates convert 50000 KZT EUR    # convert 50000 KZT to EUR
npx kzt-rates --help

Data source

• All rates: https://nationalbank.kz/rss/rates_all.xml
• Rate for a date: https://nationalbank.kz/rss/get_rates.cfm?fdate=DD.MM.YYYY

Only HTTPS is used, since the National Bank of Kazakhstan has disabled plain HTTP access to these endpoints.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

License

Licensed under the Mozilla Public License 2.0.