Metadata-Version: 2.4
Name: fxrateapi
Version: 0.1.0
Summary: Official Python SDK for fxrateapi.com — exchange rates, currency conversion, and time series data
Project-URL: Homepage, https://fxrateapi.com
Project-URL: Documentation, https://docs.fxrateapi.com
Project-URL: Repository, https://github.com/fxrateapi/fxrateapi
Author-email: fxrateapi <support@fxrateapi.com>
License: MIT
Keywords: currency,exchange-rate,forex,fxrateapi,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# fxrateapi

Official Python SDK for [fxrateapi.com](https://fxrateapi.com) — exchange rates, currency conversion, and time series data from ECB, FRED, and OXR.

## Installation

```bash
pip install fxrateapi
```

## Quick start

```python
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

```python
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

```python
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](https://docs.fxrateapi.com) for full API documentation.

## License

MIT
