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.