pydantic-ai-unirate

Pydantic AI integration for the UniRate API — a drop-in currency-exchange toolset for Pydantic AI agents.

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

Why this package

Pydantic AI has no built-in FX tool — most examples hand-roll one against exchangerate-api.com or AlphaVantage. This package gives you a typed, tested UniRateToolset (a subclass of pydantic_ai.toolsets.FunctionToolset, i.e. an AbstractToolset) that plugs straight into an Agent, plus the underlying async wrapper and tool functions if you want to compose your own toolset.

Install

pip install pydantic-ai-unirate

Quick start

import os

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

from pydantic_ai import Agent

from pydantic_ai_unirate import UniRateToolset

agent = Agent("openai:gpt-4o-mini", toolsets=[UniRateToolset()])

result = agent.run_sync("How many euros is 250 US dollars right now?")
print(result.output)

The toolset registers four tools the model can call:

Direct use of the wrapper

The transport layer is a standalone async client you can call without an agent:

import asyncio

from pydantic_ai_unirate import UniRateAPIWrapper


async def main() -> None:
    async with UniRateAPIWrapper() as unirate:
        print(await unirate.convert("USD", "EUR", amount=100))  # 92.5
        print(await unirate.get_rate("USD", "GBP"))             # 0.79
        print((await unirate.get_supported_currencies())[:5])
        print(await unirate.get_vat_rates("DE"))


asyncio.run(main())

Composing your own toolset

The tool functions are exported so you can register them on an existing FunctionToolset or hand them to an agent individually. Each takes the UniRateAPIWrapper as its first argument:

from pydantic_ai.toolsets import FunctionToolset

from pydantic_ai_unirate import UniRateAPIWrapper, convert, get_rate

wrapper = UniRateAPIWrapper()
toolset = FunctionToolset()
toolset.add_function(lambda from_currency, to_currency: get_rate(wrapper, from_currency, to_currency), name="get_rate")

Configuration

UniRateToolset(api_key=..., enable_historical=..., wrapper=...) forwards to the wrapper; pass a pre-built wrapper= to share an httpx client.

Error handling

Every failure raises a typed subclass of UniRateError:

Related UniRate clients

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

License

MIT — see LICENSE.