22 KiB

Raw Blame History

XAU (Gold) Trading System - Design Document

Author: Claude Code Date: October 6, 2025 Asset: XAU/USD (Gold Spot) Framework: TradingAgents Multi-Agent LLM System

📋 Executive Summary

Design a specialized multi-agent trading system for XAU (Gold) that leverages the existing TradingAgents framework with gold-specific enhancements. Gold trading requires unique considerations due to its role as a safe-haven asset, sensitivity to macro factors (USD, inflation, geopolitics), and different technical behavior compared to equities.

🎯 Objectives

Adapt TradingAgents framework for commodity/forex trading (XAU/USD pair)
Enhance analyst agents with gold-specific indicators and macro factors
Add gold-specific data sources (DXY, real yields, central bank activity, geopolitical events)
Optimize for gold's unique characteristics (24/5 trading, safe-haven flows, correlation dynamics)
Create specialized prompts for gold market analysis

🏗️ System Architecture

Current Framework Adaptation

Existing Flow (unchanged):

Analyst Team → Research Team → Trader → Risk Management → Portfolio Manager

XAU-Specific Enhancements:

Gold-specific technical indicators
Macro factor integration (USD Index, Treasury Yields, Fed Policy)
Geopolitical event monitoring
Correlation analysis tools
Safe-haven flow detection

📊 Component Design

1. Enhanced Analyst Team

A. Market Analyst (Technical) - XAU Specialization

Current: Uses equity-focused indicators (RSI, MACD, Bollinger Bands, SMA/EMA)

XAU Enhancements:

Gold-Specific Technical Indicators:

Pivot Points (S1, S2, S3, R1, R2, R3) - Gold respects technical levels strongly
ATR (Average True Range) - Critical for gold's volatility assessment
Ichimoku Cloud - Popular in forex/commodity trading
Fibonacci Retracements - Gold frequently respects Fib levels
Volume Profile / Volume Weighted Average Price (VWAP) - Institutional participation
Bollinger Band Width - Volatility breakout detection

Timeframe Analysis:

Multi-timeframe approach: 1H, 4H, Daily, Weekly
Key support/resistance from higher timeframes
Trend alignment across timeframes

Implementation:

# tradingagents/agents/analysts/xau_market_analyst.py
- Extended indicator list specific to gold
- Multi-timeframe analysis capability
- Support/resistance level identification
- Chart pattern recognition (double top/bottom, H&S for gold)

B. Fundamentals Analyst - Macro-Focused for Gold

Current: Analyzes company earnings, balance sheets, P/E ratios (equity-focused)

XAU Transformation → Macro Fundamentals Analyst:

Primary Macro Drivers:

