AUTHOR: Tony Mudau

Trade lifecycle: entries, exits, and SL/TP management

This document describes how the TFA Agents backend decides where to put stops and targets, when to open or close, and how open positions are managed over time. It maps behavior to the main modules: technical agent, orchestration agent, trade_lifecycle, execution agent, execution_guards, and app.config.

1. Architecture overview

The system is a pipeline, not a single monolith:

Important: The orchestration layer no longer fabricates SL/TP if the technical layer omits them. Invalid or zero SL/TP → the candidate is rejected (invalid_sl_tp_from_technical).

2. How SL and TP are set (before a trade is open)

2.1 Technical agent (source of truth)

In generate_trade_hypothesis (see technical_agent/main.py):

• Entry is chosen by calculate_entry_price (e.g. pullback vs breakout vs market) from OHLC and context.
• Risk distance is based on ATR and a small minimum relative to price:
  • stop_distance = max(atr * 1.5, price * 0.001).
• Take profit is a multiple of that distance (tp_mult from strategy mode, e.g. default vs htf_pullback).
• For a buy: stop_loss = entry - stop_distance, take_profit = entry + stop_distance * tp_mult.
• For a sell: the mirror.

So the first SL/TP is always anchored to the technical plan (ATR + entry), not to orchestration heuristics.

The hypothesis also exposes:

• pattern_win_rate — from pattern memory, used for EV and confidence floor later.

2.2 Orchestration (enrichment, not override)

In the per-symbol worker (_evaluate_symbol_worker):

• Entry uses the technical entry if positive; otherwise the current tick (ask for buy, bid for sell).
• If either stop_loss or take_profit is ≤ 0 → reject; there is no fallback to a % of price.
• Risk/reward is computed in price space (same as trade_lifecycle.risk_reward_ratio).
• EV gate (ev_gate_allows_entry): uses pattern_win_rate and RR. If ENTRY_REQUIRE_POSITIVE_EV is true, strongly negative expected R (below a small buffer) blocks the trade.
• Entry validation (validate_entry_proposal): see §3.
• Confidence is adjusted for MTF/reversal, then blended with EV (blend_confidence_with_ev), and compared to a floor that can rise when pattern_win_rate is weak (effective_entry_confidence_floor).

Orchestration does not replace technical SL/TP with ad-hoc percentages. It may filter a trade; it does not silently rewrite stops/targets to arbitrary deltas.

2.3 Risk / portfolio agents

Risk and portfolio agents can change size (e.g. lot) and other constraints; the intended design is that per-unit risk geometry (SL/TP prices from the technical hypothesis) remain the reference for that signal unless a future layer explicitly recomputes them (not the old % fallback).

3. Entry validation (why a signal might be dropped)

Module: trade_lifecycle.py — validate_entry_proposal.

Checks (configurable in app/config.py):

Rejection reasons are traced (e.g. risk_reward_below_minimum, entry_too_close_to_resistance, chasing_buy_near_range_top, entry_too_far_from_current_price).

3.1 Expected value (not only raw confidence)

• Per-unit EV in R: w * RR − (1 − w) where w = pattern_win_rate (clamped) and RR is the reward/risk ratio.
• If ENTRY_REQUIRE_POSITIVE_EV and EV is below about −0.02, the entry is blocked (expected_value_negative).
• blend_confidence_with_ev down-weights confidence when EV is negative; small positive adjustments when EV is healthy.

This ties “confidence” to a rough economic plausibility given stored pattern win rate—still not a guarantee of real-world calibration, but stricter than a single ≥ 0.65 threshold alone.

4. Execution path: when the order actually fires

4.1 Execution agent

• Market orders: MT5Tools.execute_market with the proposal’s SL and TP attached to the deal.
• Pending orders: execute_pending with entry, SL, and TP.
• execute_trade branches on execution_type (market vs pending) then runs guards.

4.2 evaluate_execution_guards (order of checks)

News does not block execution; it still informs orchestration (confidence, filters, LLM). Guards only check freshness and microstructure.

1. Bar age (signal freshness)

   • Last closed bar on the request timeframe must be younger than bar_age_multiplier × bar length (see EXEC_GUARD_BAR_AGE_MULT).

