metals-desk-os

# Metals Desk OS

An institutional-grade metals trading operating system for gold (XAU/USD) and silver (XAG/USD). This skill transforms the OpenClaw trader agent into a full prop-desk assistant with real-time analysis, automated execution, risk management, and performance tracking.

## When to Use This Skill

Use this skill when:
- Analyzing gold or silver market structure (ICT/SMC methodology)
- Generating trade signals with full entry/SL/TP plans
- Running automated or semi-automated trade execution via MT5
- Monitoring real-time risk, drawdown, and position management
- Tracking trading performance (win rate, expectancy, Sharpe, drawdown)
- Getting session-aware, macro-aware trading intelligence

## Architecture Overview

The system runs as a continuous event-driven pipeline:

```
PRICE FEED → SESSION ENGINE → STRUCTURE ENGINE → LIQUIDITY ENGINE →
MACRO ENGINE → BIAS ENGINE → VOLATILITY ENGINE → RISK ENGINE →
EXECUTION ENGINE → BROKER → PERFORMANCE ENGINE → DASHBOARD → ALERTS
```

All engines communicate through a central **Event Bus** (EventEmitter pattern). Every event is logged and can be monitored in real-time via WebSocket.

## Core Engines

| Engine | Purpose | Key Outputs |
|--------|---------|-------------|
| **Structure Engine** | Detects HH/HL/LH/LL, BOS, CHoCH, FVG, Order Blocks | Market structure, trend direction, structural shifts |
| **Liquidity Engine** | Finds equal highs/lows, stop clusters, session levels, sweeps | Liquidity pools, sweep confirmations |
| **Bias Engine** | Multi-timeframe directional bias with conviction scoring | HTF bias, intraday bias, conviction 0-100, alignment score |
| **Macro Engine** | Tracks DXY, US10Y yields, risk sentiment, news proximity | macro_bias (bullish/bearish/neutral gold), macro_risk level |
| **Volatility Engine** | ATR calculation, spike detection, regime classification | ATR, volatility regime (low/normal/high/extreme) |
| **Risk Engine** | Position sizing, drawdown monitoring, halt triggers | Lot size,...

# 🏛 Metals Desk OS v1.0.0

**Institutional Desk-Level Fully Automated Trading OS for XAU/USD and XAG/USD**

Architecture: Event-Driven, Risk-First, Multi-Engine AI Trading Desk

---

## 📁 File Structure

```
metals-desk-os/
├── index.js                    # Main entry point & orchestrator
├── package.json                # Dependencies
├── skill.json                  # OpenClaw skill manifest
├── manifest.json               # Runtime configuration
├── .env.example                # Environment template
│
├── core/                       # Trading engines
│   ├── bias-engine.js          # HTF/Intraday bias with conviction scoring
│   ├── structure-engine.js     # HH/HL/LH/LL, BOS, CHoCH, FVG, OB detection
│   ├── liquidity-engine.js     # Equal highs/lows, sweeps, pools
│   ├── execution-engine.js     # Trade signal generation & entry logic
│   ├── risk-engine.js          # Position sizing, drawdown, halts
│   ├── volatility-engine.js    # ATR, spike detection, regime classification
│   ├── macro-engine.js         # DXY, yields, risk sentiment
│   └── performance-engine.js   # Win rate, expectancy, Sharpe, drawdown
│
├── automation/                 # System automation
│   ├── event-bus.js            # Central nervous system (EventEmitter)
│   ├── price-feed.js           # Real-time price data from MT5/MetaAPI
│   ├── session-engine.js       # London/NY/Asian session tracking
│   ├── scheduler.js            # Cron-based daily tasks & reports
│   └── news-monitor.js         # Economic calendar & news blocking
│
├── broker/                     # Broker integration
│   ├── mt5-connector.js        # MetaAPI order execution
│   ├── risk-guard.js           # Active position monitoring & TP/SL management
│   └── order-manager.js        # High-level order lifecycle orchestration
│
├── dashboard/                  # Real-time dashboard
│   ├── websocket-feed.js       # WebSocket data broadcaster
│   ├── desk-dashboard.json     # Widget layout config
│   └── metrics.json...