@unirate/express

Express middleware and router for the UniRate API — free currency exchange rates, conversion, and VAT rates.

Attach a typed UniRate client to every request, or mount a ready-made set of JSON endpoints, and keep your API key server-side. Works with Express 4 and 5.

Features

• unirateClient() middleware — attaches a typed UniRateClient to req.unirate
• unirate() — a mountable Express Router with /rate, /convert, /currencies, /vat routes
• Full error mapping — UniRate statuses (400 / 401 / 403 / 404 / 429 / 503) mirrored to proper HTTP responses; transport failures become 502; a missing key becomes 500
• Currency-code validation + uppercasing
• API key read from options or the UNIRATE_API_KEY environment variable
• Zero runtime dependencies (uses native fetch); express is a peer dependency
• TypeScript throughout — req.unirate is typed via Express module augmentation
• ESM + CJS builds

Install

npm install @unirate/express express

express is a peer dependency (>=4.0.0, works with v4 and v5). Requires Node 18+ for native fetch. Get a free UniRate API key at unirateapi.com.

Quick start

Middleware

import express from "express";
import { unirateClient } from "@unirate/express";

const app = express();
app.use(unirateClient()); // reads process.env.UNIRATE_API_KEY

app.get("/eur", async (req, res) => {
  const rate = await req.unirate.getRate("USD", "EUR");
  res.json({ pair: "USD/EUR", rate });
});

app.listen(3000);

req.unirate is fully typed via Express's Request interface — no casting needed.

Router

import express from "express";
import { unirate } from "@unirate/express";

const app = express();
app.use("/api/unirate", unirate());

That mounts:

GET /api/unirate/rate?from=USD&to=EUR
GET /api/unirate/convert?from=USD&to=EUR&amount=100
GET /api/unirate/currencies
GET /api/unirate/vat?country=DE

Options

Both unirateClient() and unirate() accept the same options:

Option	Type	Default	Description
apiKey	string	—	API key. If omitted, resolved from the env variable
envKey	string	"UNIRATE_API_KEY"	Name of the env variable to read the key from
baseUrl	string	https://api.unirateapi.com	Override the API base URL
fetch	typeof fetch	globalThis.fetch	Inject a custom fetch
timeoutMs	number	30000	Request timeout
userAgent	string	@unirate/express/<version>	Custom User-Agent header

app.use(unirateClient({ apiKey: process.env.UNIRATE_API_KEY }));
// or a custom env variable name
app.use("/fx", unirate({ envKey: "MY_UNIRATE_KEY" }));

Routes

GET /rate

Param	Required	Default	Description
from	no	USD	Source currency (3-letter ISO code)
to	no	—	Target currency. Omit to return all rates for from

// /rate?from=USD&to=EUR  →
{ "rate": 0.92 }
// /rate?from=USD  →
{ "rates": { "EUR": 0.92, "GBP": 0.79 } }

GET /convert

Param	Required	Default	Description
from	no	USD	Source currency
to	yes	—	Target currency
amount	no	1	Amount to convert (positive number)

// /convert?from=USD&to=EUR&amount=100  →
{ "result": 92.5 }

GET /currencies

{ "currencies": ["USD", "EUR", "GBP", "..."] }

GET /vat

Param	Required	Default	Description
country	no	—	ISO-3166 alpha-2 code. Omit for all countries

// /vat?country=DE  →
{ "country": "DE", "vat_data": { "country_code": "DE", "country_name": "Germany", "vat_rate": 19 } }

Using the client directly

The internal client is exported for direct use in your own handlers:

import { UniRateClient, RateLimitError } from "@unirate/express";

const client = new UniRateClient({ apiKey: "..." });

try {
  const rate = await client.getRate("USD", "EUR");        // number
  const all = await client.getRate("USD");                // Record<string, number>
  const eur = await client.convert("EUR", 100, "USD");    // number
  const codes = await client.getSupportedCurrencies();    // string[]
  const vat = await client.getVatRate("DE");              // { country, vat_data }
} catch (err) {
  if (err instanceof RateLimitError) {
    // back off and retry
  }
}

It is also available on the @unirate/express/client subpath if you want the client without pulling in the Express glue.

Error handling

The router maps thrown errors to HTTP responses with a { "error": string } body:

Status	Meaning
400	Invalid parameter (bad currency/country code, missing/invalid amount)
401	Missing or invalid API key
403	Endpoint requires a Pro subscription
404	Currency not found or no data available
429	Rate limit exceeded
500	API key not configured on the server
502	UniRate upstream / transport error
503	Service unavailable

When using the client directly, these map to typed error classes — all extending UniRateError: InvalidRequestError, AuthenticationError, ProRequiredError, InvalidCurrencyError, RateLimitError, ServiceUnavailableError.

Free vs Pro tier

The free tier covers /rate, /convert, /currencies, and /vat. Historical and time-series endpoints require a Pro subscription and are not exposed by this package.

Example

A runnable Express app lives in examples/server.mjs:

npm run build
UNIRATE_API_KEY=your-key node examples/server.mjs

Related packages

UniRate API client libraries: Python · Node.js · Go · Rust · Ruby · PHP · Java · Swift · .NET

Framework integrations: Fastify · Hono · Next.js · Nuxt · SvelteKit · Astro · NestJS · Remix · Angular · Vue · React

Platform: Cloudflare Workers · MCP server · CLI

License

MIT © Unirate Team