# Package riskgate-ea

**Risk gate EA framework**  
*MIT License*

---

## What is this?

`riskgate-ea` provides a **client-side framework** for Expert Advisors to communicate with an external risk management server via TCP sockets. The RiskGateClient handles connection management, automatic reconnection, timeout handling, JSON serialization, and configurable fallback policies when the server is offline.

**Server-side infrastructure**: The companion package `@douglasrechia/riskgate` provides the server infrastructure to create a **MetaTrader Service** that implements custom risk management rules. Together, these packages enable centralized risk management across multiple EAs.

This project is intended **only as an educational example** of how to structure, package, and compile **MQL5** code with KnitPkg. It is **not** meant to be a production-grade library for large-scale use.

## 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.

---

## Features

- **Package type** (`type: package`) — header-only library consumable by other KnitPkg projects
- **Transitive dependencies** — importing `riskgate-ea` also makes `@douglasrechia/logger`, `@douglasrechia/sockets`, and `@vivazzi/jason` available
- **MQL5 target** — designed for MetaTrader 5
- **Compile support** — `kp compile` compiles the unit test script(s)
- **Socket-based communication** — TCP client for connecting to risk management servers
- **Server infrastructure** — companion package `@douglasrechia/riskgate` provides server-side components for building MetaTrader Services
- **Automatic reconnection** — configurable reconnection attempts and intervals
- **Timeout handling** — configurable response timeout with fallback policies
- **Fallback policies** — reject orders or use fixed lot size when server is offline

---

## Installing as a dependency (recommended)

To add `riskgate-ea` to your KnitPkg EA:

```bash
kp add @douglasrechia/riskgate-ea
```

---

## Basic usage (example)

In the case your MQL5 project uses `include_mode: include`, include headers from the KnitPkg include directory:

```mql5
#include "../knitpkg/include/douglasrechia/riskgate-ea/RiskGateClient.mqh"
```

Because `riskgate-ea` depends on other packages, you can also include their headers as needed:

```mql5
#include "../knitpkg/include/douglasrechia/logger/Logger.mqh"
#include "../knitpkg/include/douglasrechia/sockets/Sockets.mqh"
#include "../knitpkg/include/vivazzi/JAson/JAson.mqh"
```

### Example Expert Advisor

```mql5
#include "../knitpkg/include/douglasrechia/riskgate-ea/RiskGateClient.mqh"

douglasrechia::RiskGateClient client("127.0.0.1", 5555);

int OnInit() {
   client.Connect();
   return(INIT_SUCCEEDED);
}

void OnDeinit(const int reason) {
   client.Disconnect();
}

void OnTick() {
   CJAVal signal, response;
   signal["symbol"]    = _Symbol;
   signal["side"]      = "BUY";
   signal["stop_loss"] = 12.34;

   bool online = client.RequestPositionSize(signal, response);

   if(response["approved"].ToBool())
      Print("Approved: lot=", response["lot"].ToDbl());
   else
      Print("Rejected: ", response["reason"].ToStr());
}
```

> Note: The exact header names and function signatures depend on the package headers. Use MetaEditor IntelliSense to browse the available APIs.

---

## Exploring the project locally (optional)

If you want to explore how a KnitPkg package with multiple dependencies is structured, clone the repository and run the standard workflow.

### 1) Clone into MetaTrader `Scripts` folder (example)

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

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

### 2) Generate autocomplete

```bash
# Generates autocomplete / IntelliSense support for MetaEditor.
# This step will also resolve dependencies required by the test scripts.
kp autocomplete
```

### 3) Compile

```bash
kp compile
```

---

## Running unit tests

Unit tests are implemented as a MetaTrader **Script**.

1. Compile the project.
2. Restart MetaTrader (so the Navigator refreshes).
3. Run the generated unit test script from the Navigator on any chart.
4. Check results in the MetaTrader console (Experts/Scripts tab, depending on your setup).

The compiled binary is placed under the project `bin/` directory (and appears in the Navigator under the corresponding compiled location after refresh).

---

## One-command download/build via the registry (optional)

You can also use `kp get` to query the registry for metadata and automatically download/build the latest stable version.

Example (run from your MetaTrader *Data Folder* root):

```bash
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"

kp get mql5 @douglasrechia/riskgate-ea
```

Restart MetaTrader afterward to refresh the Navigator, then run the unit test script as described above.

---

## 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.