@unirate/langchain-js

LangChain.js integration for the UniRate currency-exchange API.

Drop three structured tools into any LangChain.js agent to handle FX queries: exchange currency amounts, look up rates, and list supported currencies. Mirrors the Python langchain-unirate package.

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

Installation

npm install @unirate/langchain-js @langchain/core zod

@langchain/core and zod are peer dependencies — install them alongside this package.

Quick start

import { createUniRateTools, UniRateAPIWrapper } from "@unirate/langchain-js";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";

// Share one wrapper across all tools
const wrapper = new UniRateAPIWrapper({ apiKey: process.env.UNIRATE_API_KEY });
const tools = createUniRateTools(wrapper);

const llm = new ChatOpenAI({ model: "gpt-4o" });
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful currency assistant."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);

const agent = createToolCallingAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

const result = await executor.invoke({ input: "Convert 250 USD to JPY" });
console.log(result.output);

Tools

unirate_exchange — UniRateExchangeTool

Convert an amount from one currency to another.

Parameter	Type	Description
from_currency	string	ISO 4217 source code (e.g. "USD", "BTC")
to_currency	string	ISO 4217 target code
amount	number (optional)	Amount to convert, defaults to 1

const tool = new UniRateExchangeTool({ apiKey: "..." });
await tool.invoke({ from_currency: "USD", to_currency: "EUR", amount: 100 });
// → "100 USD = 92.5 EUR (UniRate latest rate)"

unirate_rate — UniRateRateTool

Look up the exchange rate between two currencies (or all rates from a base).

const tool = new UniRateRateTool({ apiKey: "..." });
await tool.invoke({ from_currency: "USD", to_currency: "EUR" });
// → "1 USD = 0.925 EUR (UniRate latest rate)"

unirate_currencies — UniRateCurrenciesTool

List all 593+ supported currency codes.

const tool = new UniRateCurrenciesTool({ apiKey: "..." });
await tool.invoke({});
// → "UniRate supports 593 currencies: USD, EUR, GBP, ..."

UniRateAPIWrapper

The wrapper class is available for use outside of an agent context:

import { UniRateAPIWrapper } from "@unirate/langchain-js";

const wrapper = new UniRateAPIWrapper(); // reads UNIRATE_API_KEY from env
console.log(await wrapper.getRate("USD", "EUR")); // 0.925
console.log(await wrapper.convert("USD", "EUR", 100)); // 92.5
console.log(await wrapper.run("USD", "EUR", 100)); // "100 USD = 92.5 EUR (UniRate latest rate)"

Factory convenience

import { createUniRateTools } from "@unirate/langchain-js";

// Pass options directly — a shared wrapper is created internally
const [exchangeTool, rateTool, currenciesTool] = createUniRateTools({
  apiKey: process.env.UNIRATE_API_KEY,
});

Errors

All errors extend UniRateError:

HTTP	Class	Meaning
400	InvalidRequestError	Bad parameters
401	AuthenticationError	Missing/invalid API key
403	ProRequiredError	Historical endpoints (Pro plan)
404	InvalidCurrencyError	Unknown currency
429	RateLimitError	Rate limit exceeded

Security

• Zero runtime dependencies; @langchain/core 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

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 © UniRate