Metadata-Version: 2.4
Name: rate-api-python
Version: 1.0.3
Summary: Official Python client for the Rate-API.com exchange-rate & crypto API
Author-email: Vilgar <digitalbrainsam@gmail.com>
License: MIT
Project-URL: Homepage, https://rate-api.com
Project-URL: Documentation, https://rate-api.com/en/docs
Project-URL: Repository, https://github.com/Vilgar/rate-api.com
Project-URL: Issues, https://rate-api.com/en/docs
Keywords: exchange-rate,currency,forex,crypto,api,rate-api
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# rate-api-python

Official Python client for [Rate-API.com](https://rate-api.com). Standard library only — no dependencies. Python 3.8+.

## Install

```bash
pip install rate-api-python
```

## Usage

```python
from rate_api import RateApiClient, RateApiError

client = RateApiClient("YOUR_API_KEY")

rates = client.latest("USD", ["EUR", "GBP"])
print(rates["rates"]["EUR"])

client.convert("USD", "EUR", 100)                 # Pro+
client.historical("2026-01-15", "USD", ["EUR"])   # Pro+
client.pair("USD", "EUR")                          # single pair
client.crypto(["BTC", "ETH"])                      # Pro+
client.currencies()                                # supported currencies
client.usage()                                     # current-month usage vs quota
client.health()                                    # public

try:
    client.convert("USD", "ZZZ", 100)
except RateApiError as e:
    print(e, e.status)   # "Invalid target currency" 400
```

## Methods

`latest` · `convert` · `pair` · `historical` · `crypto` · `currencies` · `usage` · `quota` · `health`

## Errors

Every failure raises `RateApiError` (or a subclass), so a single `except RateApiError` catches everything:

```python
import time
from rate_api import RateApiClient, RateApiError, RateLimitError, RateApiTimeoutError

try:
    client.latest("USD", ["EUR"])
except RateLimitError as e:
    time.sleep(e.retry_after)                  # honour the server's backoff
except RateApiTimeoutError:
    ...                                        # request exceeded `timeout`
except RateApiError as e:
    print(e, e.status, e.type, e.request_id)
```

| Class | When | Extra attributes |
|---|---|---|
| `RateApiError` | any API/HTTP error | `status` (HTTP code; `None` on network/timeout), `type` (stable `error.type` slug), `request_id` (`X-Request-Id` — quote it when contacting support) |
| `RateLimitError` | HTTP 429 | `retry_after` (seconds to wait) |
| `RateApiTimeoutError` | request exceeded `timeout` | — |

## Configuration

```python
RateApiClient(api_key, base_url="https://rate-api.com/api/v1", timeout=15, max_retries=2)
```

| Argument | Default | Notes |
|---|---|---|
| `base_url` | `https://rate-api.com/api/v1` | pass `…/api/v2` to target v2 directly |
| `timeout` | `15` | per-request socket timeout in seconds (covers headers and body) |
| `max_retries` | `2` | automatically retries 429/503/network/timeout with exponential backoff, honouring the server's `Retry-After` header |

## License

MIT
