> 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/basic-features/spread-filter.md).

# Spread Filter

The **Spread Filter** feature blocks the copy of new positions when the current spread of the symbol exceeds a configured threshold at the moment the open is detected. This protects slave accounts from being filled at unfavorable conditions caused by short-lived spread widening (news, rollover, low-liquidity sessions, broker quote anomalies).

The filter applies **to position opens only**. Closes, partial closes, and SL/TP modifications are **always copied** regardless of the spread, so the slave is never left holding a position the master has already exited.

If the measured spread exceeds the threshold, the open is **blocked** and written to the copier log (symbol, master ticket, measured spread, configured mode and threshold). By default the blocked open is dropped immediately. If the spread filter's **Retry on block** setting is enabled, the open is treated as a failed open and re-evaluated through the copier's existing **Open retry** / **Open retry timeout** mechanism: the spread is re-checked on each retry and the open is copied as soon as it comes back under the threshold, or definitively dropped when the open-retry timeout elapses.

## How It Works

When a new master position is detected, MetaCopier:

1. Reads the current bid/ask of the symbol from the configured **source account** (master by default, optionally the slave) and computes the spread.
2. Compares it to the configured threshold (global or per-symbol).
3. If the spread is **within** the threshold, the open is copied normally.
4. If the spread **exceeds** the threshold, a log entry is written. If **Retry on block** is off (default), the open is dropped immediately. If **Retry on block** is on and the copier has **Open retry** enabled, the open is re-attempted (and the spread re-checked) until it passes or the **Open retry timeout** elapses.

## Threshold Modes

Each symbol (and the global default) defines how the threshold is interpreted:

* **Points**: an absolute spread limit in broker points. *Example:* `30` on EURUSD means the open is blocked if the spread on the source account is greater than 3.0 pips.
* **Percentage of price**: the spread limit expressed as a percentage of the current symbol price (`spread / price × 100`). The limit scales automatically with the instrument's price level, which is convenient for symbols where the price moves over a wide range (e.g. indices, metals, crypto). *Example:* `0.05` on XAUUSD at a price of `2,400` means the open is blocked if the spread exceeds `1.20` (= 0.05% × 2,400).

## Settings

* **Mode**: How the threshold is interpreted (`Points` or `Percentage of price`). Can be overridden per symbol.
* **Threshold**: The global spread limit applied to all symbols that do not have a per-symbol override. A value of `0` disables the global filter.
* **Source**:
  * **Master** (default): The spread is read from the master account's symbol at the moment the open is detected. This is the typical use case - filtering out trades opened during abnormal market conditions on the source signal.
  * **Slave**: The spread is read from the slave account's mapped symbol just before sending the copied open. This protects the slave from poor execution conditions on its own broker (e.g. a slave broker with significantly wider spreads than the master) but adds an extra tick lookup per copied open.
* **On missing price**: Defines what to do when the bid/ask of the symbol is not available on the source account at the time of the check (no recent tick, symbol not subscribed, market closed, broker quote feed temporarily missing). The spread can't be measured in that case, so a decision has to be made:

  * **Allow** (default): Let the open through and copy it normally (fail-open). Missing data is treated as "no evidence of an abnormal spread", which avoids dropping trades just because of a momentary tick gap.
  * **Block**: Drop the open the same way as a threshold violation (fail-closed). Recommended when the filter is used as a hard guard (e.g. prop firm or HFT setups) where copying without a measurable spread is unacceptable.

  In both cases the event is written to the copier log.
* **Retry on block**: Whether a spread-blocked open should be re-evaluated through the copier's existing open-retry mechanism instead of being dropped immediately.
  * **Off** (default): A blocked open is dropped right away, even if the copier has **Open retry** enabled. This keeps spread blocks decoupled from transport-error retries.
  * **On**: A blocked open is treated as a failed open. The copier-wide **Open retry** flag must also be enabled - otherwise nothing is retried. The spread is re-checked on each retry attempt; the open is copied as soon as it passes or definitively dropped when **Open retry timeout** elapses.
* **Per-symbol configuration**: Optionally define a different mode and threshold per symbol. Symbol-specific rules always take priority over the global setting. This is useful because spreads differ drastically between asset classes (e.g. tight on majors, wide on exotics and indices).

{% hint style="info" %}
The spread filter does not introduce its own retry timeout. When **Retry on block** is enabled, the retry window comes from the copier's **Open retry timeout** setting (see the **Copiers** section). Both **Retry on block** and copier-wide **Open retry** must be on for a spread-blocked open to be retried.
{% endhint %}

{% hint style="info" %}
The Spread Filter affects **opens only**. If the master closes or modifies SL/TP on a position, those events are always copied regardless of the current spread - the slave will never be left holding a position the master has already exited.
{% endhint %}