ecbfx

A minimal command-line tool and Python library for fetching EUR foreign exchange rates directly from the ECB SDMX API.

Install

pip install ecbfx

Working on ecbfx:

git clone https://github.com/edvinassvedas-dev/ecbfx.git
cd ecbfx && pip install -e ".[dev]"
pytest

CLI usage

# Today's rate for USD (indirect: USD per 1 EUR — ECB native)
# Note: ECB publishes rates ~16:00 CET on trading days.
# If today's rate isn't available yet, use --latest instead.
ecbfx USD

# Specific date, and multiple currencies at once
ecbfx USD 2025-01-15
ecbfx USD GBP CHF 2025-01-15

# Date range
ecbfx USD GBP --from 2025-01-01 --to 2025-03-31

# Direct convention: EUR per 1 foreign unit (inverted)
ecbfx USD 2025-01-15 --direct

# Most recent available rate (ignores today being a weekend/holiday)
ecbfx USD --latest

# Single value only — ideal for shell scripting
RATE=$(ecbfx USD --quiet)

# CSV output (pipe-friendly)
ecbfx USD --from 2025-01-01 --to 2025-01-31 --csv > rates.csv

# Read (date, currency) pairs from a file or stdin — one HTTP call per currency
ecbfx --pairs transactions.csv --direct --csv
cat transactions.csv | ecbfx --pairs - --direct --csv

Convention

ECB publishes indirect natively. --direct inverts the rate. The convention column in CSV output (USD/EUR or EUR/USD) makes the direction explicit for downstream pipelines.

Flags reference

Weekend and holiday gap-filling

ECB only publishes rates on trading days. By default, ecbfx automatically uses the most recent prior trading day's rate (Last Observation Carried Forward) when a requested date falls on a weekend or public holiday — including the first date in a range that starts on a holiday such as January 1st.

A future date is never substituted, so a rate is never influenced by information that did not exist on the date requested. If no trading day exists within 5 calendar days before the target — the widest real gap in the ECB calendar — the lookup fails rather than reaching further back for a staler rate.

Use --no-gap-fill to disable substitution entirely and receive an explicit error instead — useful in audit workflows where a substituted rate is not acceptable.

Exit codes

Useful for scripting:

ecbfx USD --quiet || echo "fetch failed, exit $?"

Python API

from datetime import date
from ecbfx import fetch_rates, fetch_rates_for_pairs, fetch_latest

# Indirect (default) — foreign units per 1 EUR, contiguous range
rows = fetch_rates(["USD", "GBP"], date(2025, 1, 1), date(2025, 1, 31))

# Direct — EUR per 1 foreign unit
rows = fetch_rates(["USD"], date(2025, 1, 15), date(2025, 1, 15), direct=True)

# Most recent available rate
rows = fetch_latest(["USD", "CHF"])

# Sparse transaction dates — one HTTP call per currency regardless of pair count
pairs = [
    (date(2025, 1, 15), "USD"),
    (date(2025, 1, 20), "GBP"),
    (date(2025, 2,  3), "USD"),
]
rows = fetch_rates_for_pairs(pairs, direct=True)

# Strict mode — raises ECBError on weekends/holidays instead of substituting
rows = fetch_rates(["USD"], date(2025, 1, 13), date(2025, 1, 13), gap_fill=False)

for r in rows:
    print(r["date"], r["currency"], r["convention"], r["rate"])

Both fetch functions accept direct, decimals, gap_fill, timeout and an optional session for connection reuse.

Behaviour worth knowing

• fetch_rates is all-or-nothing across currencies. A malformed code raises before any request. A well-formed code the ECB will not serve raises partway through: rows already fetched are discarded and later currencies are never requested. Call once per currency if you need per-currency isolation.
• Duplicate currencies collapse. ["USD", "usd"] is one HTTP call and one row per date.
• Output order differs between the two functions — see the table below.

Input validation

from ecbfx import validate_currency, ECBError

# Normalises and validates a currency code — raises ECBError if invalid
print(validate_currency("usd"))    # → "USD"
print(validate_currency("  GBP "))  # → "GBP"

try:
    validate_currency("US$")
except ECBError as e:
    print(e)
    # Invalid currency code 'US$'. Expected a 3-letter ISO 4217 code, e.g. USD, GBP, CHF.

Use ECBError in try/except blocks when calling any ecbfx function to handle API failures, network errors, or invalid inputs cleanly.

fetch_rates vs fetch_rates_for_pairs

Both make one HTTP call per currency.

Note: fetch_rates_for_pairs fetches the full span from the earliest to the latest date per currency in that single call. For very sparse data (e.g. two transactions 10 years apart) this pulls the entire intervening range; a warning is logged when the span exceeds one year.

License

MIT