Initial release v1.0.0

Exchange Rate API SDK — real-time mid-market currency exchange rates
for 160+ currencies. Rebranded for exchange-rateapi.com.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cahthuranag

.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+dist/
+*.egg-info/
+.venv/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Exchange Rate API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,319 @@
+# exchangerateapi
+
+[![PyPI version](https://img.shields.io/pypi/v/exchangerateapi.svg)](https://pypi.org/project/exchangerateapi/)
+[![license](https://img.shields.io/pypi/l/exchangerateapi.svg)](https://github.com/Exchange-RateAPI/exchange-rateapi-python/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/exchangerateapi.svg)](https://pypi.org/project/exchangerateapi/)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://pypi.org/project/exchangerateapi/)
+
+**The most elegant way to access real-time mid-market exchange rates in Python**
+
+## Why Choose This Client?
+
+- **Lightning Fast** -- Zero dependencies, pure Python standard library
+- **Real-Time Data** -- Rates updated every 60 seconds from Reuters (Refinitiv) and interbank feeds
+- **Mid-Market Rates** -- The true interbank rate -- no hidden spread or markup
+- **160+ Currencies** -- Major, minor, and exotic currency pairs
+- **Type Hints** -- Full type annotations for IDE autocomplete
+- **Zero Dependencies** -- Uses only `urllib` and `json` from the standard library
+
+## Get Your API Key
+
+Ready to start? Get your free API key from [exchange-rateapi.com/register](https://exchange-rateapi.com/register).
+
+## Installation
+
+```bash
+pip install exchangerateapi
+```
+
+## Quick Start
+
+Get up and running in seconds:
+
+```python
+from exchangerateapi import ExchangeRateAPI
+
+# Set your API key
+client = ExchangeRateAPI(api_key="era_live_YOUR_API_KEY")
+
+# Get latest exchange rates
+data = client.latest(base="USD", symbols=["EUR", "GBP", "JPY"])
+print(data["rates"])  # {"EUR": 0.9234, "GBP": 0.7891, "JPY": 151.42}
+
+# Convert an amount
+result = client.convert("USD", "EUR", 1000)
+print(f"$1,000 = EUR {result['result']}")
+```
+
+## API Reference
+
+- [Latest Rates](#latest-exchange-rates) -- Get current exchange rates
+- [Historical Data](#historical-exchange-rates) -- Fetch rates for specific dates
+- [Currency Conversion](#currency-conversion) -- Convert between currencies
+- [Time Series](#time-series-data) -- Get rates over date ranges
+- [Available Currencies](#available-currencies) -- List all supported currencies
+- [Single Rate](#single-rate) -- Get one currency pair
+- [Historical by Period](#historical-rates-by-period) -- Preset period lookups
+
+---
+
+### Latest Exchange Rates
+
+Get the most current exchange rates with a single call:
+
+```python
+# All rates from USD (default base)
+data = client.latest()
+print(data["rates"])
+
+# Target specific currencies with EUR base
+data = client.latest(base="EUR", symbols=["USD", "GBP", "JPY"])
+print(data["rates"])
+# {"USD": 1.083, "GBP": 0.8546, "JPY": 163.92}
+```
+
+**Response:**
+
+```python
+{
+    "base": "EUR",
+    "date": "2026-04-09T14:30:00Z",
+    "rates": {"USD": 1.083, "GBP": 0.8546, "JPY": 163.92}
+}
+```
+
+---
+
+### Historical Exchange Rates
+
+Travel back in time to get rates from any date:
+
+```python
+# Using a string date
+data = client.for_date("2026-01-15", base="USD", symbols=["EUR"])
+print(data["rates"])  # {"EUR": 0.9187}
+
+# Using a date object
+from datetime import date
+data = client.for_date(date(2026, 1, 15), base="EUR", symbols=["USD", "GBP"])
+
+# Using a datetime object
+from datetime import datetime
+data = client.for_date(datetime(2026, 1, 15, 12, 0, 0))
+```
+
+**Response:**
+
+```python
+{
+    "base": "USD",
+    "date": "2026-01-15",
+    "rates": {"EUR": 0.9187}
+}
+```
+
+---
+
+### Currency Conversion
+
+Convert any amount between currencies -- including historical conversions:
+
+```python
+# Current conversion
+result = client.convert("USD", "EUR", 1000)
+print(result)
+# {"from": "USD", "to": "EUR", "amount": 1000, "result": 923.4, "rate": 0.9234}
+
+# Historical conversion -- what was $1,000 worth on Jan 15?
+result = client.convert("USD", "EUR", 1000, date="2026-01-15")
+print(f"Rate on Jan 15: {result['rate']}")
+# {"from": "USD", "to": "EUR", "amount": 1000, "result": 918.7, "rate": 0.9187, "date": "2026-01-15"}
+
+# Using a date object
+from datetime import date
+result = client.convert("GBP", "JPY", 500, date=date(2025, 12, 31))
+```
+
+---
+
+### Available Currencies
+
+Discover all 160+ supported currency symbols and names:
+
+```python
+data = client.symbols()
+print(data["symbols"])
+# {
+#     "USD": "United States Dollar",
+#     "EUR": "Euro",
+#     "GBP": "British Pound Sterling",
+#     "JPY": "Japanese Yen",
+#     ...160+ currencies
+# }
+
+# Build a currency list
+for code, name in data["symbols"].items():
+    print(f"{code}: {name}")
+```
+
+---
+
+### Time Series Data
+
+Get exchange rates over a date range for trend analysis and charting:
+
+```python
+data = client.time_series(
+    "2026-01-01", "2026-03-31",
+    base="USD",
+    symbols=["EUR", "GBP"],
+)
+print(data["rates"]["2026-01-15"])
+# {"EUR": 0.9187, "GBP": 0.7834}
+
+# Using date objects
+from datetime import date
+data = client.time_series(
+    date(2026, 1, 1), date(2026, 3, 31),
+    symbols=["EUR"],
+)
+```
+
+**Response:**
+
+```python
+{
+    "base": "USD",
+    "start_date": "2026-01-01",
+    "end_date": "2026-03-31",
+    "rates": {
+        "2026-01-01": {"EUR": 0.9187, "GBP": 0.7834},
+        "2026-01-02": {"EUR": 0.9195, "GBP": 0.7841},
+        ...
+    }
+}
+```
+
+---
+
+### Single Rate
+
+Get a single exchange rate between two currencies:
+
+```python
+rate = client.get_rate("USD", "EUR")
+print(f"1 USD = {rate['rate']} EUR")
+
+# With amount
+rate = client.get_rate("USD", "EUR", 500)
+print(f"$500 = EUR {rate['to']['amount']}")
+```
+
+---
+
+### Historical Rates by Period
+
+Get historical rates using preset periods -- no date math needed:
+
+```python
+history = client.get_historical_rates("USD", "EUR", "30d")
+print(f"Current: {history['current']['rate']}")
+for point in history["rates"]:
+    print(f"{point['time']}: {point['rate']}")
+```
+
+**Available periods:** `1d`, `7d`, `30d`, `1y` (default: `7d`)
+
+---
+
+## Configuration
+
+```python
+client = ExchangeRateAPI(
+    api_key="era_live_YOUR_API_KEY",               # Required
+    base_url="https://exchange-rateapi.com",       # Optional
+    timeout=10,                                     # Optional (seconds)
+)
+```
+
+| Parameter  | Type  | Default                        | Description                     |
+| ---------- | ----- | ------------------------------ | ------------------------------- |
+| `api_key`  | `str` | --                             | Your API key                    |
+| `base_url` | `str` | `https://exchange-rateapi.com` | API base URL                    |
+| `timeout`  | `int` | `10`                           | Request timeout in seconds      |
+
+---
+
+## Per-Request API Key Override
+
+Every method supports a per-request API key override -- useful for multi-tenant apps:
+
+```python
+client = ExchangeRateAPI(api_key="default_key")
+
+# Override for a specific request
+data = client.latest(api_key="other_users_key")
+result = client.convert("USD", "EUR", 100, api_key="tenant_key")
+symbols = client.symbols(api_key="another_key")
+```
+
+---
+
+## Error Handling
+
+All errors are raised as `ExchangeRateAPIError` with an optional HTTP status code:
+
+```python
+from exchangerateapi import ExchangeRateAPI, ExchangeRateAPIError
+
+client = ExchangeRateAPI(api_key="era_live_YOUR_API_KEY")
+
+try:
+    rate = client.get_rate("USD", "INVALID")
+except ExchangeRateAPIError as e:
+    print(e)        # "Currency not found"
+    print(e.status)  # 404
+```
+
+| Status | Meaning                                |
+| ------ | -------------------------------------- |
+| --     | Missing API key (raised before request) |
+| `401`  | Invalid API key                        |
+| `404`  | Currency code not found                |
+| `429`  | Rate limit exceeded                    |
+| `500`  | Server error                           |
+
+---
+
+## Methods Reference
+
+| Method                                              | Description                                                |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| `latest(base, symbols, api_key)`                    | Get latest rates for one or more currencies                |
+| `for_date(date, base, symbols, api_key)`            | Get rates for a specific historical date                   |
+| `convert(from, to, amount, date, api_key)`          | Convert amount (supports historical date)                  |
+| `time_series(start, end, base, symbols, api_key)`   | Get rates across a custom date range                       |
+| `symbols(api_key)`                                  | List all 160+ supported currency codes and names           |
+| `get_rate(from, to, amount, api_key)`               | Get a single exchange rate                                 |
+| `get_rates(source, target, api_key)`                | Get rates with full metadata                               |
+| `get_historical_rates(source, target, period, api_key)` | Historical rates by preset period (1d/7d/30d/1y)      |
+
+---
+
+## Zero Dependencies
+
+This SDK uses only Python standard library (`urllib`, `json`). No external packages required. Nothing to audit, nothing to break.
+
+---
+
+## Links
+
+- [API Documentation](https://exchange-rateapi.com/developers)
+- [Register (Free)](https://exchange-rateapi.com/register)
+- [Dashboard](https://exchange-rateapi.com/profile)
+- [Status](https://exchange-rateapi.com/status)
+- [GitHub](https://github.com/Exchange-RateAPI/exchange-rateapi-python)
+
+## License
+
+MIT