tcmb-rates

Fetch and parse official exchange rates from the Central Bank of the Republic of Türkiye (TCMB). Zero dependencies, ESM, and runs anywhere fetch exists — Node 18+, Cloudflare Workers, Deno, Bun, and modern browsers.

• ✅ All currencies in the daily bulletin (USD, EUR, GBP, JPY, …), not just USD
• ✅ Forex & banknote buying/selling + cross rates
• ✅ Historical rates with automatic fallback to the previous business day (TCMB publishes nothing on weekends/holidays)
• ✅ Pure parser (parseTcmbXml) you can use offline, plus fetch helpers
• ✅ Injectable fetch for testing and custom runtimes

Why this package?

Several TCMB clients already exist on npm. This one is different in two ways that matter for modern deployments:

• Zero dependencies. Every other TCMB package pulls in a runtime dependency — axios, request, xml2js, fast-xml-parser, moment, and friends. This package ships none: the parser is a small pure function and fetching uses the platform fetch.
• Runs anywhere fetch exists. The others are CommonJS and Node-only; many rely on Node's http/request, so they don't run on edge runtimes at all. This package is ESM and works on Cloudflare Workers, Deno, Bun, browsers, and Node 18+ — the same code everywhere.

On top of that it covers the whole bulletin (all currencies, forex + banknote + cross rates), not just USD, and does historical lookups that walk back to the previous business day so weekends and holidays just work.

If you only need one USD value in a Node script, any of the alternatives is fine. If you want a dependency-free client that runs on the edge, use this one.

Install

npm install @muhalifsy/tcmb-rates

Usage

import { getLatestRates, getRatesForDate, getRate } from "@muhalifsy/tcmb-rates";

// Latest published bulletin
const rates = await getLatestRates();
console.log(rates.date);                       // "2026-07-08"
console.log(rates.currencies.USD.forexBuying);  // 46.7694
console.log(rates.currencies.EUR.forexSelling); // 53.5x

// One value, quickly
const usd = await getRate("USD");                       // forexBuying by default
const eurSell = await getRate("EUR", { field: "forexSelling" });

// Historical (walks back to the previous business day if needed)
const past = await getRatesForDate("2026-01-01");
console.log(past.usedPreviousBusinessDay); // true (Jan 1 is a holiday)
console.log(past.date);                    // the actual bulletin date used

Offline parsing

If you already have the XML (cached, proxied, etc.), skip the network entirely:

import { parseTcmbXml } from "@muhalifsy/tcmb-rates";

const { date, currencies } = parseTcmbXml(xmlString);

API

getLatestRates(options?) → Promise<TcmbRates>

Fetches today.xml — the most recently published bulletin.

getRatesForDate(date, options?) → Promise<TcmbRates & { requestedDate, usedPreviousBusinessDay } | null>

Fetches the bulletin for an ISO "YYYY-MM-DD" date. Walks back up to options.maxLookback days (default 7) to the previous business day, since TCMB does not publish on weekends and holidays. Returns null if nothing is found in the window.

getRate(code, options?) → Promise<number | null>

Convenience for a single value. options.field defaults to "forexBuying"; options.date switches to historical lookup. Returns null if the currency or field is absent.

parseTcmbXml(xml) → TcmbRates

Pure function. Parses a TCMB bulletin XML string. Safe on empty/garbage input (returns { date: null, currencies: {} }).

toIsoDate(value) → string | null

Normalizes TCMB's date formats (DD.MM.YYYY, MM/DD/YYYY, ISO) to "YYYY-MM-DD".

Options

All fetching functions accept:

| Option | Type | Default | Description | |--------|------|---------|-------------| | fetch | typeof fetch | global fetch | Inject a custom fetch (tests, proxies, custom runtimes) | | maxLookback | number | 7 | (date lookup only) max business days to walk back |

Types

interface CurrencyRate {
  code: string;              // "USD"
  unit: number;              // units the rate applies to (1, 100, …)
  name: string;              // English name from the bulletin ("US DOLLAR")
  nameTr: string;            // Turkish name from the bulletin ("ABD DOLARI")
  forexBuying: number | null;
  forexSelling: number | null;
  banknoteBuying: number | null;
  banknoteSelling: number | null;
  crossRateUsd: number | null;
  crossRateOther: number | null;
}

interface TcmbRates {
  date: string | null;                        // "YYYY-MM-DD"
  currencies: Record<string, CurrencyRate>;   // keyed by ISO code
}

Notes

• Rates are quoted in TRY per unit of the currency. For currencies like JPY the bulletin sets unit: 100, so divide by unit for a per-1 rate.
• This package talks to https://www.tcmb.gov.tr/kurlar/…. It is an independent open-source project and is not affiliated with or endorsed by TCMB. Respect their service and cache responses where possible.

License

MIT © Suleyman (muhalifsy)