UC_4.10.1: Soft Breach — Daily Loss Limit Hit

---

Document References

---

1. Overview

2. Trigger

Execution gateway (Rithmic / MT5 / TraderEvolution) natively evaluates and enforces: Net_P&L ≤ −Daily_Loss_Limit

Formula:

Daily_Loss_Limit = Absolute_Stop_Loss × Daily_Loss_Ratio (positive value), where:

• Absolute_Stop_Loss = Notional × SIM_stop_percent (Zapier Table C, default 7.5%, flat rate, all SIM tiers — Ref: [CHR-49], see BR_4.10.1.6)
• Daily_Loss_Ratio = 1/3 (Zapier Table C)
• Notional = fixed SIM capital tier ($25,000 / $50,000 / $150,000 for Level 1/2/5)

Worked example (SIM Level 1, $25,000 notional):

• Step 1 — Absolute_Stop_Loss: $25,000 × 0.075 = $1,875
• Step 2 — Daily_Loss_Limit: $1,875 × 1/3 = $625 → breach fires when Net_P&L <= −$625

SIM uses a flat SIM_stop_percent (Zapier Table C, default 7.5%) regardless of level tier.

Rounding rule (Ref: CR-13)

Net P&L definition:

Net_P&L = Realized P&L + Unrealized P&L

• Sourced from ACCOUNT_METRICS WebSocket stream (throttled at 1000ms). Fields: balance, equity, open_pnl, realized_pnl
• P&L does NOT include platform fees, data feed fees, or commissions — tracked separately. Breach check uses trade-execution P&L only.

On breach — 3-step sequence (in order):

1. Flatten — All open positions force-closed at market. All working orders cancelled. No retry
2. Lock — Account set to Read-Only on execution gateway.
3. Reset — Account unfreezes at next fixed reset_time (Forex: 16:00 CST, Monday–Friday; Futures: 17:00 CST Exchange Reset).

Positions are flattened before lock — zero open positions during soft-lock.

3. Pre-conditions

• Trader has an active SIM account (Status = Active_SIM)
• Middleware maintains a persistent connection to the execution gateway via WebSocket
• Net_P&L is tracked in real-time via ACCOUNT_METRICS stream (from the execution gateway)

4. Post-conditions

Immediate (T+0 — at breach):

• Flatten: All open positions force-closed at market. All working orders cancelled. No retry
• Lock: Trading/execution account set to Read-Only on execution gateway. (Note: Auth0 / dashboard login account is NOT affected — trader can still log in and view dashboard, charts, P&L, journal,...)
• DAILY_LIMIT_BREACH WebSocket event fired to frontend
• Frontend renders "Daily Limit Reached" overlay on Dashboard — see BR_4.10.1.1.
• Account Status does NOT change — remains Active_SIM. POST /fail-challenge NOT called.

At next reset_time (fixed daily clock):

• Daily P&L counter reset AND soft lock lifted simultaneously.
• Futures: reset_time fixed at 17:00 CST daily ("Exchange Reset")
• Forex: reset_time fixed at 16:00 CST (17:00 EST), Monday–Friday
• Friday breach (Forex): reset_time (16:00 CST) does not fire on Saturday/Sunday (market closed). If the breach occurs on a Friday, the soft lock persists through the weekend and lifts automatically at Monday's 16:00 CST reset.

If trader never breaches:

• Soft lock / unfreeze mechanism never activates.

5. Basic Flow

Architecture note: Daily Loss Limit is calculated and enforced natively by the execution gateway (Rithmic / MT5 / TraderEvolution) — NOT by middleware. Middleware only relays state to the frontend via WebSocket; not routed through Zapier.

Step 1 — Real-time P&L monitoring:

Middleware listens to the ACCOUNT_METRICS stream (throttled at 1000ms) from the execution gateway. The gateway itself evaluates Net_P&L ≤ −Daily_Loss_Limit and enforces the breach natively.

Step 2 — Breach detected → 3-step sequence (Flatten → Lock → Reset):

1. Flatten: All open positions force-closed at market. All working orders (stop-loss, take-profit) cancelled. No retry.
2. Lock: Trading/execution account set to Read-Only on execution gateway. Auth0/dashboard account unaffected
3. (Reset is automatic at next fixed reset_time — see Step 5)

Step 3 — Fire WebSocket event (Sotatek can modify if needed):

