Skip to main content

allratestoday

PyPI version codecov Tests license Python zero dependencies Security: Snyk

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 urllib and json from 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 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-plugin then /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 (send Content-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 as request_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_rate in the MCP server
  • Machine-readable site guide: llms.txt

📜 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)

Source distribution for allratestoday 1.3.6
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)

Table of built distributions (wheels) for allratestoday 1.3.6
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page