administration:propfirm_rules [Documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PropFirm Account Rules ======

PropFirm Account Rules let a firm enforce proprietary-trading ("prop firm") risk rules on individual accounts, evaluated continuously by the T4 Account Handler. The first available rule is the **Trailing Drawdown**: the account tracks a high-water mark (HWM), and if the account's net liquidation value falls to the trailing floor, T4 liquidates all positions, cancels all working orders, and disables the account.

The rule formula:

  Breach when:  NLV <= Min( HWM - Drawdown, Starting Balance )

  * The HWM only ever moves up. It is reset only by an [[#resetting_an_account_epoch_bump|epoch bump]].
  * The floor trails the HWM but is **capped at the Starting Balance** — once a trader is up by more than the drawdown amount, the floor stops tightening, and from then on the rule works to stop the account out at its starting balance rather than below it.
  * Costs charged by auto-liquidation fills are excluded from the rule's NLV, so a liquidation's own fees do not count toward the breach calculation (see [[#auto-liquidation_cost_exclusion|cost exclusion]]).

<note important>
The rule controls when T4 **attempts** enforcement — it does not guarantee an account outcome. Breaches are enforced through standard [[administration:administration_auto_liquidation|Auto Liquidation]] market orders, so normal auto-liquidation behavior applies: fills are subject to slippage, gaps, price limits, and market availability, and the realized balance after a breach can end up below the calculated floor. The HWM and floor figures on this page describe the rule's calculation, not a promised result. The terms of the T4 EULA apply.
</note>

===== Requirements =====

^ Requirement ^ Detail ^
| Account Mode | Must be **Auto Liq**. |
| Account Fees | Must be configured (not //None//) — the rule needs T4-calculated fees. |
| Starting Balance | ''PropFirmStartingBalance'' must be greater than 0. |
| Server | The account's Account Handler must run the prop-firm engine (arranged by CTS). |

===== Configuration =====

Two fields on the account (set via the Admin API account endpoints, or the Admin Portal where available):

^ Field ^ Meaning ^
| ''PropFirmStartingBalance'' | The plan size. Seeds the HWM and caps the trailing floor. |
| ''PropFirmRulesJSON'' | The rules document (below). Saving it with a null/empty value preserves the existing document; the explicit clear is ''{"Rules":[]}''. |

The rules document:

<code json>
{
  "SchemaVersion": 1,
  "Epoch": 1,
  "Rules": [
    {
      "Type": "TrailingDrawdown",
      "RuleIndex": 0,
      "Enabled": true,
      "Params": {
        "DrawdownAmount": 2000,
        "Variant": "EndOfDay"
      }
    }
  ]
}
</code>

^ Parameter ^ Values ^ Meaning ^
| ''Epoch'' | integer | Version counter for the rule state. Incrementing it resets the rule (see below). |
| ''Enabled'' | true/false | A disabled rule is not evaluated and keeps no state. |
| ''DrawdownAmount'' | > 0 | Drawdown as a dollar amount. **Exactly one** of ''DrawdownAmount'' / ''DrawdownPercent'' must be set. |
| ''DrawdownPercent'' | 0–100 | Drawdown as a percentage of the Starting Balance. |
| ''Variant'' | ''Intraday'' (default) or ''EndOfDay'' | When the HWM ratchets — see the examples below. |

===== How the HWM moves =====

  * **Intraday** — the HWM ratchets on **live NLV** (balance plus open-position profit) on every evaluation. An unrealized peak counts even if the trader gives the profit back.
  * **EndOfDay** — the HWM commits only when the trade date rolls, on the **realized balance**. Intraday peaks do not count.

**The breach check runs continuously in both variants.** The variants differ only in when the floor tightens, not in when a breach is detected — an EndOfDay account that hits its floor mid-session is liquidated mid-session.

On first activation (and after every epoch bump) the HWM seeds at ''Max(Starting Balance, current NLV)''.

===== Example: Intraday variant =====

$50,000 plan, ''DrawdownAmount'' 2000, ''Variant'' ''Intraday''. HWM seeds at 50,000; the floor starts at 48,000.

^ ^ Session activity ^ NLV peak ^ EOD balance ^ HWM ^ Floor (Min(HWM−2,000, 50,000)) ^
| Day 1 | Buys 2 ES, rallies to +$1,250 open profit, closes out at +$800 | 51,250 | 50,800 | **51,250** | **49,250** |
| Day 2 | Rallies to +$1,600 open profit, closes at +$1,150 | 52,400 | 51,950 | **52,400** | **50,000** (capped) |
| Day 3 | Short NQ moves against the account | — | — | 52,400 | 50,000 |

  * Day 1: the //unrealized// peak of 51,250 ratchets the HWM, even though only $800 was kept. This is the defining property of the Intraday variant.
  * Day 2: the floor reaches the Starting Balance cap — from now on it stays at 50,000 no matter how high the HWM climbs.
  * Day 3: when NLV touches 50,000 the rule breaches: T4 begins liquidating positions, cancels working orders, and disables the account. The final balance depends on the liquidation fills and can be below the floor. The audit shows the formula values, e.g. ''49998.50 <= Min(52400.00 - 2000.00, 50000.00) = 50000.00''.

===== Example: EndOfDay variant =====

$50,000 plan, ''DrawdownPercent'' 4 (4% of 50,000 = $2,000), ''Variant'' ''EndOfDay''. HWM seeds at 50,000; the floor starts at 48,000.

^ ^ Session activity ^ NLV peak ^ EOD balance ^ HWM after day roll ^ Floor ^
| Day 1 | Up $1,900 at the session high, closes at +$1,200 | 51,900 | 51,200 | **51,200** | **49,200** |
| Day 2 | Gives back $900 | 51,300 | 50,300 | 51,200 (no change) | 49,200 |
| Day 3 | Losing streak continues intraday | — | — | 51,200 | 49,200 |

  * Day 1: unlike the Intraday variant, the 51,900 peak is ignored — only the realized 51,200 commits, and only at the day roll.
  * Day 2: the HWM never moves down; the floor holds at 49,200.
  * Day 3: the moment live NLV touches 49,200 — even mid-session — the account breaches and liquidation begins. //EndOfDay controls the ratchet, not the enforcement.//

===== Breach behavior =====

On breach, T4 immediately:

  - Liquidates all open positions (market-order auto-liquidation),
  - Cancels all working orders,
  - Disables the account,
  - Sends the standard auto-liquidation notifications with trigger type //TrailingDrawdown//.

The floor is the **trigger level**, not a guaranteed exit value — liquidation orders fill at prevailing market prices, so the account's realized balance after enforcement depends on those fills.

The breach then **latches**: re-enabling the account without resetting the rule causes the engine to disable it again. The only way to re-arm a breached account is an epoch bump.

===== Resetting an account (epoch bump) =====

After a payout, a plan reset, or a breach review, increment the ''Epoch'' in the rules document (the Admin API provides a one-call endpoint for this). The engine then:

  * Re-seeds the HWM at ''Max(Starting Balance, current NLV)'',
  * Clears the breach latch,
  * Clears the accumulated auto-liquidation cost exclusions.

**Note:** an epoch bump does not change the account balance. Adjust the balance first (e.g. after a payout), then bump the epoch so the HWM re-seeds from the adjusted value.

===== Auto-liquidation cost exclusion =====

Fees charged by auto-liquidation fills are added back to the rule's NLV permanently, so liquidation costs do not push the rule calculation (further) toward the floor. The firm-level setting ''CommissionExclusionScope'' controls the scope:

^ Scope ^ Excluded from the rule NLV ^
| ''LiquidationFeeOnly'' (default) | Only the per-liquidation charge. |
| ''AllAutoLiqFillCosts'' | The per-liquidation charge plus ordinary commission and fees on auto-liq fills. |

===== Admin API =====

^ Endpoint ^ Purpose ^
| ''GET /admin/v1/accounts/{accountID}'' | Returns ''propFirmRulesJSON'' and ''propFirmStartingBalance'' with the account details. |
| ''POST/PUT'' account create/update | Accepts ''PropFirmRulesJSON'' and ''PropFirmStartingBalance''. Invalid documents are rejected with a 400 and a reason. |
| ''GET /admin/v1/accounts/{accountID}/propfirm/state'' | The live rule state: HWM, epoch, breach time, cost exclusions. Read-only. |
| ''POST /admin/v1/accounts/{accountID}/propfirm/epoch'' | Bumps the epoch and saves the document — the one-call account reset. |

Rule state fields returned by the state endpoint:

^ Field ^ Meaning ^
| ''Hwm'' | Current high-water mark. |
| ''Epoch'' | The epoch this state belongs to. |
| ''BreachedAt'' | Set when the account is latched breached; null otherwise. |
| ''CumulativeExcludedLiqFees'' / ''...Commissions'' | Auto-liq costs excluded from the rule NLV to date. |
| ''InitializedAt'' / ''InitReference'' | When the HWM was seeded and from what NLV (diagnostics). |