US Dollar Index (DXY)
- Inverse correlation with gold (~-0.7 to -0.9)
- Track DXY technical levels and trends
- Monitor USD strength/weakness narratives
Real Treasury Yields (10-Year TIPS)
- Gold's opportunity cost metric
- Negative yields = bullish for gold
- Track yield curve dynamics
Federal Reserve Policy
- Interest rate decisions and forward guidance
- QE/QT programs (liquidity conditions)
- Fed speak and policy pivot signals
- FOMC meeting minutes and dot plot
Inflation Indicators
- CPI, Core CPI, PCE (Fed's preferred metric)
- Inflation expectations (breakeven rates)
- Producer prices (PPI)
Central Bank Activity
- Central bank gold purchases (demand driver)
- Reserve diversification trends
- CBGA (Central Bank Gold Agreement) updates
Geopolitical Risk
- Conflicts, sanctions, trade wars
- Political instability events
- Currency crisis developments

Data Sources:

FRED (Federal Reserve Economic Data) API
Alpha Vantage for forex/macro data (DXY, USD pairs)
Custom news scraping for geopolitical events
CME FedWatch Tool data (rate probabilities)

Implementation:

# tradingagents/agents/analysts/xau_macro_analyst.py (NEW)
# Replace fundamentals_analyst for XAU trading
- USD Index trend analysis
- Real yield calculation and trends
- Fed policy stance interpretation
- Inflation regime assessment
- Geopolitical risk scoring

C. News Analyst - Gold-Specific Focus

Current: General market news monitoring

XAU Enhancements:

Targeted News Sources:

Central Bank Communications: Fed, ECB, BoE, PBoC statements
Geopolitical Developments: Conflicts, sanctions, safe-haven triggers
Inflation Reports: CPI, PCE releases and surprises
US Dollar Events: Economic data affecting USD (NFP, GDP, retail sales)
Mining Supply News: Major producer disruptions, strikes
ETF Flows: GLD, IAU inflow/outflow trends (sentiment indicator)

Sentiment Analysis Categories:

Safe-haven demand (bullish)
Risk-on sentiment (bearish)
Inflation concerns (bullish)
USD strength narratives (bearish)
Central bank hawkish/dovish tone

Implementation:

# tradingagents/agents/analysts/xau_news_analyst.py
- Geopolitical event detection and impact scoring
- Central bank communication parsing
- Macro data release monitoring
- Gold-specific keyword filtering

D. Sentiment Analyst - COT & Positioning

Current: Social media sentiment for equities

XAU Transformation → Market Positioning Analyst:

Data Sources:

COT Report (Commitment of Traders)
- Large Speculators net positioning
- Commercials (producers/refiners) hedging activity
- Extreme positioning as contrarian indicator
- Week-over-week changes in open interest
Gold ETF Flows
- GLD (SPDR Gold Shares) holdings trends
- IAU (iShares Gold Trust) flows
- Daily/weekly net inflows as sentiment
Options Market
- GLD/GC options: Put/Call ratio
- Implied volatility (GVZ - Gold VIX)
- Skew analysis (demand for upside vs downside)
Social Sentiment (Secondary)
- FinTwit gold discussions (Twitter/X)
- Reddit r/Gold, r/wallstreetbets mentions
- Institutional research sentiment from Seeking Alpha, Bloomberg

Implementation:

# tradingagents/agents/analysts/xau_positioning_analyst.py
- COT report parsing and trend analysis
- ETF flow tracking
- Options sentiment metrics
- Contrarian positioning signals

2. Research Team - Gold Context

Bull Researcher:

Emphasize safe-haven narratives
Inflation hedge thesis
USD weakness scenarios
Central bank demand trends
Technical breakout potential

Bear Researcher:

Opportunity cost arguments (rising real yields)
Risk-on equity market strength
USD strength cases
Profit-taking from overbought levels
Technical resistance failures

Research Manager:

Synthesize macro vs technical signals
Weight fundamental drivers appropriately
Consider gold's dual nature (commodity + safe-haven)

3. Trading Team - XAU Execution

Trader Agent Enhancements:

Position Sizing for Gold:

Account for higher volatility vs equities (1-2% daily moves common)
Use ATR-based position sizing
Respect gold's leverage conventions (100:1 in forex)

Entry/Exit Refinement:

Key round numbers (1900, 2000, 2100, etc.) as psychological levels
London Fix times (10:30 AM, 3:00 PM London) - high liquidity periods
Avoid thin liquidity periods (Asian session gaps)

Stop Loss Strategies:

ATR-based stops (2x-3x ATR from entry)
Technical stops (below/above key S/R)
Volatility-adjusted trailing stops

Time Horizon Considerations:

Intraday: 1H-4H trends
Swing: Daily-Weekly trends
Position: Monthly macro themes

4. Risk Management - Gold-Specific Risks

Unique Gold Risks:

Flash Crashes: Gold prone to liquidity gaps (e.g., May 2021 flash crash)
Overnight Gaps: 24/5 trading means weekend geopolitical gaps
USD Correlation: Strong negative correlation can amplify moves
Volatility Spikes: VIX spikes → gold volatility spikes
Macro Event Risk: FOMC, CPI, NFP can cause 2-5% moves

Risk Management Enhancements:

Aggressive Analyst:

Leverage up during strong macro tailwinds (QE environments)
Ride momentum in safe-haven flows
Scale into breakouts of multi-year resistances

Conservative Analyst:

Reduce size around FOMC, CPI releases
Respect ATR-based stops strictly
Exit partial positions at Fibonacci resistance levels
Avoid trading during thin liquidity (holiday periods)

Neutral Analyst:

Balance technical signals with macro backdrop
Use correlation filters (if DXY rallying hard, be cautious on gold longs)
Monitor VIX for risk-off confirmations

🔧 Technical Implementation Plan

Phase 1: Data Layer Enhancement

New Data Vendors (tradingagents/dataflows/):

fred_api.py - Federal Reserve Economic Data
- DXY (US Dollar Index)
- 10-Year Treasury Yield
- 10-Year TIPS (real yields)
- CPI, PCE, PPI data
- Fed Funds Rate
forex_data.py - Forex/Commodity Data
- XAU/USD from Alpha Vantage or OANDA API
- EUR/USD, GBP/USD for correlation
- Gold futures (GC) data from CME
cot_data.py - Commitment of Traders
- CFTC COT report parsing
- Net positioning calculations
- Historical extremes tracking
etf_flows.py - Gold ETF Holdings
- GLD holdings scraping (from SPDR website)
- IAU holdings tracking
- Daily/weekly flow calculations

Data Abstraction Update (tradingagents/agents/utils/agent_utils.py):

# New abstract tool functions
def get_macro_data(indicator: str, start_date: str, end_date: str) -> str:
    """Fetch macro data (DXY, yields, CPI, etc.)"""

def get_cot_data(asset: str, lookback_weeks: int) -> str:
    """Fetch COT positioning data"""

def get_etf_flows(etf_ticker: str, start_date: str, end_date: str) -> str:
    """Track ETF inflows/outflows"""

def get_correlation(asset1: str, asset2: str, window: int) -> float:
    """Calculate rolling correlation between assets"""

Phase 2: Agent Specialization

Create XAU-Specific Agent Files:

tradingagents/agents/analysts/xau_market_analyst.py
- Gold-specific technical indicators
- Multi-timeframe analysis
- Key level identification (Fibonacci, pivots)
- Chart pattern recognition
tradingagents/agents/analysts/xau_macro_analyst.py (replaces fundamentals)
- USD Index analysis
- Real yields calculation and trend
- Fed policy stance interpretation
- Inflation regime assessment
- Central bank activity monitoring
tradingagents/agents/analysts/xau_news_analyst.py
- Geopolitical event filtering
- Macro data release monitoring
- Central bank communication parsing
- Safe-haven narrative detection
tradingagents/agents/analysts/xau_positioning_analyst.py (replaces social)
- COT report analysis
- ETF flow tracking
- Options sentiment (Put/Call, IV)
- Contrarian signals from extremes

Prompt Engineering (System Messages):

Each XAU agent gets gold-specific system prompts:

Market Analyst: "You are analyzing XAU/USD (Gold). Gold is a safe-haven asset highly sensitive to USD strength, real yields, and geopolitical risk..."
Macro Analyst: "Your role is to assess fundamental drivers of gold prices: USD Index, real yields, Fed policy, inflation, central bank demand, geopolitical risk..."
News Analyst: "Monitor news for gold-specific catalysts: Fed communications, inflation surprises, geopolitical crises, USD-impacting events..."
Positioning Analyst: "Analyze market positioning through COT data, ETF flows, and options. Extreme positioning can signal reversals..."

Phase 3: Configuration & Integration

XAU-Specific Config (tradingagents/xau_config.py):

XAU_CONFIG = DEFAULT_CONFIG.copy()

# Override data vendors for XAU-specific sources
XAU_CONFIG["data_vendors"] = {
    "core_stock_apis": "alpha_vantage",  # For XAU/USD price data
    "technical_indicators": "yfinance",   # Or custom forex indicators
    "fundamental_data": "fred",           # Macro data from FRED
    "news_data": "alpha_vantage",         # Keep existing
    "macro_data": "fred",                 # NEW: FRED for macro
    "positioning_data": "cot_api",        # NEW: COT data
    "etf_data": "scraper",                # NEW: ETF flows
}

# XAU-specific parameters
XAU_CONFIG["asset_class"] = "commodity"
XAU_CONFIG["trading_hours"] = "24/5"  # Sunday 5pm - Friday 5pm ET
XAU_CONFIG["tick_size"] = 0.01
XAU_CONFIG["contract_size"] = 100  # oz for futures
XAU_CONFIG["max_leverage"] = 50  # Conservative for retail

# Risk parameters tuned for gold volatility
XAU_CONFIG["max_position_size_pct"] = 2.0  # % of portfolio
XAU_CONFIG["atr_multiplier_stop"] = 2.5    # ATR-based stops
XAU_CONFIG["correlation_threshold"] = -0.6  # DXY correlation filter

Graph Setup for XAU (tradingagents/graph/xau_graph.py):

class XAUTradingGraph(TradingAgentsGraph):
    """Specialized graph for XAU trading"""

    def __init__(self, debug=False, config=None):
        # Use XAU-specific analysts
        xau_analysts = ["xau_market", "xau_macro", "xau_news", "xau_positioning"]

        # Initialize with XAU config
        xau_config = config or XAU_CONFIG

        super().__init__(
            selected_analysts=xau_analysts,
            debug=debug,
            config=xau_config
        )

    def _create_tool_nodes(self):
        """Override to include XAU-specific tools"""
        return {
            "xau_market": ToolNode([
                get_stock_data,       # XAU/USD price data
                get_indicators,       # Technical indicators
                get_correlation,      # NEW: Correlation analysis
            ]),
            "xau_macro": ToolNode([
                get_macro_data,       # NEW: DXY, yields, CPI
                get_news,             # Macro news
            ]),
            "xau_news": ToolNode([
                get_news,
                get_global_news,
            ]),
            "xau_positioning": ToolNode([
                get_cot_data,         # NEW: COT report
                get_etf_flows,        # NEW: GLD/IAU flows
            ]),
        }

Phase 4: Execution & Backtesting

Entry Point (xau_main.py):

from tradingagents.graph.xau_graph import XAUTradingGraph
from tradingagents.xau_config import XAU_CONFIG
from dotenv import load_dotenv

load_dotenv()

# Initialize XAU-specific graph
xau_system = XAUTradingGraph(debug=True, config=XAU_CONFIG)

# Run analysis
trade_date = "2024-05-10"
final_state, decision = xau_system.propagate("XAU", trade_date)

print(f"Gold Trading Decision for {trade_date}:")
print(decision)

# Optionally backtest on historical data
# xau_system.backtest(start_date="2023-01-01", end_date="2024-12-31")

CLI Enhancement (cli/xau_main.py):

# Add XAU mode to existing CLI
@app.command()
def xau():
    """Run XAU (Gold) trading analysis"""
    # Use XAU-specific workflow
    # Select macro factors instead of equity analysts
    # Display gold-specific metrics (DXY correlation, real yields, COT)

📈 Gold-Specific Features

1. Macro Dashboard

Real-time dashboard showing:

DXY (US Dollar Index): Current level, trend, support/resistance
10Y Real Yield: Current level, direction, historical context
Fed Funds Rate: Current rate, expected changes (CME FedWatch)
CPI (YoY): Latest inflation reading, trend
XAU/DXY Correlation: Rolling 30/60/90 day correlation
VIX: Risk sentiment proxy

2. COT Positioning Indicator

Large Spec Net Positioning (Long - Short)
Commercials Positioning (hedging activity)
Percentile ranking (is positioning extreme?)
Week-over-week changes
Contrarian signals (extreme long = caution, extreme short = opportunity)

3. Multi-Timeframe Technical Analysis

Timeframe Alignment:

Weekly: Major trend direction (above/below 200 SMA)
Daily: Intermediate trend and key S/R levels
4H: Entry/exit timing, momentum shifts
1H: Precision entries, stop placement

Confluence Zones:

Identify areas where multiple timeframes show S/R
Fibonacci + pivot + moving average confluence
Volume profile nodes (high activity zones)

4. Correlation Filters

Pre-Trade Checks:

If DXY rallying strongly (+0.5% day) → reduce gold long conviction
If DXY breaking down → increase gold long conviction
If VIX spiking (risk-off) → gold should benefit (safe-haven check)
If real yields rising → headwind for gold

Dynamic Position Sizing:

Increase size when macro tailwinds align (weak USD + rising inflation + dovish Fed)
Reduce size when macro headwinds present (strong USD + rising real yields + hawkish Fed)

🧪 Testing & Validation

Backtesting Strategy

Historical Periods to Test:

QE Environment (2020-2021): Gold rally to $2075
Rate Hike Cycle (2022-2023): Gold decline to $1620, then recovery
Geopolitical Crisis (Feb 2022): Russia-Ukraine invasion safe-haven spike
Inflation Surge (2021-2022): CPI spike and gold's response

Metrics to Track:

Win rate on BUY/SELL signals
Average holding period
Max drawdown during trending vs ranging markets
Signal quality during high-volatility events (FOMC, CPI)
Correlation to actual XAU/USD price changes

Paper Trading

Before live deployment:

Run system daily for 3 months
Track hypothetical P&L vs actual gold moves
Analyze false signals and improve filters
Refine risk management (stop sizes, position sizing)

🚀 Implementation Roadmap

Week 1-2: Data Infrastructure

Implement FRED API integration (fred_api.py)
Implement COT data parser (cot_data.py)
Implement ETF flows scraper (etf_flows.py)
Add correlation calculation tools
Test all data sources with historical queries

Week 3-4: Agent Specialization

Create xau_market_analyst.py with gold-specific indicators
Create xau_macro_analyst.py for fundamental drivers
Create xau_news_analyst.py with geopolitical focus
Create xau_positioning_analyst.py for COT/ETF analysis
Write comprehensive prompts for each agent

Week 5: Integration & Configuration

Create xau_config.py with gold-specific parameters
Create XAUTradingGraph class
Update tool routing for XAU-specific data
Create xau_main.py entry point
Test end-to-end flow with sample dates

Week 6: Testing & Refinement

Backtest on 2020-2024 historical data
Analyze signal quality and edge cases
Refine prompts based on output quality
Optimize debate rounds and research depth
Document findings and adjust parameters

Week 7-8: CLI & Deployment

Enhance CLI with XAU mode
Create macro dashboard visualization
Add real-time monitoring scripts
Setup paper trading pipeline
Create user documentation

📋 Key Decisions & Trade-offs

1. Fundamental Analysis Approach

Decision: Replace equity fundamentals analyst with macro analyst
Rationale: Gold doesn't have earnings/revenue; macro factors drive price
Trade-off: Lose equity analysis capability in XAU mode (acceptable - focused system)

2. Data Vendor Selection

Decision: Use FRED for macro data, custom scrapers for COT/ETF
Rationale: Free, reliable, comprehensive coverage
Trade-off: Rate limits on FRED (acceptable with caching), scraping fragility (mitigate with fallbacks)

3. Timeframe Focus

Decision: Multi-timeframe (1H, 4H, Daily, Weekly)
Rationale: Gold respects technical levels across timeframes
Trade-off: Increased complexity, potential conflicting signals (resolve with hierarchy: Weekly > Daily > 4H > 1H)

4. Research Depth

Decision: Keep debate rounds at 1-2 for cost efficiency
Rationale: Gold has clearer macro drivers than equities; less debate needed
Trade-off: May miss nuanced scenarios (acceptable - can increase for critical periods)

5. Real-time vs EOD Analysis

Decision: Start with EOD (end-of-day) analysis
Rationale: Easier to implement, sufficient for swing trading
Trade-off: Miss intraday opportunities (acceptable for Phase 1; add real-time in Phase 2)

🎯 Success Metrics

Quantitative Metrics

Signal Accuracy: >60% directional accuracy on daily moves
Macro Alignment: >75% of signals align with dominant macro regime
Risk-Adjusted Returns: Sharpe ratio >1.0 in backtests
Drawdown: Max drawdown <15% in backtests

Qualitative Metrics

Report Quality: Coherent, actionable macro narratives
Risk Awareness: Proper identification of geopolitical/macro risks
Timing: Signals generated before major moves (leading, not lagging)
Consistency: Stable performance across different market regimes

📚 Resources & References

Gold Market Fundamentals

World Gold Council: https://www.gold.org/
LBMA (London Bullion Market Association): https://www.lbma.org.uk/
GLD ETF Holdings: https://www.spdrgoldshares.com/

Macro Data Sources

FRED (Federal Reserve): https://fred.stlouisfed.org/
CME FedWatch: https://www.cmegroup.com/markets/interest-rates/cme-fedwatch-tool.html
CFTC COT Reports: https://www.cftc.gov/MarketReports/CommitmentsofTraders/index.htm

Technical Analysis

TradingView (Gold charts): https://www.tradingview.com/symbols/XAUUSD/
Investing.com (Gold real-time): https://www.investing.com/commodities/gold

🔄 Next Steps After Planning

Review this design with stakeholders/users
Prioritize features (MVP vs nice-to-have)
Set up development environment (API keys, test data)
Begin Week 1 implementation (Data Infrastructure)
Iterate based on testing feedback

END OF DESIGN DOCUMENT

This design provides a comprehensive blueprint for building a gold-specific trading system. The modular approach allows incremental development while maintaining compatibility with the existing TradingAgents framework.

22 KiB Raw Blame History

XAU (Gold) Trading System - Design Document

📋 Executive Summary

🎯 Objectives

🏗️ System Architecture

Current Framework Adaptation

📊 Component Design

1. Enhanced Analyst Team

A. Market Analyst (Technical) - XAU Specialization

B. Fundamentals Analyst - Macro-Focused for Gold

C. News Analyst - Gold-Specific Focus

D. Sentiment Analyst - COT & Positioning

2. Research Team - Gold Context

3. Trading Team - XAU Execution

4. Risk Management - Gold-Specific Risks

🔧 Technical Implementation Plan

Phase 1: Data Layer Enhancement

Phase 2: Agent Specialization

Phase 3: Configuration & Integration

Phase 4: Execution & Backtesting

📈 Gold-Specific Features

1. Macro Dashboard

2. COT Positioning Indicator

3. Multi-Timeframe Technical Analysis

4. Correlation Filters

🧪 Testing & Validation

Backtesting Strategy

Paper Trading

🚀 Implementation Roadmap

Week 1-2: Data Infrastructure

Week 3-4: Agent Specialization

Week 5: Integration & Configuration

Week 6: Testing & Refinement

Week 7-8: CLI & Deployment

📋 Key Decisions & Trade-offs

1. Fundamental Analysis Approach

2. Data Vendor Selection

3. Timeframe Focus

4. Research Depth

5. Real-time vs EOD Analysis

🎯 Success Metrics

Quantitative Metrics

Qualitative Metrics

📚 Resources & References

Gold Market Fundamentals

Macro Data Sources

Technical Analysis

🔄 Next Steps After Planning

22 KiB

Raw Blame History