riskgate-ea-realcase/README.md

# riskgate-ea-realcase

**Risk gate EA real world use case**  
*MIT License*

---

## What is this?

`riskgate-ea-realcase` is a **real-world example Expert Advisor** that demonstrates how to integrate the [`@douglasrechia/riskgate-ea`](https://forge.mql5.io/DouglasRechia/riskgate-ea) client framework into a working MQL5 EA.

The EA monitors multiple currency pairs (EURUSD, GBPUSD, AUDUSD, NZDUSD), groups them by correlation magic number, and on each new bar computes an ATR-based stop loss and requests position sizing approval from an external risk management server before placing a trade.

This project is intended **only as an educational example** of how to build a real-case EA on top of the `riskgate-ea` package using KnitPkg. It is **not** meant to be a production-grade trading system.

## Prerequisites

To use this project, you will need:

1. [**MetaTrader 5**](https://www.mql5.com/) installed.
2. **KnitPkg CLI**: The KnitPkg package manager for MetaTrader. If you don't have it, you can install it by following the instructions in the [main KnitPkg repository](https://github.com/knitpkg-dev/knitpkg-mt.git).
3. **KnitPkg homepage**: See [https://knitpkg.dev](https://knitpkg.dev) for an overview and [https://docs.knitpkg.dev](https://docs.knitpkg.dev) for documentation.
4. A running **RiskGate server** (see [`@douglasrechia/riskgate-service-realcase`](https://forge.mql5.io/DouglasRechia/riskgate-service-realcase)) listening on `127.0.0.1:5555`.

---

## Features

- **Expert Advisor type** (`type: expert`) — compiled and attached to MetaTrader charts
- **ATR-based risk** — stop loss is computed as `ATR(14) × 4` on each new bar
- **Correlation groups** — EURUSD/GBPUSD share magic `1000`; AUDUSD/NZDUSD share magic `1001`
- **Server-gated entries** — no trade is placed without approval from the RiskGate server
- **Graceful offline handling** — logs an error and skips the trade if the server is unreachable
- **KnitPkg dependencies** — uses `@douglasrechia/riskgate-ea`, `@douglasrechia/calc`, and `@douglasrechia/bar`

---

## Getting started

### 1) Clone into MetaTrader `Experts` folder

```bash
# Go to your MetaTrader 'Experts' directory.
# Tip: in MetaEditor, right-click the `Experts` folder and choose "Open Folder".
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>\MQL5\Experts"

git clone https://forge.mql5.io/DouglasRechia/riskgate-ea-realcase.git
cd riskgate-ea-realcase
```

### 2) Install dependencies

```bash
kp install
```

### 3) Compile

```bash
kp compile
```

### 4) Run the EA

1. Start the RiskGate server (see the companion service [project](https://forge.mql5.io/DouglasRechia/riskgate-service-realcase)).
2. Restart MetaTrader so the Navigator refreshes.
3. Attach `RiskgateEaRealcase` to a chart for any of the supported symbols.
4. Check the Experts tab in the MetaTrader terminal for log output.

---

## How it works

On every new bar the EA:

1. Fetches the latest 20 bars via `BarMqlRates`.
2. Computes `risk = ATR(14) × 4`.
3. Sends a JSON payload to the RiskGate server:
   ```json
   { "symbol": "EURUSD", "sl_points": 120, "magic": 1000 }
   ```
4. If the server approves the request, opens a BUY order with the returned lot size, using `risk` as the stop loss distance and `risk × 8` as the take profit distance.

---

## License

This project is released under the **MIT License**. See `LICENSE` for details.

---

## Disclaimer

This code is provided **as-is**, for **educational purposes only**.  
No warranty (express or implied) is provided. Use at your own risk.