2. Optional micro-trend vs direction (if EXEC_GUARD_REQUIRE_TECH_AGREEMENT).

3. Slippage vs proposed entry

   • |ref − entry| / entry vs EXEC_GUARD_MAX_SLIPPAGE_PCT (ref = ask for buy, bid for sell).

4. Spread

   • (ask − bid) / mid must not exceed **EXEC_MAX_SPREAD_RATIO`.

5. Volatility spike

   • Last bar’s range divided by ATR(14) must not exceed EXEC_VOL_ATR_SPIKE_MULT (abnormal single-bar extension).

5. Open positions: SL/TP on the server and in memory

• MT5 returns positions with floating sl and tp. The backend normalizes these in parse_positions (common.py) so downstream logic can read sl and tp on each open position.
• Initial SL/TP on the order are what the technical layer intended; the trade management layer can tighten stops (breakeven, trail) or reduce size (partial) via new MT5 calls.

6. Holding positions: in-trade management (breakeven, trail, partial)

Function: apply_open_position_lifecycle in trade_lifecycle.py, called from exit management in the orchestration when evaluating each open position (after loading OHLC for that symbol).

Definitions:

• 1R in price uses the current open SL vs open price:
  • Buy: one_risk_price = price_open − sl (when sl is a valid buy stop).
  • Sell: sl − price_open when sl is above entry.
• Profit in R (profit_in_r): unrealized move along the trade divided by that 1R distance.

When enabled (defaults in app/config.py):

Implementation uses MT5Tools.modify_position_sltp and close_position_volume.

Caveats:

• If initial SL is 0 or invalid, 1R cannot be computed—management steps are skipped for that position.
• Partial-close deduplication is in-process; after restart, a duplicate partial is unlikely but possible if tickets repeat in edge cases.
• Tightening stops can increase stop-out rate in chop; tune TRADE_MGMT_* and ATR multiplier for your pairs.

7. Exits: strategies beyond broker TP/SL

Exit decisions are merged in this order of concern (see _run_exit_management):

1. In-trade lifecycle (above) — adjusts SL/TP or size before discretionary exit logic.

2. LLM + rules exit (llm_position_exit_decision in common.py)

   • Heuristics: e.g. technical direction opposes the position with sufficient confidence, or very negative floating P&L.
   • If OpenAI is configured, an LLM may output hold vs close with confidence.

3. Hard take-profit (account money)

   • From risk settings: if hard_take_profit_enabled and floating profit ≥ hard_take_profit_amount (account currency) → close (overrides as a full exit).

4. Time stop (bar-based)

   • time_stop_candles sets a max hold in bars per chart timeframe (e.g. M15: 72 bars ≈ 18h at 15m; M30: 36 bars; H1: 18 bars; short TFs: longer bar counts).
   • position_age_bars uses opened_at and timeframe bar length.
   • If age ≥ max and profit in R is still very low (scratch / drift), a time-based close is recommended.
   • A stricter case extends hold slightly (1.2×) with still weak R-multiple.
   • Executed closes can record close_reason time_stop in trade history when applicable.

5. Execution

   • ExecutionAgent.close_open_position sends a market close for the full remaining volume at the ticket.

Broker-level TP/SL still apply automatically on the server; the stack adds strategic flattening, risk caps, and time limits.

8. Configuration reference (app/config.py)

Tune spread and vol thresholds per symbol and broker (commissions, typical spreads).

9. End-to-end mental model

1. Technical builds entry + SL + TP (ATR-based) and pattern_win_rate.
2. Orchestration rejects bad geometry (missing SL/TP, R:R, EV, S/R, chase, deviance), then other agents and gates.
3. Execution guards block bad timing and conditions (stale bar, slippage, wide spread, vol spike; optional micro-trend).
4. MT5 holds the order with the passed SL/TP.
5. Lifecycle can move SL, trail, and partially close using R and ATR.
6. Exit manager can close on LLM/risk, hard P&L, or time stop, in addition to normal TP/SL hits.

This turns the system from a signal executor into a trade lifecycle with explicit entry quality, execution quality, and position management layers—each configurable and traceable in logs and execution_guard_events / traces.

10. File map

Last updated to match the trade-lifecycle implementation in the repository (entries, execution guards, post-open management, and time-based exits).