fxrateapi 0.1.0

Official Python SDK for fxrateapi.com — exchange rates, currency conversion, and time series data

fxrateapi

Official Python SDK for fxrateapi.com — exchange rates, currency conversion, and time series data from ECB, FRED, and OXR.

Installation

pip install fxrateapi

Quick start

from fxrateapi import FxRateApiClient

client = FxRateApiClient(api_key="fxr_your_key_here")

# Latest rates
rates = client.latest(base="USD", symbols=["EUR", "GBP", "JPY"])
print(rates.rates["EUR"])  # 0.847

# Convert 1000 USD → EUR
result = client.convert(from_currency="USD", to="EUR", amount=1000)
print(result.result)  # 847.4

# Historical (immutable, cache forever)
hist = client.historical("2020-03-16", base="USD")

# Time series (max 366 days)
ts = client.timeseries(start="2024-01-01", end="2024-03-31", symbols=["EUR"])
for date, day_rates in ts.rates.items():
    print(date, day_rates.get("EUR"))

Async usage

import asyncio
from fxrateapi import AsyncFxRateApiClient

async def main():
    async with AsyncFxRateApiClient(api_key="fxr_your_key_here") as client:
        # Fetch concurrently
        latest, usage = await asyncio.gather(
            client.latest(base="USD", symbols=["EUR", "GBP"]),
            client.usage(),
        )
        print(latest.rates["EUR"])
        print(f"{usage.requests.used}/{usage.requests.limit} requests used")

asyncio.run(main())

Error handling

from fxrateapi import FxRateApiClient
from fxrateapi.exceptions import FxRateApiResponseError, FxRateApiTimeoutError

client = FxRateApiClient(api_key="fxr_your_key_here")

try:
    client.latest(base="INVALID")
except FxRateApiResponseError as e:
    print(e.status)     # 422
    print(e.code)       # "fx_invalid_symbol"
    print(e.why)        # human-readable reason
    print(e.how_to_fix) # suggestion
except FxRateApiTimeoutError as e:
    print(f"Timed out after {e.timeout}s")

API reference

See docs.fxrateapi.com for full API documentation.

License

MIT