EA_with_Python/docs/MyProject/HITEntryEA_spec_en.md

# HITEntryEA Specification

## 1. Overview

`HITEntryEA.mq5` is the entry-only Expert Advisor. It runs the H4/H1 Python signal workflow, applies the M15 confirmation rules, and submits pending orders. It does not manage filled positions. Stop management, trailing, and time-based position exits are delegated to `HITPositionManagerEA.mq5`.

The two EAs coordinate through matching `_Symbol` and `input_entry_magic_number` / `input_managed_magic_number`. The operating assumption is a retail hedging account, and initialization fails on non-hedging accounts.

## 2. Indicators

- No standard or custom indicators are used.
- Confirmed H4/H1 OHLC data is exported to Python. The EA reads `trend_state.txt`, `target_prices.txt`, and `target_zones.txt`.
- M15 confirmation uses `CopyRates(_Symbol, PERIOD_M15, OHLC_START_SHIFT, M15_CONFIRM_BARS, rates)`.

## 3. Parameters

- `lot_size = 0.01`: Standard order volume.
- `spread_limit = 60`: Maximum allowed spread in points.
- `input_entry_magic_number = 10001`: Magic number assigned to pending orders.
- `input_slippage_points = 10`: Allowed order deviation in points.
- `input_position_limit = 10`: Limit for same-symbol/same-magic pending orders plus positions.
- `use_split_entry_zone = false`: Enables split entries from the H1 prediction zone.
- `split_entry_count = 3`: Number of split entry orders.
- `split_lot_mode = SPLIT_LOT_TOTAL`: Total-volume split or fixed-volume split.
- `input_cancel_retry_cooldown_seconds = 60`: Ticket-level retry cooldown after pending cancellation failures.
- `use_m15_entry_filter = true`: Enables M15 closed-bar confirmation.
- `input_entry_max_candidate_age_minutes = 120`: Maximum age for using an H1 candidate for new execution.
- `input_tp_multiplier = 1.25`: Expands the API TP distance from the entry price. Values below `1.0` are clamped to `1.0`, and values above `100.0` are clamped to `100.0`.
- `input_min_tp_points = 0`: Minimum final TP distance in points. `0` disables the floor.
- `input_max_tp_points = 0`: Maximum expanded TP distance in points. `0` disables the cap. The EA never makes the final TP closer than the API-provided TP distance.
- `input_range_breakout_guard_enabled = true`: Cancels adverse reversal Limit orders during range breakouts and temporarily blocks new ones.
- `input_range_breakout_guard_timeframe = PERIOD_M15`: Timeframe used by the range-breakout monitor.
- `input_range_breakout_lookback_bars = 20`: Closed-bar count used for range high/low and average range.
- `input_range_breakout_max_width_multiplier = 6.0`: Maximum allowed range width versus average range. `0` disables the width filter.
- `input_range_breakout_buffer_multiplier = 0.20`: Average-range multiplier used as the confirmed-breakout buffer.
- `input_range_breakout_near_multiplier = 0.50`: Average-range multiplier used as the pre-breakout proximity band.
- `input_range_breakout_body_multiplier = 1.50`: Required latest closed-bar body multiple for momentum warning.
- `input_range_breakout_cooldown_bars = 4`: Number of monitor-timeframe bars to block adverse Limit entries after detection.

## 4. Entry And Exit Conditions

- New pending orders are sent only after spread, H4 state, H1 candidate, M15 timing, price consistency, broker distance, volume, and same-symbol/same-magic limit checks pass.
- Before order submission, TP is recalculated from the distance between entry and the API TP, multiplied by `input_tp_multiplier`. Buy strategies place the final TP above entry, and Sell strategies place it below entry.
- Split entries recalculate the final TP separately for each slot, using that slot's entry price.
- Pending orders receive `input_entry_magic_number`.
- The entry EA cancels expired pending orders, pending orders that conflict with the refreshed H4 state, and stale split-entry pending orders.
- When the range-breakout guard is enabled, upward breakout warning/confirmation cancels existing T4 Sell Limit orders and blocks new T4 entries until cooldown expiry. Downward breakout warning/confirmation cancels existing T2 Buy Limit orders and blocks new T2 entries.
- H1 Python results, candidate timestamps, and stale split-pending cleanup are processed before the spread gate; excessive spread only blocks new order submission.
- Filled-position SL updates, trailing, and time-based exits are not performed by this EA.

## 5. Risk Management

- The order limit counts only pending orders and positions matching `_Symbol` and `input_entry_magic_number`.
- Python process markers, process IDs, done files, and timeouts are monitored to prevent duplicate launches and stale-result reuse.
- If a done file exists but the expected result file is missing, the EA clears the done/running state and marks the same workflow for retry on the next tick.
- If the API TP direction contradicts the Buy/Sell price rules, the EA does not repair it; the existing price-consistency checks skip the order.
- The range-breakout guard only touches pending orders matching `_Symbol` and `input_entry_magic_number`; upward breakouts cancel T4 Sell Limit only, and downward breakouts cancel T2 Buy Limit only.
- `OrderSend` return values and `MqlTradeResult.retcode` are checked and logged.
- Because the design assumes hedging accounts, per-ticket position management is handled by `HITPositionManagerEA.mq5`.

## 6. Unit Test Scope

- In the Strategy Tester, this EA is tested for pending-order creation, expired pending cancellation, and H4-state mismatch cancellation.
- Position management behavior is outside this EA's unit-test scope.
- Python linkage filenames include `_Symbol` and `input_entry_magic_number` to preserve reproducibility.

## 7. Changelog

- 2026-06-14: Added initialization failure on non-hedging accounts. Moved H1 result loading before spread gating, added retry recovery for done-without-result Python states, and removed the unused filled-position time-exit path from the entry EA side.
- 2026-06-13: Connected the range-breakout guard from `HIT-EA_refactor_ver6.mq5` to the entry EA, including T4 Sell Limit retreat on upward breakouts, T2 Buy Limit retreat on downward breakouts, and cooldown-based new-entry blocking.
- 2026-06-13: Added `input_tp_multiplier`, `input_min_tp_points`, and `input_max_tp_points` to expand API-derived TP distances for both standard orders and per-slot split entries.
- 2026-06-07: Split entry responsibilities from `HIT-EA_refactor_ver6.mq5`; moved SLTP panel and filled-position management responsibilities to `HITPositionManagerEA.mq5`.