allratestoday
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
- 💹 Mid-Market Rates — No retail spread or markup baked in
- 🌍 160+ Currencies — Major, minor, and exotic currency pairs
- 🔷 Type Hints — Full type annotations for IDE autocomplete
- 📦 Zero Dependencies — Uses only
urllibandjsonfrom the standard library - ✅ 100% Test Coverage — Comprehensive test suite with full coverage
🔑 Get Your API Key
Ready to start? Get your free API key from allratestoday.com/register.
📦 Installation
pip install allratestoday
🏁 Quick Start
Get up and running in seconds:
from allratestoday import AllRatesToday
# Set your API key
client = AllRatesToday(api_key="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 = €{result['result']}")
📚 API Reference
- Latest Rates — Get current exchange rates
- Historical Data — Fetch rates for specific dates
- Currency Conversion — Convert between currencies
- Time Series — Get rates over date ranges
- Available Currencies — List all supported currencies
- Single Rate — Get one currency pair
- Historical by Period — Preset period lookups
Latest Exchange Rates
Get the most current exchange rates with a single call:
# 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:
{
"base": "EUR",
"date": "2026-04-09T14:30:00Z",
"rates": {"USD": 1.083, "GBP": 0.8546, "JPY": 163.92}
}
Historical Exchange Rates
Get rates for any date in the last 365 days (paid plans; free and trial keys get a 403 historical_requires_paid_plan):
# 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), symbols=["EUR"])
for_date() and time_series() need symbols (one request per symbol) and cover the last 365 days.
Response:
{
"base": "USD",
"date": "2026-01-15",
"rates": {"EUR": 0.9187}
}
Currency Conversion
Convert any amount between currencies — including historical conversions (paid plans):
# 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:
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 (paid plans):
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:
{
"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:
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 = €{rate['to']['amount']}")
Historical Rates by Period
Get historical rates using preset periods — no date math needed (paid plans):
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
client = AllRatesToday(
api_key="YOUR_API_KEY", # Required
base_url="https://allratestoday.com", # Optional
timeout=10, # Optional (seconds)
)
| Parameter | Type | Default | Description |
|---|---|---|---|
api_key |
str |
— | Your API key |
base_url |
str |
https://allratestoday.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:
client = AllRatesToday(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 AllRatesTodayError with an optional HTTP status code:
from allratestoday import AllRatesToday, AllRatesTodayError
client = AllRatesToday(api_key="YOUR_API_KEY")
try:
rate = client.get_rate("USD", "INVALID")
except AllRatesTodayError 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 |
🧪 Testing
Run tests:
pip install pytest pytest-cov
pytest tests/ -v
Run with coverage:
pytest tests/ --cov=allratestoday --cov-report=term-missing
📖 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 (paid plan) |
convert(from, to, amount, date, api_key) |
Convert amount (historical date needs a paid plan) |
time_series(start, end, base, symbols, api_key) |
Get rates across a custom date range (paid plan) |
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; paid plan) |
📦 Zero Dependencies
This SDK uses only Python standard library (urllib, json). No external packages required. Nothing to audit, nothing to break.
🤖 Use it from an AI agent
The same rates are available to coding agents and LLM tools without a second integration:
- Claude Code plugin (no key):
/plugin marketplace add AllRates-Today/claude-code-pluginthen/plugin install allratestoday@allratestoday - Hosted MCP endpoint:
https://allratestoday.com/api/mcp— Streamable HTTP, keyless, nothing to install - Local MCP servers:
npx -y @allratestoday/mcp-server(live mid-market rates) ·npx -y @allratestoday/central-bank-mcp(official central-bank rates) - Trial key for agents, no signup:
POST https://allratestoday.com/api/agent/keys(sendContent-Type: application/json) returns a 100-call key valid 7 days for latest rates and latest central-bank tables (history and dated tables are paid-plan only); both MCP servers expose it asrequest_trial_key - Daily Reference Rate (first published 2026-10-12): one fixed USD table per business day, the 16:00 London median of minute samples, never revised — keyless at
https://allratestoday.com/api/open/reference-rate,get_reference_ratein the MCP server - Machine-readable site guide: llms.txt
🔗 Links
📜 License
MIT
Metadata
Release files for allratestoday 1.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| allratestoday-1.3.6.tar.gz | 16.9 kB | Without provenance | Details for allratestoday-1.3.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| allratestoday-1.3.6-py3-none-any.whl | Python 3 | none | any | Details for allratestoday-1.3.6-py3-none-any.whl |
Total release size: 27.9 kB
Release files / allratestoday-1.3.6.tar.gz
| Download URL | allratestoday-1.3.6.tar.gz |
|---|---|
| Size | 16.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e12e8a8c990cbf0062d66232e5a6909a460f4fc9eed49e7d0080d38559a99fef
|
|
BLAKE2b-256 checksum How to use checksums |
8f2f1c17d8ebd3560f94cfd2fbe0840d0613e5e3763487f719e10f98ace3dbdb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / allratestoday-1.3.6-py3-none-any.whl
| Download URL | allratestoday-1.3.6-py3-none-any.whl |
|---|---|
| Size | 11.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a1a9c36aa10b45088c92c40868752be43510a7f970bae91c793864e7293991d
|
|
BLAKE2b-256 checksum How to use checksums |
d3f0f9a1f441d8d0751b75f1757b4d185121497fc504f1ec90d12e7f35c8f3e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for allratestoday 1.3.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.