Metadata-Version: 2.4
Name: xratesapi
Version: 0.1.0
Summary: Official Python SDK for the XRates exchange rate API.
Project-URL: Homepage, https://xratesapi.com
Project-URL: Source, https://github.com/xratesapi/python-sdk
Project-URL: Issues, https://github.com/xratesapi/python-sdk/issues
Author-email: XRates Team <support@xratesapi.com>
License: MIT
License-File: LICENSE
Keywords: currency,exchange-rate,forex,fx,xrates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# xratesapi

Official Python SDK for the [XRates exchange rate API](https://xratesapi.com).

Python 3.9+, built on [httpx](https://www.python-httpx.org/).

## Install

```bash
pip install xratesapi
```

## Quick start

```python
from xratesapi import Client

client = Client("YOUR_API_KEY")

print(client.latest(base="USD", symbols=["EUR", "GBP"]))
print(client.convert("USD", "EUR", 100))
```

The client is also a context manager:

```python
with Client("YOUR_API_KEY") as client:
    rates = client.latest()
```

## Methods

| Method | Endpoint |
| --- | --- |
| `latest(base="USD", symbols=None)` | `GET /api/v1/latest` |
| `historical(date, base="USD", symbols=None)` | `GET /api/v1/{YYYY-MM-DD}` |
| `convert(from_, to, amount, date=None)` | `GET /api/v1/convert` |
| `timeseries(start_date, end_date, base="USD", symbols=None)` | `GET /api/v1/timeseries` |
| `fluctuation(start_date, end_date, base="USD", symbols=None)` | `GET /api/v1/fluctuation` |
| `currencies()` | `GET /api/v1/currencies` |
| `status()` | `GET /api/v1/status` |

## Error handling

```python
from xratesapi import (
    Client,
    ApiError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

try:
    client.latest(base="XXX")
except AuthenticationError:
    ...  # 401 / 403
except RateLimitError:
    ...  # 429 — back off
except ValidationError as e:
    print(e.payload)  # raw response body
except ApiError as e:
    print(e.status, e)
```

## Configuration

```python
import httpx
from xratesapi import Client

# Custom timeout / base URL
client = Client("KEY", base_url="https://xratesapi.com", timeout=30.0)

# Or inject your own httpx.Client (retries, proxies, transport, ...)
http = httpx.Client(timeout=30.0, transport=httpx.HTTPTransport(retries=3))
client = Client("KEY", http_client=http)
```

## License

MIT
