Add FXMacroData macro provider

docs/AI_AGENT_BUILTIN_TOOLS.md

@@ -58,6 +58,15 @@ FRED macro tools:
 
 Built-in FRED tools require `FRED_API_KEY` so Lumibot can request official FRED/ALFRED observations with `realtime_start` and `realtime_end`. Lumibot does not use public CSV fallbacks for macro data, because those endpoints can contain revised values and are not a safe default for historical simulations.
 
+FXMacroData tools:
+
+- `list_fxmacrodata_indicators`
+- `get_fxmacrodata_series`
+- `get_fxmacrodata_latest`
+- `get_fxmacrodata_snapshot`
+
+FXMacroData tools fetch FX-focused macro announcement rows from FXMacroData. USD announcement data is public. Set `FXMD_API_KEY` or `FXMACRODATA_API_KEY` for non-USD and paid endpoint access. Lumibot sends the key as an `X-API-Key` header rather than adding it to request URLs.
+
 Memory tools:
 
 - `remember`

docs/AI_TRADING_AGENTS.md

@@ -80,7 +80,7 @@ if __name__ == "__main__":
         )
 ```
 
-The agent gets Lumibot's built-in `get_fred_series` tool automatically when `FRED_API_KEY` is configured. During backtests the tool defaults `as_of` to the strategy datetime and uses FRED/ALFRED realtime parameters, so the agent does not see future macro revisions.
+The agent gets Lumibot's built-in macro tools automatically. `get_fred_series` is exposed when `FRED_API_KEY` is configured and uses FRED/ALFRED realtime parameters during backtests. FXMacroData tools such as `get_fxmacrodata_series` are also available for FX-focused macro announcement rows; set `FXMD_API_KEY` or `FXMACRODATA_API_KEY` for non-USD access.
 
 No local MCP server scripts. No npm installs. No explicit built-in tool lists. Lumibot includes all built-in tools by default, and you can add custom `@agent_tool` functions when you need proprietary APIs or special research logic.
 

docs/ENV_VARS.md

@@ -363,6 +363,24 @@ Notes:
 - Purpose: Override the local FRED macro data cache.
 - Default: `~/.lumibot/cache/fred`.
 
+### `FXMD_API_KEY`
+- Purpose: Optional FXMacroData API key for non-USD and paid macro announcement endpoints.
+- Default: unset.
+- Notes: Lumibot sends this key as an `X-API-Key` header. `FXMACRODATA_API_KEY` is also accepted. USD announcement data can be fetched without a key.
+
+### `FXMACRODATA_API_KEY`
+- Purpose: Alternate environment variable for the FXMacroData API key.
+- Default: unset.
+- Notes: Used when `FXMD_API_KEY` is not set.
+
+### `LUMIBOT_FXMACRODATA_API_BASE_URL`
+- Purpose: Override the FXMacroData API base URL.
+- Default: `https://api.fxmacrodata.com/v1`.
+
+### `LUMIBOT_FXMACRODATA_CACHE_DIR`
+- Purpose: Override the local FXMacroData macro release cache.
+- Default: `~/.lumibot/cache/fxmacrodata`.
+
 ### `LUMIBOT_MEMORY_DIR`
 - Purpose: Override the local SQLite agent memory root.
 - Default: `.lumibot/memory` under the current working directory.

docs/FRED_MACRO_DATA.md

@@ -4,7 +4,7 @@ Lumibot includes native Federal Reserve Economic Data (FRED) macro tools for str
 
 Use macro data for interest rates, inflation, employment, growth, liquidity, credit spreads, and market-risk context.
 
-## Strategy API
+## FRED Strategy API
 
 ```python
 self.macro.list_series()
@@ -13,9 +13,9 @@ self.macro.get_latest("UNRATE")
 self.macro.get_snapshot(["FEDFUNDS", "DGS10", "CPIAUCSL", "UNRATE"])
 ```
 
-## Agent Tools
+## FRED Agent Tools
 
-Agents receive these built-ins automatically:
+Agents receive these FRED built-ins automatically:
 
 - `list_fred_series`
 - `get_fred_series`
@@ -24,9 +24,11 @@ Agents receive these built-ins automatically:
 
 You do not need to manually attach these tools. They are included with the rest of the built-in agent tool surface.
 
