> For the complete documentation index, see [llms.txt](https://docs.metacopier.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metacopier.io/features/pro-features/masaniello.md).

# Masaniello

The **Masaniello** copier feature is an advanced money management system that automatically calculates the **optimal position size** for each copied trade based on a predefined series plan.

It is designed to help you reach a **target profit goal** over a fixed number of trades by distributing risk across the series in a structured way. Masaniello does not generate trading signals, it only controls how large each copied trade is opened.

This feature is ideal for traders who want:

* **Structured risk management**
* A predefined series plan (e.g., *10 trades, 6 wins needed*)
* Automatic lot sizing per trade
* Optional safety breakers (max loss streak, cooldown, etc.)

## Overview

Masaniello works with the concept of a **series**:

* A series contains **N events** (trades), for example `10`.
* Within those N trades, you expect **W wins**, for example `6`.
* You define a bankroll allocation (for example `5% of equity`).
* You define a target profit goal (for example `+50% of bankroll`).

The system then generates an internal staking table and calculates the **next lot size** automatically for each new trade.

## How it works

When Masaniello is enabled:

1. A **bankroll** is reserved for the current series (e.g., 5% of equity).
2. The system calculates a series plan based on:
   * Total events (N)
   * Expected wins (W)
   * Expected payout model (R-multiple or payout factor)
   * Target profit
3. Each time a copied trade closes, Masaniello updates the series result:
   * **WIN**
   * **LOSS**
   * **BREAKEVEN** (optional)
4. Based on the updated state, the next trade size is calculated automatically.
5. The series resets automatically depending on your reset rules:
   * target reached
   * bankroll depleted
   * series completed

Masaniello can also run with **symbol-specific overrides**, meaning each symbol can use different series settings.

## Settings

<figure><img src="/files/aCavE0s8YaHOxRjyfD9j" alt=""><figcaption></figcaption></figure>

### Core Series Settings

* **Total events**
  * Defines how many trades belong to one Masaniello series.
  * Example: `10` means a series contains 10 trades.
* **Expected wins**
  * Defines how many wins you expect out of the total events.
  * Example: `6` wins out of `10`.
* **Bankroll percentage**
  * Defines how much of your account is reserved as bankroll for the series.
  * Example: `5%`.
* **Bankroll base**
  * Defines which account value is used for bankroll calculation:
    * `BALANCE`
    * `EQUITY`
    * `FREE_MARGIN`
* **Target profit percentage**
  * Defines the profit target relative to the bankroll.
  * Example: if bankroll = $500 and target profit = `50%`, the target is +$250.

### Expected Payout Model

Masaniello needs a model to estimate how much profit a WIN produces.

* **Payout model**
  * `R_MULTIPLE`: profit is modeled as R-multiple (risk-based).
  * `PAYOUT_FACTOR`: profit is modeled as fixed payout factor (binary-style).
  * `REALIZED_R`: optional advanced mode using realized R multiples from real trades.
* **Expected R multiple**
  * Only used when payout model = `R_MULTIPLE`
  * Example: `1.0` means your average win is +1R.
* **Expected payout factor**
  * Only used when payout model = `PAYOUT_FACTOR`
  * Example: `0.75` means a WIN earns +75% of the risked amount.
* **Expected loss R multiple**
  * Defines the expected average loss in R.
  * Default is `-1.0` meaning a full loss of risk per losing trade.

### Lot / Position Size Control

These settings ensure that Masaniello produces broker-compatible lot sizes.

* **Minimum lot size**
  * Smallest lot allowed, even if the calculation is smaller.
* **Maximum lot size**
  * Hard cap to avoid excessive exposure.
* **Lot step**
  * Defines the rounding increment for the calculated lot size.
  * Example: `0.01` for Forex.
* **Lot rounding mode**
  * Defines how lots are rounded:
    * `DOWN` (recommended)
    * `UP`
    * `NEAREST`

### Trade Outcome Policy (Win/Loss/Break-even)

Masaniello must classify each closed trade as a WIN, LOSS, or BREAKEVEN.

* **Outcome policy**
  * `THRESHOLD`: uses win threshold percentage and threshold base
  * `SIGN`: profit > 0 = WIN, profit < 0 = LOSS, profit = 0 = BREAKEVEN
  * `R_BASED`: WIN depends on realized R (advanced mode)
* **Win threshold percentage**
  * Defines how much profit is required to classify as a WIN.
  * Example: `0` means any positive profit is a WIN.
  * Example: `10` means profit must be at least 10% of the threshold base.
* **Win threshold base**
  * Defines what the threshold percentage is applied to:
    * `RISK`
    * `NOTIONAL`
    * `ABSOLUTE`
* **Exclude break-even trades**
  * If enabled, trades closed at 0 profit/loss do **not** consume an event in the series.

### Partial Close Handling (Multiple TPs / Manual partial close)

When trades are partially closed, Masaniello must decide how the outcome is counted.

* **Partial win policy**
  * `IGNORE`: partial closes are ignored until the trade is fully closed (recommended)
  * `COUNT_AS_WIN`: any partial close with profit counts as WIN
  * `COUNT_AS_LOSS`: any partial close with loss counts as LOSS
  * `PROPORTIONAL`: outcome is counted fractionally (advanced)

### Reset Rules & Safety Breakers

These rules define when a series resets and adds additional safety controls.

* **Reset on target reached**
  * Resets the series immediately once target profit is reached.
* **Reset on bankroll depleted**
  * Resets the series if the bankroll is depleted before reaching the target.
* **Auto reset on series complete**
  * Resets automatically after total events are completed.
* **Max consecutive losses**
  * Safety breaker: force reset after X consecutive losses.
  * `0` disables this rule.
* **Cooldown after reset (minutes)**
  * Prevents immediate restart after a reset (useful for prop firm rules or aggressive strategies).
  * `0` disables cooldown.

### Auto-Tuning (Historical Win Rate)

Masaniello can automatically adjust `expectedWins` based on historical performance.

* **Use historical win rate**
  * If enabled, expectedWins is adjusted using past trades.
* **Statistics look-back days**
  * Defines how many days are used for historical stats.
  * `0` means only current series trades are used.
* **Minimum trades for historical win rate**
  * Minimum number of closed trades required before auto-tuning is applied.
  * Below this threshold, manual expectedWins is used.
* **Min / Max expected wins**
  * Clamps the auto-calculated expected wins into a safe range.
* **Win rate smoothing factor**
  * Defines how fast the system adapts to new results (0..1).
  * Higher values update faster.

## Per-Symbol Configuration

You can define symbol-specific Masaniello settings.\
Symbol settings override the general settings.

This is useful when:

* You trade different symbols with different volatility
* You want different risk plans per symbol
* You want to isolate series per symbol

## Example Scenario

You define:

* Total events = `10`
* Expected wins = `6`
* Bankroll = `5%` of equity
* Target profit = `50%` of bankroll
* Payout model = `R_MULTIPLE`
* Expected R multiple = `1.0`

Result:

* Masaniello reserves a bankroll for the series
* It calculates a stake plan across 10 trades
* Each copied trade receives the correct lot size for the current step
* The series resets automatically when:
  * target is reached
  * series completes
  * bankroll is depleted (optional)

## Notes & Limitations

* Masaniello assumes trades can be classified clearly as WIN / LOSS / BE.
* For strategies with many parallel trades, you should decide whether series state is handled:
  * per symbol (recommended)
  * global per copier account
* If your master trades do not use stop loss values, prefer:
  * `PAYOUT_FACTOR`
  * or a conservative expectedRMultiple