@unirate/hono

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

Attach a typed UniRate client to your request context, or mount a ready-made set of JSON endpoints, and keep your API key server-side. Runs on any Hono runtime: Cloudflare Workers, Bun, Node.js, and Deno.

Features

• unirate() middleware — attaches a typed UniRateClient to c.var.unirate
• unirateRouter() — a mountable Hono sub-app 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
• Currency-code validation + uppercasing
• API key read from options or the UNIRATE_API_KEY environment binding
• Zero runtime dependencies (uses native fetch); hono is a peer dependency
• TypeScript throughout, ESM-first

Install

npm install @unirate/hono hono

hono is a peer dependency (>=4.0.0). Get a free UniRate API key at unirateapi.com.

Quick start

Middleware

import { Hono } from "hono";
import { unirate } from "@unirate/hono";

type Env = { Bindings: { UNIRATE_API_KEY: string } };

const app = new Hono<Env>();
app.use(unirate()); // reads c.env.UNIRATE_API_KEY

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

export default app;

c.var.unirate is fully typed via Hono's ContextVariableMap — no casting needed.

Router

import { Hono } from "hono";
import { unirateRouter } from "@unirate/hono";

const app = new Hono();
app.route("/api/unirate", unirateRouter());

export default app;

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 unirate() and unirateRouter() accept the same options:

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | API key. If omitted, resolved from the env binding | | envKey | string | "UNIRATE_API_KEY" | Name of the env binding 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 |

app.use(unirate({ apiKey: process.env.UNIRATE_API_KEY }));
// or a custom binding name
app.route("/fx", unirateRouter({ 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/hono";

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
  }
}

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 Hono app lives in examples/server.ts:

UNIRATE_API_KEY=your-key npx tsx examples/server.ts

Related packages

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

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

Platform: Cloudflare Workers · MCP server · CLI

License

MIT © Unirate Team