@unirate/fastify

Official Fastify plugin for the UniRate currency-exchange API. Registered with fastify-plugin semantics, it decorates your Fastify instance with a typed unirate client and can optionally mount read-only proxy routes that keep your API key server-side.

UniRate offers free real-time exchange rates for 170+ currencies plus VAT data; historical rates and time-series are Pro-tier endpoints.

Install

npm install @unirate/fastify

fastify is a peer dependency (>=4.0.0, works with v4 and v5). Native fetch is required (Node ≥ 20.12). Zero runtime dependencies.

Quick start

import Fastify from "fastify";
import unirate from "@unirate/fastify";

const app = Fastify();

await app.register(unirate, {
  apiKey: process.env.UNIRATE_API_KEY!,
});

app.get("/price", async () => {
  // `app.unirate` is fully typed thanks to module augmentation.
  const rate = await app.unirate.getRate("USD", "EUR");
  return { usd_to_eur: rate };
});

await app.listen({ port: 3000 });

Because the plugin is wrapped with fastify-plugin semantics, the unirate decorator is registered on the root instance and is available in every encapsulated route context — register it once.

Options

await app.register(unirate, {
  apiKey: process.env.UNIRATE_API_KEY!, // required
  baseUrl: "https://api.unirateapi.com", // optional override
  timeoutMs: 30_000,                      // optional request timeout
  userAgent: "my-app/1.0",               // optional User-Agent
  decorateName: "unirate",               // optional; name of the decorator
  routes: false,                          // optional; mount proxy routes
  routePrefix: "/unirate",               // optional; route prefix
});

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Required. Your UniRate API key. | | baseUrl | string | https://api.unirateapi.com | API base URL. | | timeoutMs | number | 30000 | Per-request timeout. | | userAgent | string | @unirate/fastify/<version> | User-Agent header. | | decorateName | string | "unirate" | Instance decorator name (fastify.<name>). | | routes | boolean | false | Mount read-only proxy routes. | | routePrefix | string | "/unirate" | Prefix for the mounted routes. |

The decorated client

app.unirate is a UniRateClient with the standard UniRate method surface:

await app.unirate.getRate("USD", "EUR");          // number
await app.unirate.getRate("USD");                 // Record<string, number>
await app.unirate.convert("EUR", 100, "USD");     // number
await app.unirate.getSupportedCurrencies();       // string[]
await app.unirate.getVatRates();                  // all VAT rates
await app.unirate.getVatRates("DE");              // one country
// Pro-tier (403 on free plans):
await app.unirate.getHistoricalRate("2024-01-01", 1, "USD", "EUR");
await app.unirate.getTimeSeries("2024-01-01", "2024-01-07");
await app.unirate.getHistoricalLimits();

Currency and country codes are uppercased automatically.

Optional proxy routes

Set routes: true to expose read-only endpoints. Your API key stays on the server — the browser never sees it.

await app.register(unirate, {
  apiKey: process.env.UNIRATE_API_KEY!,
  routes: true,
});

| Route | Query | Returns | |---|---|---| | GET /unirate/rate | from (default USD), to | { from, to, rate } or { from, rates } | | GET /unirate/convert | from (default USD), to (required), amount (default 1) | { from, to, amount, result } | | GET /unirate/currencies | — | { currencies } | | GET /unirate/vat | country (optional) | all VAT rates, or one country |

curl 'http://localhost:3000/unirate/rate?from=USD&to=EUR'
curl 'http://localhost:3000/unirate/convert?from=USD&to=EUR&amount=100'
curl 'http://localhost:3000/unirate/currencies'
curl 'http://localhost:3000/unirate/vat?country=DE'

Error handling

The plugin exports the full typed-error hierarchy from the client, all extending UniRateError:

| Error | HTTP status | |---|---| | InvalidRequestError | 400 | | AuthenticationError | 401 | | ProRequiredError | 403 | | InvalidCurrencyError | 404 | | RateLimitError | 429 | | ServiceUnavailableError | 503 |

When you call the decorated client yourself, catch these:

import { RateLimitError } from "@unirate/fastify";

try {
  await app.unirate.getRate("USD", "EUR");
} catch (err) {
  if (err instanceof RateLimitError) {
    // back off
  }
}

The mounted proxy routes translate these to the corresponding HTTP status codes automatically (transport failures become 502). The statusForError(err) helper is exported if you want the same mapping in your own error handler.

Rate limits

Free-tier keys are rate-limited; a 429 surfaces as RateLimitError. Historical and time-series endpoints return 403 (ProRequiredError) on free plans.

Related clients

Part of the UniRate family: @unirate/nestjs, @unirate/next, @unirate/react, unirate-api (framework-agnostic Node client), and more.

License

MIT — see LICENSE.