Editing Component:Trade Execution

= Component: Trade Execution Engine =

'''File:''' <code>trade_execution_engine.py</code><br/>
'''Layer:''' 5 (Final)<br/>
'''Lines:''' 822<br/>
'''Code:''' [https://github.com/stoic97/plus_ev_code_base/blob/rikk_mtf_backtest001/services/backtest/src/components/trade_execution_engine.py View Source]

----

== Purpose ==

Answers the question: '''"How do we execute and manage the trade to maximize profit?"'''

This component is the executor. It takes signals from Layer 4 and:
# Converts signals to trades with realistic slippage
# Monitors open positions (stop, target, time)
# Manages stops dynamically (breakeven, trailing)
# Calculates complete P&L with all costs

----

== Trading Market Principle ==

'''"Let winners run, cut losers short. Protect profits once you have them."'''

* Breakeven stop = protect capital once trade is working → move stop to entry at 25pt profit
* Trailing stop = let winners run → trail stop behind price using ATR
* Time exit = don't hold losing trades forever → 8 hour maximum
* Slippage modeling = realistic execution → winners don't fill perfectly either

----

== Trade Lifecycle ==

<pre>
        ┌───────────────────────────────────────┐
        │  Signal from Layer 4                  │
        │  (Direction, Entry, Stop, Target)     │
        └───────────────────────────────────────┘
                         │
                         ▼
        ┌───────────────────────────────────────┐
        │  ENTRY EXECUTION                      │
        │  • Add entry slippage (1-2 pts)       │
        │  • Calculate costs (commission + CTT) │
        │  • Create Trade object                │
        └───────────────────────────────────────┘
                         │
                         ▼
        ┌───────────────────────────────────────┐
        │  POSITION MANAGEMENT (per bar)        │
        │                                       │
        │  1. Update MFE/MAE tracking           │
        │  2. Check breakeven activation (25pt) │
        │  3. Update trailing stop (ATR-based)  │
        │  4. Check stop hit                    │
        │  5. Check target hit                  │
        │  6. Check time exit (8 hours)         │
        └───────────────────────────────────────┘
                         │
                         ▼
        ┌───────────────────────────────────────┐
        │  EXIT EXECUTION                       │
        │  • Add exit slippage (stop=2pt, TP=0.5pt)│
        │  • Calculate final P&L                │
        │  • Record exit reason                 │
        └───────────────────────────────────────┘
</pre>

----

== Two-Phase Stop Management ==

=== Phase 1: Breakeven Stop ===

Once trade is profitable by 25 points, move stop to entry price + buffer:

<pre>
IF current_profit >= 25 points:

    LONG:  stop = entry_price + 2 (buffer)
    SHORT: stop = entry_price - 2 (buffer)
</pre>

'''Purpose:''' Lock in a no-loss trade (or small profit with buffer).

=== Phase 2: Trailing Stop ===

After profit exceeds activation threshold, trail stop behind price:

<pre>
Trailing Distance = ATR × 2.0 (minimum 15 points)

LONG:
    IF profit >= 20 points:
        new_stop = current_high - trailing_distance
        IF new_stop > current_stop:
            current_stop = new_stop  // Only moves UP

SHORT:
    IF profit >= 20 points:
        new_stop = current_low + trailing_distance
        IF new_stop < current_stop:
            current_stop = new_stop  // Only moves DOWN
</pre>

'''Purpose:''' Let winners run while protecting accumulated profit.

----

== ATR Calculation ==

ATR (Average True Range) measures volatility for adaptive trailing:

<pre>
True Range = max(
    high - low,
    |high - previous_close|,
    |low - previous_close|
)

ATR = average(True Range over 14 bars)

Trailing Distance = ATR × 2.0
</pre>

'''Effect:'''
* High volatility → wider trailing stop (more room to breathe)
* Low volatility → tighter trailing stop (protect more profit)

----

== Slippage Model ==

Realistic slippage based on market conditions:

=== Entry Slippage ===

<pre>
entry_slippage = base (1.0 pt)
               + position_impact (0.1 × lots, capped at 2.0)
               + volatility (0.5 pt)

Minimum: 0.5 points
</pre>

=== Exit Slippage ===

{| class="wikitable"
|-
! Exit Type !! Slippage !! Reason
|-
| Stop Loss || 2.0 points || Panic selling, worse fills
|-
| Take Profit || 0.5 points || Limit order, better fills
|-
| Time Exit || 0.0 points || Market order at close
|}

----

== MFE/MAE Tracking ==

Tracks Maximum Favorable and Adverse Excursion for each trade:

{| class="wikitable"
|-
! Metric !! What It Measures !! Usage
|-
| '''MFE''' || Best profit point reached during trade || Entry timing quality
|-
| '''MAE''' || Worst loss point during trade || Stop placement optimization
|}

<pre>
LONG:
    MFE = max profit seen = (highest_high - entry) × 100 × lots
    MAE = max loss seen = (lowest_low - entry) × 100 × lots

SHORT:
    MFE = max profit seen = (entry - lowest_low) × 100 × lots
    MAE = max loss seen = (entry - highest_high) × 100 × lots
</pre>

----

== Exit Conditions ==

Trades exit when any condition is met (checked in order):

{| class="wikitable"
|-
! Priority !! Condition !! Exit Price !! Reason Code
|-
| 1 || Stop hit || stop_price - slippage (LONG) || "stop"
|-
| 2 || Target hit || target_price - slippage (LONG) || "target"
|-
| 3 || Time limit (8 hours) || current_close || "timeout"
|}

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Value !! Description
|-
| <code>base_slippage_points</code> || 1.0 || Base entry slippage
|-
| <code>market_impact_factor</code> || 0.1 || Slippage per lot
|-
| <code>max_market_impact_slippage</code> || 2.0 || Cap on position slippage
|-
| <code>stop_loss_slippage</code> || 2.0 || Additional slippage on stops
|-
| <code>take_profit_slippage</code> || 0.5 || Reduced slippage on targets
|-
| <code>max_holding_period_minutes</code> || 480 || 8 hours max holding
|-
| <code>enable_trailing_stop</code> || True || Enable trailing stop
|-
| <code>trailing_stop_method</code> || "ATR_MULTIPLE" || ATR-based or fixed
|-
| <code>atr_period</code> || 14 || ATR lookback period
|-
| <code>atr_multiplier</code> || 2.0 || Trailing = ATR × 2
|-
| <code>enable_breakeven_stop</code> || True || Enable breakeven
|-
| <code>breakeven_activation</code> || 25.0 || Points profit to activate
|-
| <code>breakeven_buffer</code> || 2.0 || Buffer above/below entry
|-
| <code>max_concurrent_trades</code> || 3 || Maximum open positions
|}

