@unirate/nestjs

Official NestJS module for the UniRate currency-exchange API. Drop-in UniRateModule.forRoot() / forRootAsync(), an injectable UniRateService, and an optional exception filter that maps UniRate errors to HTTP status codes.

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/nestjs

Peer dependencies (use the versions your Nest app already pins): @nestjs/common ^10 || ^11, @nestjs/core ^10 || ^11, rxjs ^7, reflect-metadata ^0.1.13 || ^0.2. Native fetch is required (Node ≥ 20.12).

Quick start

Synchronous

import { Module } from "@nestjs/common";
import { UniRateModule } from "@unirate/nestjs";

@Module({
  imports: [
    UniRateModule.forRoot({ apiKey: process.env.UNIRATE_API_KEY! }),
  ],
})
export class AppModule {}

Async (typical — pulls the key from ConfigService)

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { UniRateModule } from "@unirate/nestjs";

@Module({
  imports: [
    ConfigModule.forRoot(),
    UniRateModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        apiKey: config.getOrThrow("UNIRATE_API_KEY"),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Both forms register the module as @Global() — call forRoot() / forRootAsync() once at the app root and UniRateService is injectable everywhere without re-importing.

useClass and useExisting are also supported; see UniRateModuleAsyncOptions.

Usage

import { Controller, Get, Query } from "@nestjs/common";
import { UniRateService } from "@unirate/nestjs";

@Controller("prices")
export class PricesController {
  constructor(private readonly rates: UniRateService) {}

  @Get("convert")
  async convert(
    @Query("from") from: string,
    @Query("to") to: string,
    @Query("amount") amount = 1,
  ): Promise<{ result: number }> {
    const result = await this.rates.convert(to, Number(amount), from);
    return { result };
  }

  @Get("rates")
  async snapshot(@Query("base") base = "USD"): Promise<Record<string, number>> {
    return this.rates.getRate(base);
  }
}

UniRateService API

| Method | Returns | Notes | |---|---|---| | getRate(from, to) | Promise<number> | Single pair | | getRate(from) | Promise<Record<string, number>> | Full snapshot keyed by ISO code | | convert(to, amount, from) | Promise<number> | | | listCurrencies() | Promise<string[]> | | | getHistoricalRate(date, amount, from, to?) | Promise<number \| Record<string, number>> | Pro | | getTimeSeries(start, end, amount, base, currencies?) | Promise<Record<date, Record<currency, number>>> | Pro | | getHistoricalLimits() | Promise<HistoricalLimitsResponse> | | | getVATRates(country?) | Promise<VATRatesAll \| VATRateOne> | | | raw (getter) | UniRateClient | Escape hatch for libraries that already understand UniRateClient |

Dates are YYYY-MM-DD. Currency codes are case-insensitive on input and normalised to uppercase before being sent to the API.

Error handling

UniRateService throws typed error subclasses for the documented HTTP errors:

• AuthenticationError — 401, bad / missing key
• RateLimitError — 429
• InvalidCurrencyError — 404, unknown currency code
• InvalidRequestError — 400, bad params
• ProRequiredError — 403, endpoint requires a Pro subscription
• UniRateError — base class for any other failure

Exception filter (optional)

Drop the bundled filter in globally and UniRateError subclasses become standard HTTP responses (401/403/404/400/429/502):

import { APP_FILTER } from "@nestjs/core";
import { UniRateExceptionFilter } from "@unirate/nestjs";

@Module({
  imports: [UniRateModule.forRoot({ apiKey: process.env.UNIRATE_API_KEY! })],
  providers: [{ provide: APP_FILTER, useClass: UniRateExceptionFilter }],
})
export class AppModule {}

Or scope it to a controller / handler with @UseFilters(UniRateExceptionFilter). Without the filter, errors surface as generic 500s — fine for batch jobs and CLIs but rarely what you want in an HTTP controller.

Injection tokens

For advanced wiring (e.g. swapping in a fake client during integration tests):

import { Inject, Injectable } from "@nestjs/common";
import { UNIRATE_CLIENT, UniRateClient } from "@unirate/nestjs";

@Injectable()
export class Reporting {
  constructor(@Inject(UNIRATE_CLIENT) private readonly client: UniRateClient) {}
}

UNIRATE_OPTIONS exposes the raw options object the same way.

Standalone client

If you need the raw client outside of Nest (CLI scripts, background workers without a Nest context), import it directly:

import { UniRateClient } from "@unirate/nestjs/client";

const client = new UniRateClient({ apiKey: process.env.UNIRATE_API_KEY! });
const rates = await client.getRate("USD");

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are all maintained under the UniRate-API org.

• Languages: Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
• Web frameworks: NestJS · Django / Wagtail · FastAPI · Flask · React · tRPC
• Static-site generators: Astro · Eleventy · Hugo
• Data / orchestration: Airflow · dbt · LangChain
• Workflow / no-code: n8n · Google Sheets · MCP server
• Editors / tools: VS Code · Obsidian
• Specialty bridges: NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT © UniRate