Middleware emits DAILY_LIMIT_BREACH to the frontend:

Step 4 — Frontend renders "Daily Limit Reached" overlay:

• Overlay displayed on Dashboard — see BR_4.10.1.1 and §9.1
• Daily-loss progress bar shows fully maxed
• Trader can still view dashboard, charts, P&L, journal — the Auth0/dashboard session is unaffected; only trading account order-entry is locked
• All other screens (Account, Settings, etc.) render completely normally

Step 5 — Reset time reached → Automatic unlock:

At the trader's fixed reset_time (Forex 16:00 CST / Futures 17:00 CST):

1. Daily P&L counter reset
2. Soft lock lifted
3. Frontend overlay dismissed
4. Both reset and unlock occur simultaneously

6. Alternative Flow

• [Breach occurs within seconds of the fixed reset_time]

  • System still executes Steps 2–4 (flatten + soft lock + overlay) as normal.
  • Within seconds, the fixed reset_time is reached → soft lock lifts and counter resets.
  • UX: Trader sees overlay appear briefly then disappear. Overlay is guaranteed to display at least once — shown when navigating to or reloading the Dashboard while soft lock is active.
  • Treated as a harmless edge case; no special handling required.

7. Exceptional Flow

• [Market halt occurs during soft lock]

  • A market halt does not affect the fixed reset_time. The soft lock lifts at the next scheduled reset_time (Forex 16:00 CST / Futures 17:00 CST) regardless of any concurrent market halt.

8. Business Rules

BR_4.10.1.1: Soft Lock Overlay — Temporary Until Reset Time

• When DAILY_LIMIT_BREACH fires, the "Daily Limit Reached" overlay is displayed immediately on the Dashboard. For overlay content (Header, Body, CTA copy), see §9.1.
• Clicking "Acknowledge" dismisses the overlay visually only — the soft lock remains active until the fixed reset_time. Acknowledging does NOT unlock trading.
• The overlay re-appears each time the trader lands on the Dashboard while the soft lock is still active: on initial login, on page reload, and when switching back to Dashboard from another sidebar menu.
• Scope: Dashboard overlay only. All other screens (Account, Settings, etc.) render completely normally during soft lock.

BR_4.10.1.2: Account Isolation — Single Asset Class Per Account

• A trader's account is either Futures OR exclusively Forex — mixed-class trading within the same account is not permitted by the system architecture.
• Therefore reset_time in the DAILY_LIMIT_BREACH payload is always the single fixed value for that account's designated asset class (Forex: 16:00 CST / Futures: 17:00 CST).

BR_4.10.1.4: Execution Gateway — Flatten Mechanism

• When Daily Loss Limit is breached, all open positions are force-closed at market, all working orders cancelled. No retry.
• Futures — Rithmic (SIM):
  • 'Suspend Trading' via Rithmic Paper Trading Gateway
• Forex — MT5 (SIM):
  • API: MT5 Manager API 'Disable/Read-Only'
  • Flatten: C++ MT5 Plugin (Sotatek-built) → flattens positions on the SIM-provisioned MT5 account
• Forex — TraderEvolution (SIM):
  • TraderEvolution Admin API 'Lock/Read-Only'

BR_4.10.1.5: Hard Breach Supersedes Soft Breach

• If both Daily_Loss_Limit AND Absolute_Stop_Loss (Hard Breach threshold, Ref: UC_4.10.2 §2 Trigger) thresholds are crossed simultaneously, emit ONLY LEVEL_STOP_BREACH. DAILY_LIMIT_BREACH is suppressed.
• Daily Loss Limit alone never terminates an account.
• Daily Loss Limit breach (Net_P&L ≤ −Daily_Loss_Limit) is a soft pause only: no Status change, no POST /fail-challenge.
• Applies to all levels including Level 9+ and Founding Mentor.

BR_4.10.1.6: SIM_stop_percent — Dynamic Configuration

• SIM_stop_percent is NOT hardcoded. It is read dynamically from Zapier Table C.
• Default value: 7.5%. Operations can change this at any time without code deployment.
• This variable is shared with Hard Breach — same value drives both Daily_Loss_Limit (this UC) and Absolute_Stop_Loss (Ref: UC_4.10.2 §2 Trigger).
• (Ref: [CHR-49])

9. Screen Description and Business Rules

9.1 Soft Breach Overlay

Wireframe reference: Soft breach modal.png

---

Changelog