----

== Output ==

'''Trade Object (after exit):'''
{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>entry_price</code> || float || Actual entry (with slippage)
|-
| <code>exit_price</code> || float || Actual exit (with slippage)
|-
| <code>exit_reason</code> || str || "stop", "target", "timeout"
|-
| <code>gross_pnl_inr</code> || float || P&L before costs
|-
| <code>net_pnl_inr</code> || float || P&L after commission + CTT
|-
| <code>brokerage_cost</code> || float || Commission paid
|-
| <code>tax_cost</code> || float || CTT paid
|-
| <code>max_favorable_excursion_inr</code> || float || Best P&L during trade
|-
| <code>max_adverse_excursion_inr</code> || float || Worst P&L during trade
|-
| <code>current_stop_price</code> || float || Final stop (after trailing)
|}

----

== Dependencies ==

'''Upstream:'''
* [[Component:Signal_Generation|signal_generation_trade_management.py]] - Provides signals to execute

'''Uses:'''
* SignalGenerationTradeManagement.execute_signal() - For entry
* SignalGenerationTradeManagement.close_trade() - For exit

----

== Quick Reference ==

{| class="wikitable"
|-
! Event !! Action
|-
| New signal received || Execute with slippage, create trade
|-
| Profit reaches 25pt || Move stop to breakeven (entry + 2pt)
|-
| Profit reaches 20pt || Start trailing stop (ATR × 2)
|-
| Price hits stop || Exit with 2pt slippage, reason="stop"
|-
| Price hits target || Exit with 0.5pt slippage, reason="target"
|-
| 8 hours elapsed || Exit at market, reason="timeout"
|-
| Higher high (LONG) || Trail stop up if trailing active
|-
| Lower low (SHORT) || Trail stop down if trailing active
|}

----

[[Category:Components]]
[[Category:Layer 5]]