Skip to main content

allratestoday

PyPI version Tests license Python zero dependencies Security: Snyk

Real-time mid-market exchange rates for Python — 160+ currencies, conversions and history from the AllRatesToday API, with zero dependencies. Need the official rate a central bank or tax authority published instead? See allratestoday-central-bank.

🚀 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
  • ✅ Tested in CI — the test suite runs on every push
  • 🔀 Multi-tenant ready — per-request API key override on every method

🔑 Get Your API Key

Get a free API key at allratestoday.com/register — no credit card. Your key, usage and plan live on the dashboard.

Plan Includes
Free latest, convert, get_rate, get_rates, symbols
Paid Everything above plus for_date, time_series, get_historical_rates and dated convert — see pricing

AI agents can self-issue a 100-call, 7-day trial key with no signup — see the AI agent section below.

📦 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.891067, "GBP": 0.749934, "JPY": 158.2}

# 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.12225, "GBP": 0.8416, "JPY": 177.53}

Response:

{
    "base": "EUR",
    "date": "2026-10-19T11:46:01+0000",
    "rates": {"USD": 1.12225, "GBP": 0.8416, "JPY": 177.53}
}

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": 891.067, "rate": 0.891067}

# 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": "US Dollar",
#     "EUR": "Euro",
#     "GBP": "British Pound",
#     "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']}")
# {"from": {"currency": "USD", "amount": 500}, "to": {"currency": "EUR", "amount": 445.5335},
#  "rate": 0.891067, "source": "mid-market"}

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:
    data = client.for_date("2026-01-15", symbols=["EUR"])
except AllRatesTodayError as e:
    print(e)         # "Historical rates require a paid plan. ..."
    print(e.status)  # 403
Status Meaning
— Missing API key, bad date or missing symbols (raised before any request)
400 Unknown currency code
401 Invalid API key
403 Your plan does not include this call (history needs a paid plan)
429 Quota or rate limit reached
500 Server error

💡 Quota tips

  • Each method call is one request against your quota; latest(symbols=[...]) returns several currencies in one call, so prefer it to looping get_rate.
  • for_date() and time_series() make one request per symbol.
  • Rates refresh every 60 seconds — caching responses for a minute loses nothing.

🏛️ Official central-bank rates

Mid-market rates are right for pricing and display. Tax filings, customs, statutory accounts and many invoicing rules instead require the rate a named institution published. For those, use allratestoday-central-bank — 130+ central banks and tax authorities, latest tables with no API key:

from allratestoday_central_bank import CentralBankRates

cb = CentralBankRates()
print(cb.latest("ecb", source="EUR", target="USD"))  # the ECB's own published rate and its rate_date

Need the whole archive rather than an API call? The published central-bank tables are mirrored daily as open data, one CSV per institution: Hugging Face · Kaggle (CC BY-NC 4.0).

🏦 Commercial bank board rates

For the retail buy and sell rates a commercial bank displays on its own website (SBI's TT buying rate, an Emirates NBD or HSBC Hong Kong board), use bank_rates(). It covers 1,200+ commercial banks in 120+ countries, read hourly, and needs an API key (the free key works). These are bank prices, not official rates.

client = AllRatesToday(api_key="YOUR_API_KEY")

india = client.bank_rates("in")                          # every covered bank in India
sbi = client.bank_rates("in", "sbi", ccy="USD")          # one bank, one currency
print(sbi["bank_updated_at"], sbi["buy"], sbi["sell"])
past = client.bank_rates("in", "sbi", ccy="USD", date="2026-10-15")  # stored board for a past day

Countries and bank codes are on the commercial bank rates page.


📖 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)
bank_rates(country, bank, ccy, date, api_key) Retail buy/sell board rates from commercial banks (API key)

📦 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.11

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.11
File Size Uploaded Provenance Actions
allratestoday-1.3.11.tar.gz 20.0 kB Without provenance Details for allratestoday-1.3.11.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for allratestoday 1.3.11
File Interpreter ABI Platform Actions
allratestoday-1.3.11-py3-none-any.whl Python 3 none any Details for allratestoday-1.3.11-py3-none-any.whl

Total release size: 32.8 kB

Release files / allratestoday-1.3.11.tar.gz

Download URL allratestoday-1.3.11.tar.gz
Size 20.0 kB
Tags Source
SHA-256 checksum
How to use checksums
7b5ef2abfc2dfaf01732ca70caf9290ed5447ac94d27e02027331fb102ba193f
BLAKE2b-256 checksum
How to use checksums
9097abd32ed93c04ecac16a786c564b145f829aba45dad4ab694a21c1a80ad1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / allratestoday-1.3.11-py3-none-any.whl

Download URL allratestoday-1.3.11-py3-none-any.whl
Size 12.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5693b217a931ce77459ce3bbb20f439800b531ea1c208221c4fa049d2d741605
BLAKE2b-256 checksum
How to use checksums
215a1f5fc8c6e55d043083184a091abc1e916c23da5d801d26ffdd717ed56090
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for allratestoday 1.3.11

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