# MT Account Auditor — Real Connection Setup Guide

## What this does

Your HTML dashboard (`mt_account_audit_REAL.html`) now talks to a lightweight
local Node.js server (`server.js`) which connects to real MT4/MT5 broker servers,
pulls all your trade history, and returns it to the dashboard.

Zero cloud fees. Runs on your own machine or a $5/month VPS.

---

## Architecture

```
Browser (your HTML)
       │  HTTP POST /api/connect
       ▼
server.js  (Node.js, port 3001)
       │
       ├─── MT5 WebAPI  →  broker server (port 443)
       ├─── MT4 WebAPI  →  broker server (port 443)
       └─── BridgeEA    →  local MT terminal files
```

---

## STEP 1 — Install Node.js

Download from https://nodejs.org (v18 or later)

Verify: `node --version`

---

## STEP 2 — Start the bridge server

```bash
cd mt-server
npm install
node server.js
```

You should see:
```
✅  MT Bridge Server running at http://localhost:3001
```

Leave this terminal open while using the dashboard.

---

## STEP 3 — Open the dashboard

Open `mt_account_audit_REAL.html` in your browser.

It auto-detects the running server. If the server is running, you'll see
**real data**. If not, it falls back to demo data with a warning banner.

---

## STEP 4 — Enter your account details

| Field           | What to enter                                      |
|-----------------|---------------------------------------------------|
| Broker name     | Your broker's name (e.g. `ICMarkets`, `Exness`)   |
| Server name     | Exact name from MT4/MT5 terminal (see below)      |
| Account ID      | Your account number / login                       |
| Investor pass   | Your READ-ONLY investor password (not master)     |
| Platform        | MT4 or MT5                                        |

### Finding your server name
1. Open MetaTrader
2. Go to **Tools → Options → Server**
3. The server name is shown there (e.g. `ICMarketsSC-Live04`)

### Getting your investor password
- **MT4**: Tools → Options → Server → Change Investor Password
- **MT5**: Tools → Options → Community → (or ask your broker)
- The investor password is **read-only** — it cannot place trades or withdraw

---

## How connection works (by broker type)

### Option A: MT5 WebAPI (most MT5 brokers — automatic)
MT5 exposes a standard WebAPI at `https://[your-server]/api/`.
The bridge tries this automatically. Works with:
- Exness, XM, IC Markets (MT5), Pepperstone, Admirals, and most others.

### Option B: MT4 WebAPI (select MT4 brokers)
Some MT4 brokers expose a REST WebAPI. The bridge tries known endpoints.
If yours isn't listed, add it to `adapters/mt4.js` → `BROKER_APIS`.

### Option C: BridgeEA (any broker, MT4 or MT5)
Run `BridgeEA.mq5` in your terminal as an Expert Advisor. It writes
account state to a file which the server reads. This works with **any broker**
and is the most reliable method.

#### Installing BridgeEA:
1. Copy `ea/BridgeEA.mq5` to your `MT5\MQL5\Experts\` folder
2. Open MetaEditor (F4 in MT5) and compile it
3. Drag it onto any chart
4. In EA settings, set `ApiSecret` to a password of your choice
5. Allow "Write files" in Tools → Options → Expert Advisors

---

## Common broker server names

| Broker           | MT4 Server                  | MT5 Server               |
|------------------|-----------------------------|--------------------------|
| IC Markets       | ICMarketsSC-Live04          | ICMarketsSC-MT5-1        |
| Exness           | Exness-MT4Real3             | Exness-MT5Real3          |
| XM               | XMGlobal-MT4 3              | XMGlobal-MT5 3           |
| Pepperstone      | Pepperstone-Edge-Live        | Pepperstone-MT5-Live     |
| FXCM             | FXCM-UKReal01               | —                        |
| FxPro            | FxPro.com-Real              | FxPro-MT5 Real           |
| Admirals         | AdmiralsGroup-Live          | AdmiralsGroup-MT5 Live   |
| ThinkMarkets     | ThinkMarkets-Live           | ThinkMarkets-MT5 Live    |

*Note: your exact server name may differ. Always check inside your MT terminal.*

---

## Running on a VPS (always-on access)

If you want the bridge server always available (not just when your PC is on):

```bash
# On a Ubuntu VPS (DigitalOcean, Linode, Vultr — ~$5/month)
sudo apt update && sudo apt install nodejs npm -y
git clone <your-repo> mt-server
cd mt-server && npm install

# Install PM2 to keep it running
npm install -g pm2
pm2 start server.js --name mt-bridge
pm2 save && pm2 startup
```

Then in your HTML, change:
```js
const BRIDGE_URL = 'https://your-vps-ip:3001';
```

---

## Data storage

All account data is saved as JSON files in `mt-server/data/`.
Files are named `{login}_{server}.json`.

Data is **never sent to any cloud** — everything stays on your machine.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "Bridge server offline" banner | Run `node server.js` and keep terminal open |
| Auth failed | Double-check investor password; confirm it's not the master password |
| "Cannot connect" error | Try BridgeEA method (Option C above); broker may block direct API |
| Server name not working | Copy exact name from MT terminal → Tools → Options → Server |
| CORS error in browser | Add your HTML origin to `ALLOWED_ORIGIN` in `.env` |