货币转换 API：REST 上的实时汇率

您的电子商务商店向 30 个国家/地区的客户销售产品。 您在买家页面显示价格 当地货币。 这意味着您需要实时汇率，并且需要免费 开发期间且生产成本低廉。

大多数外汇 API 从 2000 年代初开始按请求收费，需要 OAuth 流程或返回 XML。 botoi 货币 API 为您提供两个返回 JSON 的 POST 端点，支持 170 多种货币， 并在免费层匿名工作。 无需 API 密钥即可开始。

任意两种货币之间的转换

这 /v1/currency/convert 端点采用源货币、目标货币和 金额。 它返回转换后的结果和使用的汇率。

curl -X POST https://api.botoi.com/v1/currency/convert \\
  -H "Content-Type: application/json" \\
  -d '{"from": "USD", "to": "EUR", "amount": 99.99}'

回复：

{
  "success": true,
  "data": {
    "from": "USD",
    "to": "EUR",
    "amount": 99.99,
    "result": 91.79,
    "rate": 0.9180
  }
}

这 rate 字段是原始汇率。 这 result 字段是 换算后的金额，四舍五入至小数点后两位。 您两者都可以，这样您就可以显示费率 向用户提供或在您自己的代码中验证数学。

一次获取所有汇率

如果您需要多种货币的汇率，请致电 /v1/currency/convert 为了 每对都是浪费。 这 /v1/currency/rates 端点返回每个可用的 单一响应中给定基础货币的汇率。

curl -X POST https://api.botoi.com/v1/currency/rates \\
  -H "Content-Type: application/json" \\
  -d '{"base": "USD"}'

响应（截断为 9 种货币）：

{
  "success": true,
  "data": {
    "base": "USD",
    "rates": {
      "EUR": 0.9180,
      "GBP": 0.7891,
      "JPY": 149.52,
      "CAD": 1.3612,
      "AUD": 1.5340,
      "CHF": 0.8821,
      "INR": 83.4150,
      "BRL": 4.9720,
      "MXN": 17.1340
    }
  }
}

一项请求，170 多个费率。 将此响应缓存一小时，您可以转换任意金额 本地，无需进行额外的 API 调用。 这是结帐流程采用的方法 以及您同时需要多种货币的定价页面。

即时转换的价格显示组件

用户可以从下拉列表中选择货币的定价页面。 这个 Preact 组件调用 选择更改时的转换端点并显示结果。

import { useState, useEffect } from "preact/hooks";

const SUPPORTED_CURRENCIES = ["USD", "EUR", "GBP", "JPY", "CAD"];

function PriceDisplay({ priceUsd }) {
  const [currency, setCurrency] = useState("USD");
  const [converted, setConverted] = useState(priceUsd);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (currency === "USD") {
      setConverted(priceUsd);
      return;
    }

    setLoading(true);
    fetch("https://api.botoi.com/v1/currency/convert", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        from: "USD",
        to: currency,
        amount: priceUsd,
      }),
    })
      .then((res) => res.json())
      .then(({ data }) => {
        setConverted(data.result);
        setLoading(false);
      });
  }, [currency, priceUsd]);

  return (
    <div>
      <select
        value={currency}
        onChange={(e) => setCurrency(e.target.value)}
      >
        {SUPPORTED_CURRENCIES.map((c) => (
          <option key={c} value={c}>{c}</option>
        ))}
      </select>
      <span>
        {loading ? "..." : \`\\\${converted.toFixed(2)} \\\${currency}\`}
      </span>
    </div>
  );
}

该组件默认为美元，并且仅当用户选择不同的美元时才调用 API 货币。 对于生产，将其包装在缓存层中（如下所述），以便切换回并 货币之间的往来不会重复API调用。

用于多币种结帐的 Node.js 中间件

电子商务结账需要将整个购物车从您的基础货币转换为买家的货币 当地货币。 该中间件获取一次汇率，将其缓存一小时，然后进行转换 每个订单项无需额外的 API 调用。

import express from "express";

const app = express();
app.use(express.json());

// Cache rates in memory with a 1-hour TTL
let ratesCache = null;
let cacheTimestamp = 0;
const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour

async function getRates(base) {
  const now = Date.now();

  if (ratesCache && ratesCache.base === base && now - cacheTimestamp < CACHE_TTL_MS) {
    return ratesCache;
  }

  const res = await fetch("https://api.botoi.com/v1/currency/rates", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.BOTOI_API_KEY,
    },
    body: JSON.stringify({ base }),
  });
  const { data } = await res.json();

  ratesCache = data;
  cacheTimestamp = now;
  return data;
}

function convertAmount(rates, from, to, amount) {
  if (from === to) return amount;

  // If "from" is the base currency, multiply by the target rate
  if (from === rates.base) {
    return Math.round(amount * rates.rates[to] * 100) / 100;
  }

  // Otherwise, convert to base first, then to target
  const inBase = amount / rates.rates[from];
  return Math.round(inBase * rates.rates[to] * 100) / 100;
}

app.post("/checkout", async (req, res) => {
  const { items, currency } = req.body;

  // Calculate total in USD (your base currency)
  const totalUsd = items.reduce((sum, item) => sum + item.price * item.qty, 0);

  // Convert to the buyer's currency
  const rates = await getRates("USD");
  const totalLocal = convertAmount(rates, "USD", currency, totalUsd);

  res.json({
    currency,
    total: totalLocal,
    rate: rates.rates[currency],
    items: items.map((item) => ({
      ...item,
      localPrice: convertAmount(rates, "USD", currency, item.price),
    })),
  });
});

app.listen(3000);

这 convertAmount 函数处理两种情况： 直接转换时 来源与基础货币匹配，如果不匹配则进行交叉汇率转换。 的 内存缓存意味着 API 每小时调用一次，而不是每次结账调用一次。

对于高流量存储，请将缓存移至 Redis 或边缘 KV 存储，以便所有服务器 实例共享相同的缓存速率。

缓存汇率以减少 API 调用

汇率不会瞬间改变。 对于大多数应用程序，缓存速率为 1-4 小时 就足够了。 此模式使用具有基于 TTL 过期时间的内存中映射并预热缓存 启动时最常见的货币对。

const RATES_CACHE = new Map();
const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours

async function getCachedRate(from, to) {
  const key = \`\\\${from}:\\\${to}\

这 warmCache 函数在启动时运行并预取五个最常见的 对。 此后，当 TTL 到期时，每对都会按照自己的计划进行刷新。 你留下来 即使有数十种货币对，也完全在免费套餐每天 100 个请求的限制之内。

选择缓存 TTL

• 1小时： 适合您希望价格保持新鲜的结账流程 在用户会话期间。
• 4小时： 适用于定价页面、仪表板和报告工具。 费率每个工作日更新一次，因此 4 小时缓存可以捕获当天的变化。
• 24小时： 非常适合分析、发票和财务报告，其中 昨天的价格可以接受。

要点

• /v1/currency/convert 在 170+ 中任意两个之间转换特定金额 支持的货币。 返回转换后的结果和使用的速率。
• /v1/currency/rates 返回基础货币的所有可用汇率 在一个回应中。 在本地缓存以避免每次转换 API 调用。
• 两个端点均以每分钟 5 个请求和每天 100 个请求的速度匿名运行。 通过一个 X-Api-Key 更高限制的标头。
• 缓存速率为 1-4 小时，具体取决于您的准确性要求。 汇率 每个工作日更新一次。
• 该 API 在 Cloudflare 的边缘网络上运行。 响应时间为20-50ms。 与它配对 本地缓存和货币转换为面向用户的请求添加了零延迟。