feat: add Currency/FX conversion support (#456)

- Add FXRateProvider ABC and StaticFXRateProvider implementation
- Wire FX rate provider and base currency into App and Context
- Add context.get_fx_rate(), convert_to_base_currency(), get_portfolio_value()
- Auto-convert multi-market portfolio values to base currency
- StaticFXRateProvider supports inverse rates and case-insensitive lookups
- Add 17 unit tests for FX models
- Add docs page for FX conversion (Advanced Concepts)

Author: MDUYN

docusaurus/docs/Advanced Concepts/fx-conversion.md

@@ -0,0 +1,181 @@
+---
+sidebar_position: 4
+---
+
+# Currency / FX Conversion
+
+When you trade across multiple markets that use different currencies, you need a way to express all position values in a single **base currency**. The framework provides a pluggable FX conversion system that handles this automatically.
+
+## Quick Start
+
+```python
+from investing_algorithm_framework import (
+    create_app, StaticFXRateProvider
+)
+
+app = create_app()
+
+# 1. Set the base currency for portfolio reporting
+app.set_base_currency("EUR")
+
+# 2. Register an FX rate provider
+app.add_fx_rate_provider(StaticFXRateProvider({
+    ("USD", "EUR"): 0.92,
+    ("GBP", "EUR"): 1.17,
+}))
+
+# 3. Add your markets as usual
+app.add_market(
+    market="binance",
+    trading_symbol="USD",
+    # ...
+)
+app.add_market(
+    market="bitvavo",
+    trading_symbol="EUR",
+    # ...
+)
+```
+
+Inside a strategy you can now call:
+
+```python
+class MyStrategy(TradingStrategy):
+    def run_strategy(self, context: Context, **kwargs):
+        # Total portfolio value across all markets, in EUR
+        total_value = context.get_portfolio_value()
+
+        # Convert a specific amount
+        usd_amount = 1000
+        eur_amount = context.convert_to_base_currency(usd_amount, "USD")
+
+        # Get a raw FX rate
+        rate = context.get_fx_rate("GBP", "EUR")
+```
+
+## Concepts
+
+### Base Currency
+
+The base currency is the single currency in which the total portfolio value is reported. Set it once on the app:
+
+```python
+app.set_base_currency("EUR")
+```
+
+If no base currency is set, `context.get_portfolio_value()` returns the value of the first portfolio in its own trading currency — no conversion takes place.
+
+### FX Rate Provider
+
+An FX rate provider is any class that implements `FXRateProvider`:
+
+```python
+from investing_algorithm_framework import FXRateProvider
+
+class FXRateProvider(ABC):
+    def get_rate(
+        self,
+        from_currency: str,
+        to_currency: str,
+        date: datetime = None
+    ) -> float:
+        """Return rate such that amount_in_to = amount_in_from * rate."""
+        ...
+```
+
+The `date` parameter is passed automatically during backtesting (the current simulation date) and during live trading (`datetime.now()`). This lets you build providers that look up historical rates for accurate backtesting.
+
+### StaticFXRateProvider
+
+A built-in provider for fixed rates. Inverse rates are computed automatically.
+
+```python
+from investing_algorithm_framework import StaticFXRateProvider
+
+provider = StaticFXRateProvider({
+    ("USD", "EUR"): 0.92,
+    ("GBP", "EUR"): 1.17,
+})
+
+# Direct rate
+provider.get_rate("USD", "EUR")  # 0.92
+
+# Inverse is automatic
+provider.get_rate("EUR", "USD")  # ~1.087
+
+# Same currency always returns 1.0
+provider.get_rate("EUR", "EUR")  # 1.0
+```
+
+You can also add rates dynamically:
+
+```python
+provider.add_rate("JPY", "EUR", 0.0062)
+```
+
+## Building a Custom FX Rate Provider
+
+For production use you'll want live or historical rates. Implement `FXRateProvider` and fetch rates from your preferred source:
+
+```python
+import requests
+from investing_algorithm_framework import FXRateProvider
+
+
+class LiveFXRateProvider(FXRateProvider):
+    """Fetch rates from an external API."""
+
+    def __init__(self, api_key: str):
+        self._api_key = api_key
+        self._cache = {}
+
+    def get_rate(self, from_currency, to_currency, date=None):
+        if from_currency == to_currency:
+            return 1.0
+
+        pair = f"{from_currency}/{to_currency}"
+
+        if pair not in self._cache:
+            # Replace with your actual API call
+            resp = requests.get(
+                f"https://api.example.com/fx/{pair}",
+                headers={"Authorization": f"Bearer {self._api_key}"}
+            )
+            resp.raise_for_status()
+            self._cache[pair] = resp.json()["rate"]
+
+        return self._cache[pair]
+
+
+app.add_fx_rate_provider(LiveFXRateProvider(api_key="..."))
+```
+
+## Context Methods
+
+| Method | Description |
+|--------|-------------|
+| `context.get_fx_rate(from_currency, to_currency)` | Get the exchange rate between two currencies |
+| `context.convert_to_base_currency(amount, from_currency)` | Convert an amount to the base currency |
+| `context.get_portfolio_value()` | Total portfolio value across all markets in the base currency |
+
+## How It Works
+
+When `context.get_portfolio_value()` is called:
+
+1. For each portfolio (market), the framework computes the **local value** — the sum of all position values denominated in that portfolio's `trading_symbol`.
+2. If a `base_currency` and `FXRateProvider` are registered, the local value is converted to the base currency using `fx_rate_provider.get_rate(trading_symbol, base_currency)`.
+3. All converted values are summed to produce the total portfolio value.
+
+```
+Portfolio "binance" (USD)          Portfolio "bitvavo" (EUR)
+  BTC: 0.5 × $60,000 = $30,000      ETH: 2 × €3,000 = €6,000
+  + USDT: $5,000                     + EUR cash: €1,000
+  = $35,000                          = €7,000
+         │                                  │
+         │  × 0.92 (USD→EUR)               │  × 1.0 (same currency)
+         ▼                                  ▼
+      €32,200                           €7,000
+                  ╲                    ╱
+                    ╲                ╱
+                  Total = €39,200
+```

docusaurus/sidebars.js

@@ -81,6 +81,10 @@ const sidebars = {
                     type: 'doc',
                     id: 'Advanced Concepts/blotter',
                 },
+                {
+                    type: 'doc',
+                    id: 'Advanced Concepts/fx-conversion',
+                },
                 {
                     type: 'doc',
                     id: 'Advanced Concepts/custom-data-providers',

investing_algorithm_framework/__init__.py

@@ -29,7 +29,8 @@
     SlippageModel, NoSlippage, PercentageSlippage, FixedSlippage, \
     VolumeImpactSlippage, \
     CommissionModel, NoCommission, PercentageCommission, FixedCommission, \
-    FillModel, FullFill, VolumeBasedFill
+    FillModel, FullFill, VolumeBasedFill, \
+    FXRateProvider, StaticFXRateProvider
 from .infrastructure import AzureBlobStorageStateHandler, \
     CSVOHLCVDataProvider, CSVTickerDataProvider, CSVURLDataProvider, \
     JSONURLDataProvider, ParquetURLDataProvider, \
@@ -251,4 +252,6 @@
     "FillModel",
     "FullFill",
     "VolumeBasedFill",
+    "FXRateProvider",
+    "StaticFXRateProvider",
 ]

investing_algorithm_framework/app/app.py

@@ -72,6 +72,8 @@ def __init__(self, state_handler=None, name=None):
         self._run_history = None
         self._name = name
         self._blotter = None
+        self._fx_rate_provider = None
+        self._base_currency = None
 
     @property
     def context(self):
@@ -81,6 +83,8 @@ def context(self):
         ctx = self.container.context()
         ctx._blotter = self._blotter \
             if self._blotter is not None else DefaultBlotter()
+        ctx._fx_rate_provider = self._fx_rate_provider
+        ctx._base_currency = self._base_currency
 
         return ctx
 
@@ -2252,6 +2256,65 @@ def get_blotter(self):
         """
         return self._blotter
 
+    def set_base_currency(self, currency: str) -> None:
+        """
+        Set the base currency for multi-currency portfolio reporting.
+
+        When a base currency is set and an FX rate provider is registered,
+        the framework will automatically convert position values from
+        their local currency to the base currency when computing
+        portfolio totals.
+
+        Args:
+            currency: Currency code (e.g. "EUR", "USD", "GBP").
+
+        Returns:
+            None
+        """
+        self._base_currency = currency.upper()
+
+    def get_base_currency(self) -> str:
+        """
+        Get the configured base currency.
+
+        Returns:
+            str or None: The base currency code, or None if not set.
+        """
+        return self._base_currency
+
+    def add_fx_rate_provider(self, fx_rate_provider) -> None:
+        """
+        Register an FX rate provider for multi-currency portfolio
+        support. The provider supplies exchange rates between
+        currency pairs.
+
+        Args:
+            fx_rate_provider: Instance of FXRateProvider.
+
+        Returns:
+            None
+        """
+        from investing_algorithm_framework.domain.fx import FXRateProvider
+
+        if inspect.isclass(fx_rate_provider):
+            fx_rate_provider = fx_rate_provider()
+
+        if not isinstance(fx_rate_provider, FXRateProvider):
+            raise OperationalException(
+                "FX rate provider should be an instance of FXRateProvider"
+            )
+
+        self._fx_rate_provider = fx_rate_provider
+
+    def get_fx_rate_provider(self):
+        """
+        Get the configured FX rate provider.
+
+        Returns:
+            FXRateProvider or None: The FX rate provider instance.
+        """
+        return self._fx_rate_provider
+
     def add_order_executor(self, order_executor):
         """
         Function to add an order executor to the app. The order executor