# XAU Data Layer - Quick Reference Card

**One-page cheatsheet for XAU trading data**

---

## 🚀 Quick Start

```bash
# 1. Setup
cp .env.example .env
# Add FRED_API_KEY to .env (get free at fred.stlouisfed.org)

# 2. Test
python test_xau_data_layer.py

# 3. Use in code
from tradingagents.dataflows.fred_api import get_dxy_data
from tradingagents.dataflows.cot_data import get_cot_positioning
from tradingagents.dataflows.etf_flows import get_gold_etf_flows
```

---

## 📊 Data Sources at a Glance

| Source | What It Provides | Why It Matters | Key Metric |
|--------|-----------------|----------------|------------|
| **FRED** | DXY, yields, CPI, VIX | Macro drivers | DXY ↓ = Gold ↑ |
| **COT** | Futures positioning | Contrarian signals | >90th %ile = reversal |
| **ETF** | GLD/IAU flows | Institutional sentiment | Inflows = bullish |
| **Correlation** | Asset relationships | Trade filters | Gold-DXY: -0.75 |

---

## 🔑 Essential Functions

### Macro Data (FRED)
```python
from tradingagents.dataflows.fred_api import *

# Most important for gold
get_dxy_data(start, end)           # US Dollar Index
get_real_yields(start, end)        # Real yields (gold's opportunity cost)
get_inflation_data(start, end)     # CPI, PCE inflation metrics

# Other macro
get_fred_series("VIX", start, end)        # Risk sentiment
get_fred_series("FED_FUNDS", start, end)  # Fed rate
get_fred_series("10Y_YIELD", start, end)  # Treasury yield
```

### Positioning Data
```python
from tradingagents.dataflows.cot_data import *
from tradingagents.dataflows.etf_flows import *

# COT (weekly)
get_cot_positioning("GOLD", start, end)
analyze_cot_extremes(current_date, lookback_years=3)

# ETF flows (daily)
get_gold_etf_flows("GLD", start, end)
get_gold_etf_flows("IAU", start, end)
get_gold_etf_summary(start, end)
```

### Correlation Analysis
```python
from tradingagents.dataflows.correlation_tools import *

# Quick correlation
calculate_asset_correlation(gold_csv, dxy_csv, window_days=90)

# Comprehensive analysis
analyze_gold_macro_correlations(gold_csv, dxy_csv, yields_csv, vix_csv)

# Regime detection
check_correlation_regime(gold_csv, dxy_csv)
```

---

## 💡 Gold Trading Decision Framework

### 1. Macro Environment Check
```python
✅ BULLISH SETUP:
- DXY falling (USD weakness)
- Real yields negative (no opportunity cost)
- CPI rising (inflation hedge demand)
- VIX elevated (safe-haven bid)

❌ BEARISH SETUP:
- DXY rallying (USD strength)
- Real yields rising (bonds attractive)
- CPI falling (no inflation fears)
- VIX low (risk-on, equities preferred)
```

### 2. Positioning Check (Contrarian)
```python
⚠️ EXTREME LONGS (>90th percentile):
- Large specs heavily long in COT
- GLD holdings at multi-year highs
→ Crowded trade, potential reversal

💡 EXTREME SHORTS (<10th percentile):
- Large specs heavily short
- GLD outflows for weeks
→ Washed out, potential bottom
```

### 3. Correlation Filter
```python
if gold_dxy_corr < -0.6:
    # Healthy relationship
    if dxy_falling:
        increase_conviction()
    else:
        reduce_size()
else:
    # Correlation breakdown
    identify_new_driver()  # Geopolitics? Inflation surprise?
```

---

## 📈 Expected Gold Correlations

| Indicator | Expected Corr | Strength | Interpretation |
|-----------|--------------|----------|----------------|
| DXY | **-0.75** | Strong | USD ↑ → Gold ↓ |
| Real Yields | **-0.85** | Very Strong | Yields ↑ → Gold ↓ |
| VIX | **+0.40** | Moderate | Fear ↑ → Gold ↑ |
| SPY | **-0.20** | Weak | Stocks ↑ → Gold ↓ |
| CPI | **+0.60** | Moderate | Inflation ↑ → Gold ↑ |

---

## 🎯 Key Gold Levels & Thresholds

### Real Yields
- **< 0%**: Structural tailwind (no cost to hold gold)
- **0-1%**: Neutral
- **> 1%**: Headwind (bonds more attractive)

### DXY Levels (example - update based on current levels)
- **< 100**: Weak USD, gold bullish
- **100-105**: Neutral zone
- **> 105**: Strong USD, gold bearish

### COT Positioning (Net Long)
- **> 200k contracts**: Extremely bullish (contrarian bearish)
- **50k-150k**: Normal range
- **< 0 (net short)**: Extremely bearish (contrarian bullish)

### GLD Holdings
- **> 1000 tonnes**: Very high investor interest
- **800-1000 tonnes**: Elevated interest
- **< 800 tonnes**: Lower interest

---

## 🔧 Common Patterns

### Pattern 1: Macro Tailwind Alignment
```
DXY falling + Real yields negative + CPI rising
→ STRONG BULLISH (all factors aligned)
```

### Pattern 2: Divergence (Reversal Signal)
```
Gold rising + GLD outflows + COT extreme longs
→ DISTRIBUTION, potential top
```

### Pattern 3: Correlation Regime Change
```
Gold-DXY correlation weakens from -0.8 to -0.3
→ Check for new driver (geopolitics, inflation surprise)
```

---

## 🧪 Testing Checklist

```bash
# Quick validation
python test_xau_data_layer.py

# Should see:
✅ FRED API tests PASSED
✅ COT data tests PASSED
✅ ETF flows tests PASSED
✅ Correlation tools tests PASSED
✅ Integration test PASSED
```

---

## 🐛 Troubleshooting

| Error | Solution |
|-------|----------|
| `FRED API key required` | Add `FRED_API_KEY` to `.env` |
| `Rate limit exceeded` | Wait 1 minute, retry (120 req/min limit) |
| `No data available` | Check date format (YYYY-MM-DD) |
| `Correlation calculation failed` | Ensure date ranges overlap |

---

## 📚 Resources

- **FRED Data**: https://fred.stlouisfed.org/
- **COT Reports**: https://www.cftc.gov/MarketReports/CommitmentsofTraders/
- **GLD Holdings**: https://www.spdrgoldshares.com/
- **Design Doc**: `XAU_SYSTEM_DESIGN.md`
- **Full Guide**: `XAU_DATA_LAYER_README.md`

---

## 🎯 Next Phase Preview

**Phase 2**: Create XAU-specific agents that USE this data:

1. **XAU Macro Analyst** → Uses FRED data
2. **XAU Positioning Analyst** → Uses COT + ETF data
3. **XAU Market Analyst** → Uses correlations for filtering
4. **XAU News Analyst** → Monitors geopolitical catalysts

---

**Quick Start Example**:
```python
from tradingagents.dataflows.fred_api import get_dxy_data, get_real_yields
from tradingagents.dataflows.etf_flows import get_gold_etf_flows

# Check macro environment for gold trade
dxy = get_dxy_data("2024-01-01", "2024-05-10")
yields = get_real_yields("2024-01-01", "2024-05-10")
flows = get_gold_etf_flows("GLD", "2024-01-01", "2024-05-10")

# Decision:
# If DXY ↓ + Real Yields < 0 + GLD Inflows → BULLISH
```

---

**Phase 1 Status**: ✅ COMPLETE - All data sources ready for agent integration!