directus-extension-unirate

A Directus extension bundle for the UniRate currency-exchange API. It adds two things to your Directus instance:

1. /unirate REST endpoint — proxies UniRate from your Directus server so the API key never reaches the browser. Hand your frontend /unirate/convert?to=EUR&amount=100 instead of exposing a key.
2. "UniRate Currency" Flow operation — a no-code Flows node that converts an amount, fetches a rate, or lists supported currencies inside any automation.

Zero runtime dependencies — pure native fetch. The API key lives only in your Directus environment.

---

Install

From the Directus Marketplace

In your Directus project, open Settings → Marketplace, search for UniRate, and install. (Marketplace availability depends on your hosting: self-hosted instances can install any extension; Directus Cloud lists sandboxed/registry extensions.)

Manually (self-hosted)

npm install directus-extension-unirate

Directus auto-discovers extensions in node_modules whose name starts with directus-extension-. Restart Directus after installing.

Configure the API key

Set the key in your Directus environment (.env, Docker env, etc.):

UNIRATE_API_KEY=your_key_here
# optional override (defaults to https://api.unirateapi.com)
# UNIRATE_API_BASE_URL=https://api.unirateapi.com

EXTENSION_UNIRATE_API_KEY is also accepted. Get a free key at unirateapi.com.

---

The /unirate endpoint

All routes are GET, return JSON, and keep your key server-side. They are mounted under /unirate on your Directus API.

Route	Query params	Returns
/unirate/rates	from (default USD), to (optional)	{ from, to, rate } or { from, rates }
/unirate/convert	to (required), from (default USD), amount (default 1)	{ from, to, amount, result }
/unirate/currencies	—	{ currencies: [...] }
/unirate/vat	country (optional, ISO-3166 alpha-2)	UniRate VAT payload
/unirate/historical	date (required, YYYY-MM-DD), from, to, amount	historical rate/result — Pro-gated

# single rate
curl 'https://your-directus.example.com/unirate/rates?from=USD&to=EUR'
# → { "from": "USD", "to": "EUR", "rate": 0.92 }

# convert
curl 'https://your-directus.example.com/unirate/convert?to=JPY&amount=49.99'
# → { "from": "USD", "to": "JPY", "amount": 49.99, "result": 7847.1 }

# supported currencies
curl 'https://your-directus.example.com/unirate/currencies'
# → { "currencies": ["USD", "EUR", "GBP", ...] }

The /unirate/historical route requires a UniRate Pro plan. On the free tier it returns the upstream 403 unchanged.

Errors

Upstream UniRate errors are mapped to HTTP status + a JSON { "error": "..." } body: 400 invalid params, 401 bad/missing key, 403 Pro-only, 404 unknown currency, 429 rate-limited, 502 upstream/network failure. If the key is not configured the endpoint returns 503.

---

The "UniRate Currency" Flow operation

Add the UniRate Currency operation to any Flow. Configure:

• Operation — Convert amount, Get rate, or List currencies
• From currency — ISO 4217 code (default USD)
• To currency — ISO 4217 code (required for convert/rate)
• Amount — number (used by convert, default 1)

The operation's result is written to its data key for downstream steps:

// Convert amount
{ "from": "USD", "to": "EUR", "amount": 100, "result": 92.0 }

// Get rate (with To)
{ "from": "USD", "to": "EUR", "rate": 0.92 }

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

A missing key or an upstream failure throws, routing the Flow down its reject path so you can handle it (notify, retry, fall back).

Example uses: stamp a converted price_eur onto an item on create, post a daily FX snapshot to Slack, or validate a currency code against the live supported list.

---

Reusing the typed client

The bundle also exports the standalone, dependency-free TypeScript client used under the hood — handy in custom hooks or other extensions:

import { UniRateClient, ProRequiredError } from "directus-extension-unirate/client";

const client = new UniRateClient({ apiKey: process.env.UNIRATE_API_KEY! });
const eur = await client.convert("EUR", 100, "USD");

---

Security

• The UniRate API key is read only from the Directus server environment and is never sent to the browser or included in any response.
• The package ships zero runtime dependencies (native fetch), built with plain tsc — no bundler/transpiler tree pulled into your install.
• Published to npm with provenance (npm attestations).

---

Development

npm install
npm run typecheck
npm test          # vitest mock suite
npm run build     # tsc → dist/

CI runs typecheck + tests + build on Node 20 and 22.

---

UniRate ecosystem

UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.

Core clients (9 languages) Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift

JavaScript / TypeScript React · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC

Static-site generators Astro · Eleventy · Hugo · Jekyll

CMS & e-commerce Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus

Data, AI & backend LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt

Platform & tools MCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian

Money library bridges money gem (Ruby) · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT © 2026 UniRate API