# stapel-currencies 0.1.8

Currencies and exchange rates: a Currency catalog keyed by ISO 4217 code with Decimal rates relative to a configurable base currency, cross-rate conversion (convert()) exposed as a comm Function, a pluggable rate-provider seam (ECB by default), a public read-only HTTP API, and a Celery task / management commands to refresh rates.

Contract: axes 2 · extension points 2.
Generated from docs/capabilities.json by `stapel-llms-txt` — do not edit; drift-gated by `make contract-check`.

## Configuration axes — what a product switches on
Settings keys; `default` is what you get by saying nothing. Turning an axis off unmounts the operations it gates.
- BASE_CURRENCY [enum, default "USD"] — Base currency for exchange rates
  ISO 4217 code every Currency.value rate is relative to. The base currency always converts at rate 1. Changing it reinterprets stored rates — re-run update_exchange_rates after switching (conf.py, MODULE.md Extension points table).
- CONVERSION_DECIMAL_PLACES [enum, default 2] — Conversion result precision
  Decimal places conversion results are quantized to (ROUND_HALF_UP) in services.convert and the currencies.convert Function (conf.py, MODULE.md).

## Extension points — what a product replaces, fork-free
- DEFAULT_CURRENCIES [catalog_override]
  Seed list read by the load_default_currencies management command (code/display_name/symbol/value dicts); replaces the default 16-currency list wholesale (conf.py, MODULE.md).
- RATE_PROVIDER [dotted_path]
  REPLACE, single strategy: implement the RateProvider ABC (providers.py) and point the setting at it — default ECBRateProvider (ECB eurofxref-daily.xml, rebased when base != EUR); enforced as a RateProvider subclass by get_rate_provider() (conf.py, MODULE.md 'Rate providers').

## Fits with — fleet dependencies
- stapel-core (required) — AppSettings config layer, comm Function (currencies.convert), error registry — the only stapel-* dependency (pyproject.toml: 'Depends on stapel-core only'; conf.py:11, functions.py:19, errors.py:6)
