io.github.CloudCorpRecords/ronfix

ronfix

Romanian leu reference rates, straight from the source. ronfix is a small keyless client for the National Bank of Romania (BNR), which publishes its daily reference fixings as static XML files. It answers the questions those files support, for any day since 2005: what rate was in force on a given day, what an amount converts to or from RON at that rate, how a currency's fixings ran over a window, and what a year's average comes to the way ANAF computes it.

Every number is handled in exact decimals. A rate is kept as the text BNR published (4.2440, never 4.244), amounts reach the arithmetic as the strings they were written as, and each result is rounded exactly once, by the rule you name. Nothing is ever passed through a float.

Tools

• health — whether BNR answers: the date of its latest fixing and how many currencies that fixing carries, with a warning when the fixing is more than five days old.
• rate — the rate in force on a day (default today). A weekend, a holiday, or today before the ~13:00 Bucharest fixing takes the last fixing before it, including December's last fixing in early January. The answer carries the rate exactly as BNR wrote it, its multiplier, and its date as published_on; today's rate asked before the fixing also carries a note saying so.
• convert — an amount (a decimal string) to or from RON at the rate in force on a day. Name the pair with currency alone (amount in that currency, result in RON) or explicitly with from/to. places (0 to 8, default 2) and rounding (half-up by default, or half-even) control the single rounding; rate_rule picks in_force (default) or last_before (the last fixing strictly before the day). The answer carries the rate, its multiplier and date, and a meaning line, for example: "100 EUR = 509.10 RON at BNR's EUR rate 5.0910 RON for 1 EUR, published on 2026-10-16 (in force on 2026-10-16), rounded half-up to 2 places". Worked check: 10000 HUF at 1.2354 per 100 is 123.54 RON.
• rates — one series per currency (up to 50 named via currencies, or every currency BNR published), each with its multiplier and its fixings, oldest first. With date (or nothing, for today) a series holds the single rate in force that day, dated by its fixing; with from and to (default today) it holds every fixing in the window, both ends included. A currency BNR published but not in the window is listed in absent; a window with no fixings at all answers no series and a note saying so.
• annual_average — a year's average as ANAF uses it: the mean of BNR's twelve monthly averages (each the mean of that month's daily rates), each mean rounded once, half up, to four places, with the monthly averages and their day counts. A year not over yet answers the months so far with complete: false. Reference points: USD averaged 4.6885 in 2022 and 4.5743 in 2023; EUR averaged 4.9315 in 2022.

Behaviour worth knowing

• Rates are RON per unit, or per 100 units (the multiplier) for HUF, JPY, KRW and a few others; conversions divide or multiply by it accordingly.
• Upstream is BNR's public XML at curs.bnr.ro: /nbrfxrates.xml for the latest fixing and /files/xml/years/nbrfxrates<year>.xml for a whole year. A request is tried up to three times on a 5xx, a 429 or a dropped connection. A past year's file is fetched once per process; the current year's file and the latest fixing are kept ten minutes. Dates are Bucharest dates whatever the host's timezone.
• Limits: BNR reference rates only, from 2005; no cross rates (one side of a conversion is RON); windows at most 366 days and 2,000 rates.

Errors

Failures carry one of four classes at the start of the message:

• input — the question cannot be answered as asked and nothing was fetched: a date after today or before 2005, a window over 366 days or 2,000 rates, or a conversion with no RON side. The message names which.
• not_found — BNR does not publish that currency ("BNR publishes no ... rate here; it publishes ...", listing the ones it does), or has no rates file for that year yet.
• api — BNR's server did not answer, even after retries.
• drift — BNR answered with something that is not its rates XML (the old www.bnr.ro addresses answer HTML with status 200), or a rate that is not a plain decimal, or a multiplier change inside one month of an annual average. A multiplier change between months of an annual average answers with a warning instead.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/ronfix health '{}'
npx @reneturcios/ronfix rate '{"currency":"EUR","date":"2026-10-16"}'
npx @reneturcios/ronfix convert '{"amount":"10000","currency":"HUF"}'
npx @reneturcios/ronfix rates '{"currencies":["EUR","USD"],"from":"2026-10-01","to":"2026-10-16"}'
npx @reneturcios/ronfix annual_average '{"currency":"USD","year":2022}'
npx @reneturcios/ronfix --version

Output is the tool's result as JSON. Exit codes: 0 on success, 1 on a runtime error, 2 on a usage error.

MCP server

npx -y @reneturcios/ronfix mcp

MCP client config:

{
  "mcpServers": {
    "ronfix": {
      "command": "npx",
      "args": ["-y", "@reneturcios/ronfix", "mcp"]
    }
  }
}

No key or account is needed; the server reads BNR's public files only.

Docker

docker run -i ghcr.io/cloudcorprecords/ronfix
docker run --rm ghcr.io/cloudcorprecords/ronfix rate '{"currency":"EUR"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios