How to Use Freqtrade with FXMacroData for Macro-Aware Trading Bots

Freqtrade is a popular open-source trading bot framework with strategy files, backtesting, hyperopt, dry-run, and live modes. FXMacroData fits beside it as an external macro-risk layer: calendar events, announcement history, FX sessions, USD macro context, and release windows that a bot can use as filters or annotations.

Freqtrade is usually used for crypto pairs, but macro context still matters when USD liquidity, global risk appetite, rates, or release windows affect the quote currency or broader market. The goal is not to turn a bot into an economist. It is to stop the bot from behaving as if every candle has the same macro risk.

Why Freqtrade Fits Macro Filters

Freqtrade strategies already operate on dataframes and entry/exit signal columns. That is a clean place to add an external binary feature such as macro_block, usd_release_window, or session_state. The model or AI layer is optional; the strategy itself should use deterministic columns.

Useful first tests include blocking new entries before major USD events, tagging trades by FX session, or comparing bot behavior on days with high-impact US announcements against normal days.

What Changes for the Bot Operator

A bot operator's problem is not only signal generation. It is also deciding when the bot should be allowed to act. Freqtrade can already evaluate indicators and manage a strategy loop. FXMacroData adds a separate question: is the market about to enter a known macro window where normal candle behavior may not be representative?

That distinction is especially useful for dry-run and live monitoring. Instead of discovering after the fact that a bot opened a position just before a major USD event, the operator can see a simple macro tag in the strategy path. The tag does not predict the release. It controls when the bot is allowed to treat a technical setup as normal.

This keeps judgement in the right layer. The macro calendar becomes a deterministic feature, while any AI assistant stays in the research lane: explaining blocked trades, suggesting tests, or summarizing the next release window.

Workflow Shape

REST, Cache, Strategy, or AI?

Step 1: Cache FXMacroData State

Run a small refresh job on a schedule that matches your trading timeframe. It can write a simple local file for the strategy to read.

import json
import os
import requests
from pathlib import Path

def fetch(path):
    r = requests.get(
        f"https://api.fxmacrodata.com/v1{path}",
        params={"api_key": os.environ["FXMD_API_KEY"]},
        timeout=20,
    )
    r.raise_for_status()
    return r.json()

state = {"calendar": fetch("/calendar/usd"), "sessions": fetch("/market_sessions")}
Path("user_data/fxmacrodata_state.json").write_text(json.dumps(state))

The public REST examples use query-parameter authentication:

curl "https://api.fxmacrodata.com/v1/calendar/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/announcements/usd/inflation?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/market_sessions?api_key=YOUR_API_KEY"

Step 2: Use the State in a Strategy

Freqtrade strategy files define indicators and entry or exit rules. Load the cached state and turn it into deterministic columns.

from freqtrade.strategy import IStrategy
from pandas import DataFrame
import json

class MacroAwareStrategy(IStrategy):
    timeframe = "5m"

    def populate_indicators(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
        with open("user_data/fxmacrodata_state.json", "r", encoding="utf-8") as f:
            state = json.load(f)
        dataframe["macro_block"] = 0
        if has_usd_event_window(state, dataframe["date"].iloc[-1]):
            dataframe["macro_block"] = 1
        return dataframe

Then require the macro flag to be clear before new entries. Keep the rule readable while you prove the idea.

def populate_entry_trend(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
    dataframe.loc[
        (dataframe["macro_block"] == 0) &
        (dataframe["volume"] > 0) &
        (dataframe["close"] > dataframe["close"].rolling(20).mean()),
        "enter_long"
    ] = 1
    return dataframe

Step 3: Backtest the Macro Filter

Freqtrade backtesting and hyperopt simulate only parts of live bot behavior, so test the macro feature in a way that matches its intended use. Compare runs with and without the filter, then inspect the trades blocked by macro windows.

freqtrade backtesting --strategy MacroAwareStrategy --timerange 20240101-20261231
freqtrade backtesting --strategy BaseStrategy --timerange 20240101-20261231

Do not call the live API from inside historical backtests. Use a fixed macro snapshot for the backtest range so the result can be reproduced later.

Research Questions Worth Testing

The macro filter should earn its place. Test it against questions that would matter to an operator deciding whether to keep the rule enabled.

Optional AI Research Layer

If you use an AI coding assistant or research agent around Freqtrade, connect FXMacroData MCP at https://mcp.fxmacrodata.com. Use it to inspect macro context, explain backtest results, or generate a first draft of strategy code. Keep execution in Freqtrade's deterministic strategy and risk controls.

{
  "servers": {
    "FXMacroData": {
      "type": "http",
      "url": "https://mcp.fxmacrodata.com?api_key=YOUR_API_KEY"
    }
  }
}

Bot Guardrails

Common Questions

Is Freqtrade an FX trading platform?

Freqtrade is primarily used as a crypto trading bot framework. FXMacroData is still relevant when USD macro events, global sessions, and rate-sensitive conditions affect crypto pairs or portfolio risk.

Should the strategy call FXMacroData every candle?

No. Refresh macro state in a sidecar or scheduled task, cache it locally, and let the strategy read deterministic columns.

Can MCP run the Freqtrade bot?

Do not use MCP as the bot control plane. Use MCP for research and assistant workflows, and keep Freqtrade strategy execution behind its normal controls.