xau-trader
by ArcadiaUZ
README.md
# xau-trader-agent
Agentic **XAUUSD** trading loop for MetaTrader 5 **demo** accounts, packaged as
an MCP server plus a DeepSeek Harness skill.
The model does the reading - Asia range, sweep quality, multi-timeframe FU/SFU/AFU supply zones,
bias, spread, news-free windows - and the code enforces the risk envelope: 0.5% per trade,
2% daily stop, 4% total stop, 5 trades a day, 1:5 RR, flat before swap. Everything that happens
is written to a journal, and a 21:00 report is generated automatically.

## What it does
| piece | description |
|---|---|
| **MCP server** | 19 tools: market data, Asia boxes, sweep state machine, zone stack, MTF bias, CVD proxy, TV-style PNG charts, manual drawings, one-tick decisions, journal and reports |
| **Agentic loop** | one tick = analysis -> decision -> guarded execution -> state -> journal -> next wake time |
| **Skill** | `skills/xau-trader/SKILL.md` tells the agent when to use the tools, the loop protocol, the rules and the pitfalls |
| **Guards** | demo-only whitelist, hard-blocked logins, dry-run by default, broker-side SL/TP on every entry |
## Quick start
```powershell
git clone https://github.com/ArcadiaUZ/xau-trader-agent.git
cd xau-trader-agent
.\scripts\install.ps1 -DemoLogin 12345678 # creates .venv, installs deps, writes .env
.\scripts\install-skill.ps1 # ~/.dsh/skills/xau-trader
.\scripts\register-mcp.ps1 # adds the xau-trader MCP server to DSH
```
Requirements: Windows, a running **MetaTrader 5** terminal logged into a **demo** account,
Python 3.10+ (3.12 tested), and DeepSeek Harness for the skill/loop integration.
Verify without trading:
```powershell
.\venv\Scripts\python.exe tests\loop_test.py # decision matrix, dry-run only
.\venv\Scripts\python.exe tests\mcp_client_test.py # stdio handshake + xau_status
.\venv\Scripts\python.exe -m trader.loop --no-render
```
## MCP tools
| group | tools |
|---|---|
| data / analysis | `xau_status`, `xau_candles`, `xau_analyze`, `xau_mtf`, `xau_risk_state` |
| charts | `xau_render` |
| drawings | `draw_rect`, `draw_trendline`, `draw_hline`, `draw_vline`, `draw_text`, `drawings_list`, `drawings_delete`, `drawings_clear` |
| loop | `xau_tick`, `xau_loop_state`, `xau_flat` |
| journal | `journal_append`, `xau_daily_report` |
## Risk rules (hard-coded, env-tunable)
| rule | default |
|---|---|
| risk per trade | 0.5% of balance |
| daily loss stop | 2% |
| total loss stop | 4% |
| max trades per day | 5 |
| RR | 1:5 |
| entries | 11:00 - 20:30 (UTC+5) |
| forced flat | 20:45 |
## Safety model
- `guard()` runs before **every** order: login must be whitelisted, account must be `DEMO`,
and trade must be allowed by the broker.
- `XAU_TRADER_BLOCKED` logins (prop / real accounts) raise before anything is sent.
- `live=false` (default) turns the whole execution path into a dry run - the order request is
built and logged, nothing is sent.
- Every entry carries a broker-side SL and TP, so an open position is protected even if the
agent stops running.
## Layout
```text
trader/ python package (config, mt5_io, engine, zones, render, drawings,
journal, auto, loop, cycle, mcp_server)
skills/xau-trader/ the DeepSeek Harness skill + references
scripts/ install.ps1, install-skill.ps1, register-mcp.ps1
tests/ loop_test.py, dry_run_test.py, mcp_client_test.py
docs/ SETUP.md, ARCHITECTURE.md, images
examples/ cordis.patch.yml snippet for DSH
```
## Docs
- [docs/SETUP.md](docs/SETUP.md) - installation, demo account, MCP registration, timers
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - modules, data flow, decision state machine
- [skills/xau-trader/SKILL.md](skills/xau-trader/SKILL.md) - the agent-facing workflow
## Disclaimer
Educational tooling for **demo** accounts. Forex/gold trading carries substantial risk; past
patterns (Asia sweep, supply zones) are not guarantees. The authors take no responsibility for
losses, including on prop-firm accounts. Never point this code at an account you cannot afford
to lose - the whitelist and blocked list exist for that reason.
## License
MIT