-## API Key Behavior
+## FRED API Key Behavior
 
-`FRED_API_KEY` is required for the official FRED/ALFRED API path and for strict point-in-time macro backtests.
+`FRED_API_KEY` is required for the official FRED/ALFRED API path and for FRED macro data fetches.
+
+This FRED credential is not used by FXMacroData. FXMacroData access is described separately below.
 
 Lumibot uses the official FRED/ALFRED API and passes `realtime_start` and `realtime_end` based on the strategy datetime. This is the strict point-in-time path for macro backtests.
 
@@ -53,3 +55,37 @@ export LUMIBOT_FRED_CACHE_DIR=/path/to/cache
 ```
 
 Backtests should fetch each series once and reuse the local cache instead of hitting FRED on every trading iteration.
+
+## FXMacroData Macro Releases
+
+Lumibot also includes an FXMacroData provider for FX-focused macro announcement rows:
+
+```python
+self.macro.fxmacrodata.list_indicators()
+self.macro.fxmacrodata.get_series("eur", "inflation")
+self.macro.fxmacrodata.get_latest("jpy", "policy_rate")
+self.macro.fxmacrodata.get_snapshot("gbp", ["inflation", "policy_rate", "unemployment"])
+```
+
+FXMacroData agents receive these read-only built-ins automatically:
+
+- `list_fxmacrodata_indicators`
+- `get_fxmacrodata_series`
+- `get_fxmacrodata_latest`
+- `get_fxmacrodata_snapshot`
+
+USD announcement data is public. Set `FXMD_API_KEY` or `FXMACRODATA_API_KEY` for non-USD and paid endpoint access. Lumibot sends the key as an `X-API-Key` header, not as an `api_key` query parameter.
+
+In a backtest, `as_of` defaults to `self.get_datetime()`. Lumibot filters release rows by `announcement_datetime` so the strategy does not see macro releases after the simulated datetime.
+
+In backtests, FXMacroData responses are cached under:
+
+```text
+~/.lumibot/cache/fxmacrodata
+```
+
+Override with:
+
+```bash
+export LUMIBOT_FXMACRODATA_CACHE_DIR=/path/to/cache
+```

docsrc/agents.rst

@@ -88,7 +88,7 @@ Here is a complete AI trading agent strategy that uses Lumibot's built-in FRED m
                 benchmark_asset="SPY",
             )
 
-That is the entire strategy file. No local MCP server scripts, no npm installs, and no explicit built-in tool lists. LumiBot includes built-in tools by default, including ``get_fred_series`` when ``FRED_API_KEY`` is configured.
+That is the entire strategy file. No local MCP server scripts, no npm installs, and no explicit built-in tool lists. LumiBot includes built-in tools by default, including ``get_fred_series`` when ``FRED_API_KEY`` is configured and FXMacroData tools such as ``get_fxmacrodata_series`` for FX-focused macro announcement rows.
 
 How ``@agent_tool`` Works
 -------------------------

docsrc/agents_builtin_tools.rst

@@ -136,6 +136,20 @@ using realtime parameters. LumiBot's built-in FRED tools do not use public CSV
 fallbacks; macro tool output should either come from the official API or fail
 clearly.
 
+FXMacroData
+-----------
+
+FXMacroData tools expose FX-focused macro announcement rows to agents:
+
+- ``list_fxmacrodata_indicators``
+- ``get_fxmacrodata_series``
+- ``get_fxmacrodata_latest``
+- ``get_fxmacrodata_snapshot``
+
+USD announcement data is public. Set ``FXMD_API_KEY`` or
+``FXMACRODATA_API_KEY`` for non-USD and paid endpoint access. LumiBot sends the
+key as an ``X-API-Key`` header rather than adding it to request URLs.
+
 News
 ----
 

docsrc/environment_variables.rst

@@ -909,6 +909,35 @@ LUMIBOT_FRED_CACHE_DIR
 - Purpose: Override local FRED macro data cache.
 - Default: ``~/.lumibot/cache/fred``.
 
+FXMD_API_KEY
+^^^^^^^^^^^^
+
+- Purpose: Optional FXMacroData API key for non-USD and paid macro announcement
+  endpoints.
+- Default: unset.
+- Notes: LumiBot sends this key as an ``X-API-Key`` header.
+  ``FXMACRODATA_API_KEY`` is also accepted. USD announcement data can be fetched
+  without a key.
+
+FXMACRODATA_API_KEY
+^^^^^^^^^^^^^^^^^^^
+
+- Purpose: Alternate environment variable for the FXMacroData API key.
+- Default: unset.
+- Notes: Used when ``FXMD_API_KEY`` is not set.
+
+LUMIBOT_FXMACRODATA_API_BASE_URL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Purpose: Override the FXMacroData API base URL.
+- Default: ``https://api.fxmacrodata.com/v1``.
+
+LUMIBOT_FXMACRODATA_CACHE_DIR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Purpose: Override local FXMacroData macro release cache.
+- Default: ``~/.lumibot/cache/fxmacrodata``.
+
 LUMIBOT_MEMORY_DIR
 ^^^^^^^^^^^^^^^^^^
 

docsrc/macro_data.rst

@@ -8,8 +8,8 @@ employment, growth, liquidity, credit spreads, and market-risk context.
 .. image:: ../docs/assets/ai_committee/docs_fred_macro_data.png
    :alt: FRED macro data tools and point-in-time behavior in Lumibot
 
-Strategy API
-------------
+FRED Strategy API
+-----------------
 
 .. code-block:: python
 
@@ -18,10 +18,10 @@ Strategy API
    self.macro.get_latest("UNRATE")
    self.macro.get_snapshot(["FEDFUNDS", "DGS10", "CPIAUCSL", "UNRATE"])
 
-Agent Tools
------------
+FRED Agent Tools
+----------------
 
-Agents receive these built-ins automatically:
+Agents receive these FRED built-ins automatically:
 
 - ``list_fred_series``
 - ``get_fred_series``
@@ -31,13 +31,18 @@ Agents receive these built-ins automatically:
 These tools are available to read-only research agents and trading-enabled
 portfolio agents. They do not submit, cancel, or modify orders.
 
-API Key Behavior
-----------------
+FRED API Key Behavior
+---------------------
 
 ``FRED_API_KEY`` is required for the official FRED/ALFRED API path and for
-all macro data fetches. LumiBot uses the official API path instead of public
-CSV fallbacks so tool output has a clear provenance and backtests can request
-point-in-time vintage observations.
+FRED macro data fetches.
+
+This FRED credential is not used by FXMacroData. FXMacroData access is
+described separately below.
+
+LumiBot uses the official API path instead of public CSV fallbacks so tool
+output has a clear provenance and backtests can request point-in-time vintage
+observations.
 
 With a key, LumiBot passes ``realtime_start`` and ``realtime_end`` based on the
 strategy datetime so the backtest sees the vintage observations that were
@@ -60,3 +65,35 @@ Cache
 
 FRED data is cached under ``~/.lumibot/cache/fred`` by default. Override this
 with ``LUMIBOT_FRED_CACHE_DIR``.
+
+FXMacroData Macro Releases
+==========================
+
+LumiBot also includes an FXMacroData provider for FX-focused macro announcement
+rows:
+
+.. code-block:: python
+
+   self.macro.fxmacrodata.list_indicators()
+   self.macro.fxmacrodata.get_series("eur", "inflation")
+   self.macro.fxmacrodata.get_latest("jpy", "policy_rate")
+   self.macro.fxmacrodata.get_snapshot("gbp", ["inflation", "policy_rate", "unemployment"])
+
+FXMacroData agents receive these read-only built-ins automatically:
+
+- ``list_fxmacrodata_indicators``
+- ``get_fxmacrodata_series``
+- ``get_fxmacrodata_latest``
+- ``get_fxmacrodata_snapshot``
+
+USD announcement data is public. Set ``FXMD_API_KEY`` or
+``FXMACRODATA_API_KEY`` for non-USD and paid endpoint access. LumiBot sends the
+key as an ``X-API-Key`` header, not as an ``api_key`` query parameter.
+
+In a backtest, ``as_of`` defaults to ``self.get_datetime()``. LumiBot filters
+release rows by ``announcement_datetime`` so the strategy does not see macro
+releases after the simulated datetime.
+
+In backtests, FXMacroData responses are cached under
+``~/.lumibot/cache/fxmacrodata`` by default. Override this with
+``LUMIBOT_FXMACRODATA_CACHE_DIR``.