@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

License

MIT © UniRate