ronfix

ronfix

来自源头的罗马尼亚列伊参考汇率。 ronfix 是国家银行 of Romania（BNR）的轻量级免密客户端。BNR 将每日参考 定盘价发布为静态 XML 文件。对于自 2005 年以来的任意日期，它都能回答 这些文件支持的问题：某日适用的汇率是多少、某笔金额按该汇率兑换为 RON 或从 RON 兑换后是多少、某种货币在某段时间内的定盘价走势如何， 以及 ANAF 计算的某年平均值是多少。

所有数字都使用精确小数处理。汇率保留为 BNR 发布的文本（4.2440，绝不 是 4.244），金额以其原始字符串形式参与运算，每个结果只舍入 一次，并严格遵循你指定的规则。任何数值都不会经过浮点数处理。

工具

• health — BNR 是否有响应：返回最新定盘价的日期及该定盘价 包含的货币数量；如果定盘价已超过五天，则会发出警告。
• rate — 某日适用的汇率（默认 为今天）。周末、节假日，或布加勒斯特时间约 13:00 定盘价发布之前的今天，都会采用 此前最近的定盘价，包括 1 月初采用 12 月的最后一个定盘价。 响应会原样返回 BNR 发布的汇率、multiplier 和作为 published_on 的日期；如果在今日定盘价发布前查询今日汇率，也会附带 说明这一情况的 note。
• convert — 按某日适用的汇率，将金额（十进制字符串）兑换为 RON 或从 RON 兑换。只需指定 currency（金额以该货币计，结果以 RON 计），或通过 from/to 明确指定货币对。places（0 到 8，默认值为 2）和 rounding（默认 half-up，或 half-even）控制唯一一次舍入；rate_rule 用于选择 in_force（默认值）或 last_before（严格早于指定日期的最后一个 定盘价）。响应会返回汇率、倍数及日期，并提供一行 meaning，例如： “100 EUR = 509.10 RON，采用 BNR 的 EUR 汇率 5.0910 RON / 1 EUR，发布于 2026-10-16（于 2026-10-16 生效），按 half-up 舍入至 2 位小数”。计算示例：10000 HUF 按每 100 单位 1.2354 的汇率兑换为 123.54 RON。
• rates — 每种货币一组序列（通过 currencies 最多指定 50 种 货币，也可返回 BNR 发布的所有货币），每组包含倍数和按时间 从早到晚排列的定盘价。指定 date（或不指定日期， 即查询今天）时，序列包含该日适用的单个汇率，并按定盘日期标记；指定 from 和 to（默认今天）时，序列包含时间范围内的所有定盘价，包含起止日期。BNR 发布过但未出现在时间范围内的货币会列在 absent 中；如果时间范围内完全没有定盘价，则不会返回任何序列，并会附带说明的注释。
• annual_average — 按 ANAF 的算法计算某年的平均值：取 BNR 十二个月平均值的 均值（每个月平均值为当月每日汇率的均值），每个均值只舍入一次，按 half up 舍入 至四位小数，并返回每月平均值及其天数。尚未结束的年份会返回截至目前的月份，并设置 complete: false。参考值：USD 在 2022 年的平均值为 4.6885，2023 年为 4.5743；EUR 在 2022 年的平均值为 4.9315。

值得了解的行为

• 汇率表示每单位 RON，或每 100 单位（multiplier）；HUF、JPY、KRW 和其他少数货币采用后一种方式； 换算时会据此相应地进行除法或乘法。
• 上游数据来自 BNR 的公开 XML，位于 curs.bnr.ro： 最新定盘价使用 /nbrfxrates.xml， 全年数据使用 /files/xml/years/nbrfxrates<year>.xml。遇到 5xx、 429 或连接中断时，每个请求最多重试三次。过去年份的文件每个进程只获取一次； 当年文件和最新定盘价会缓存十分钟。日期始终使用布加勒斯特日期， 不受主机时区影响。
• 限制：仅支持 BNR 参考汇率，且数据始于 2005 年；不支持交叉汇率（换算的一方必须是 RON）； 时间范围最多 366 天、最多 2,000 个汇率。

错误

失败消息开头会标明以下四种类别之一：

• input — 无法按要求回答问题，且未获取任何内容：日期晚于今天或早于 2005 年、时间范围超过 366 天或 2,000 条汇率，或兑换时没有 RON 一侧。消息会说明具体原因。
• not_found — BNR 不发布该货币的汇率（“BNR 此处不发布……汇率；它发布的是……”，并列出实际发布的货币），或尚无该年份的汇率文件。
• api — 即使重试，BNR 的服务器仍未响应。
• drift — BNR 返回的内容不是汇率 XML（旧的 www.bnr.ro 地址会返回状态码为 200 的 HTML），或汇率不是纯十进制数，或年度平均汇率中一个月内出现乘数变化。年度平均汇率中跨月出现乘数变化时，则会返回 warning。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

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

输出是工具结果的 JSON。退出代码： 0 表示成功，1 表示运行时错误，2 表示用法错误。

MCP 服务

npx -y @reneturcios/ronfix mcp

MCP 客户端配置：

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

无需密钥或账户；该服务仅读取 BNR 的公开文件。

Docker

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

开发

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

许可证

MIT — 版权所有 (c) 2026 Rene Turcios