haystack-unirate

Haystack integration for the UniRate API — drop-in currency-exchange components for Haystack 2.x pipelines.

UniRate provides 593+ fiat, crypto, and commodity exchange rates. Latest rates, conversions, and currency listings are available on the free tier; historical and time-series endpoints require a Pro plan.

Why this package

There's no first-class FX component in core Haystack. This package gives you typed, tested @component-decorated blocks that slot straight into a Pipeline — with Secret-based API-key handling and full to_dict / from_dict serialization so pipelines round-trip to YAML/JSON cleanly.

Install

pip install haystack-unirate

Quick start

import os

os.environ["UNIRATE_API_KEY"] = "..."  # https://unirateapi.com

from haystack.utils import Secret
from haystack_unirate import (
    UniRateConverter,
    UniRateCurrencies,
    UniRateExchangeRate,
)

api_key = Secret.from_env_var("UNIRATE_API_KEY")

rate = UniRateExchangeRate(api_key=api_key)
print(rate.run(from_currency="USD", to_currency="GBP")["rate"])       # 0.79

converter = UniRateConverter(api_key=api_key)
print(converter.run(from_currency="USD", to_currency="EUR", amount=100)["result"])  # 92.5

currencies = UniRateCurrencies(api_key=api_key)
print(currencies.run()["currencies"][:5])

In a pipeline

from haystack import Pipeline
from haystack.utils import Secret

from haystack_unirate import UniRateConverter

pipeline = Pipeline()
pipeline.add_component(
    "convert", UniRateConverter(api_key=Secret.from_env_var("UNIRATE_API_KEY"))
)

result = pipeline.run(
    {"convert": {"from_currency": "USD", "to_currency": "JPY", "amount": 250}}
)
print(result["convert"]["result"])

Components

Component	Output sockets	Description
UniRateExchangeRate	rate: float, rates: dict	Latest rate for a pair; if to_currency is omitted, rates holds every supported target and rate is None.
UniRateConverter	result: float	Convert amount from one currency to another at the latest rate.
UniRateCurrencies	currencies: list[str]	All currency codes UniRate can convert between.

Each component takes:

Constructor arg	Env var	Default
api_key (Secret)	UNIRATE_API_KEY	— (required)
base_url	—	https://api.unirateapi.com
timeout	—	30.0 (seconds)

Error handling

Non-2xx responses raise UniRateAPIError (subclass of RuntimeError) with a .status_code attribute:

Status	Meaning
400	Invalid request parameters
401	Missing or invalid API key
403	Endpoint requires a Pro subscription (e.g. historical data)
404	Currency not found or no data available
429	Rate limit exceeded
503	Service unavailable

Transport failures raise UniRateAPIError with status_code=None.

Related UniRate clients

If you want to call the API directly from a non-Haystack application, there are official clients in Python, Node.js, Go, Rust, Java, Ruby, PHP, .NET, and Swift, a LangChain integration, and an MCP server.

License

MIT — see LICENSE.