@unirate/ai-sdk

Vercel AI SDK tools for the UniRate currency-exchange API.

Drop four ready-made tool() definitions into any AI SDK agent so your model can convert currencies, look up exchange rates, list supported currencies, and fetch VAT rates. Mirrors the @unirate/langchain-js package.

UniRate API · 593+ fiat, crypto & commodity instruments · Free tier available

Installation

npm install @unirate/ai-sdk ai zod

ai and zod are peer dependencies — install them alongside this package. Compatible with AI SDK v4 and v5 (each tool ships both the v4 parameters and v5 inputSchema field).

Quick start

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { createUniRateTools } from "@unirate/ai-sdk";

const tools = createUniRateTools({ apiKey: process.env.UNIRATE_API_KEY });

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  maxSteps: 5,
  prompt: "Convert 250 USD to JPY, then tell me Germany's VAT rate.",
});

console.log(text);

createUniRateTools() returns a record keyed by tool name — exactly the shape the AI SDK's generateText / streamText expect for their tools option.

Tools

createUniRateTools() returns:

| Key | Purpose | Input | |---|---|---| | unirate_exchange | Convert an amount between two currencies | from_currency, to_currency, amount? | | unirate_rate | Current rate for a pair, or all rates from a base | from_currency, to_currency? | | unirate_currencies | List all supported currency codes | — | | unirate_vat | VAT rate for a country, or all countries | country? |

Each tool is also available as an individual factory:

import {
  createExchangeTool,
  createRateTool,
  createCurrenciesTool,
  createVatTool,
} from "@unirate/ai-sdk";

const tools = {
  fx: createExchangeTool({ apiKey: process.env.UNIRATE_API_KEY }),
  vat: createVatTool({ apiKey: process.env.UNIRATE_API_KEY }),
};

unirate_exchange

// model input: { from_currency: "USD", to_currency: "EUR", amount: 100 }
// tool output: "100 USD = 92.5 EUR (UniRate latest rate)"

unirate_rate

// { from_currency: "USD", to_currency: "EUR" }
// → "1 USD = 0.925 EUR (UniRate latest rate)"

// { from_currency: "USD" }  (omit target)
// → "Rates from USD (first 10): EUR: 0.925, GBP: 0.79, ..."

unirate_currencies

// {}
// → "UniRate supports 593 currencies: USD, EUR, GBP, ..."

unirate_vat

// { country: "DE" }
// → "Germany (DE) VAT rate: 19%"

// {}  (omit country)
// → "VAT rates for 50 countries (first 10): AT: 20%, BE: 21%, ..."

UniRateAPIWrapper

The wrapper class is exported for use outside an agent context (or to share one client instance across tools):

import { UniRateAPIWrapper, createUniRateTools } from "@unirate/ai-sdk";

const wrapper = new UniRateAPIWrapper(); // reads UNIRATE_API_KEY from env
const tools = createUniRateTools(wrapper); // shares the wrapper

console.log(await wrapper.getRate("USD", "EUR")); // 0.925
console.log(await wrapper.convert("USD", "EUR", 100)); // 92.5
console.log(await wrapper.listCurrencies()); // ["USD", "EUR", ...]
console.log(await wrapper.getVatRate("DE")); // { country_code: "DE", country_name: "Germany", vat_rate: 19 }

Errors

All errors extend UniRateError:

| HTTP | Class | Meaning | |---|---|---| | 400 | InvalidRequestError | Bad parameters | | 401 | AuthenticationError | Missing/invalid API key | | 403 | ProRequiredError | Endpoint requires a Pro subscription | | 404 | InvalidCurrencyError | Unknown currency | | 429 | RateLimitError | Rate limit exceeded | | 503 / other | UniRateError | Service unavailable / generic (carries .status) |

Errors surface through the tool's execute — handle them in your agent loop as you would any tool error.

Security

• Zero runtime dependencies; ai and zod are peers provided by your app.
• Native fetch only — no transitive HTTP-client supply-chain surface.
• API key never leaves the server; tools are designed for server-side agent use.
• Published to npm with provenance attestation.

Part of the UniRate ecosystem

Official UniRate clients & framework integrations: Python · Node · React · Vue · Nuxt · Next.js · SvelteKit · NestJS · Remix · Angular · Astro · Eleventy · LangChain (Python) · LangChain.js · MCP server

License

MIT © Unirate Team