SRS: UC_7.1 — Anti-Fraud Reconciliation

---

UC_7.1 — Anti-Fraud Reconciliation

1. Overview

No wireframe — backend monitoring job with no UI screen of its own. Its only externally visible output is a Slack message to #ops_general; it never writes to Users.status, never locks the dashboard, and never surfaces an "Under Review" state to the trader.

---

2. Trigger

Event-driven — fires immediately upon Flow 4 (Promotion) completing for a trader. This is the first step Flow 5 (Payouts) executes once triggered; UC_7.2 runs immediately after this UC, regardless of this UC's outcome (see §4 Post-conditions). This UC has no independent schedule or UI trigger of its own.

---

3. Pre-conditions

---

4. Post-conditions

Reconciliation within tolerance

• No side effect. No alert is raised. UC_7.2 proceeds immediately.

Reconciliation beyond tolerance

• A Severity-1 Slack alert is posted to #ops_general, silently. Users.status is unchanged and the payout is not delayed. UC_7.2 proceeds immediately, in parallel with (not blocked by) the alert.

Endpoint error / timeout

• The payout still proceeds (fail-open, based on verified ISV platform equity). A Severity-1 Slack alert is now posted to #ops_general for this case too, using the same template as a tolerance mismatch — see Exc-1 and BR_7.1.4.

---

5. Basic Flow

1. Flow 5 begins. On Flow 4 (Promotion) completion, Flow 5 (Payouts) is triggered for the trader, and this UC's reconciliation call is its first step.

2. Call the reconciliation endpoint. The middleware calls POST /verify-payout-reconciliation, input user_id. The endpoint returns:

   { "pnl_match": bool, "broker_equity": float, "institution_balance": float }

   • pnl_match — the endpoint's own true/false verdict for whether the two values below are considered matching.
   • broker_equity — for Futures, this field name carries the Rithmic Net P&L, computed as Rithmic_Account_Balance - Max_Futures_Notional (not the raw Rithmic balance — see step 3(a)). For Forex, this field name is reused to carry the trader's individual TraderEvolution or MT5 sub-account equity/balance — see step 3(b).
   • institution_balance — for Futures, this field name carries the Ironbeam Realized P&L, computed as cashBalance - Futures_Capital (not the raw Ironbeam balance — see step 3(a)). For Forex, this field name is reused to carry the trader's own PostgreSQL Virtual Ledger value (ledgers.virtual_equity) — not an LMAX/omnibus balance; see step 3(b) for why.

3. Branch by Asset_Class — the two fields above mean different things depending on asset class:

   (a) Futures — reconcile Net P&L, not raw balance:

   • Reconcile Futures payouts by comparing the trader's net P&L against the realized P&L on the mapped Ironbeam sub-account and internal ledger:
     • Rithmic Net P&L = Rithmic_Account_Balance - Max_Futures_Notional.
     • Ironbeam Realized P&L = cashBalance - Futures_Capital.
   • Why cashBalance, not a dedicated realized-P&L field: Ironbeam's Account Balance endpoints (GET /v2/account/{accountId}/balance and GET /v2/account/getall) do not return a separate realizedPnL field. Because this UC runs immediately after Lock & Liquidate (Flow 4) when all open positions are flat (openTradeEquity = 0), all realized P&L is already settled directly inside cashBalance — so cashBalance - Futures_Capital is the realized P&L for the period.
   • Both sides are still external systems (Rithmic, the ISV, vs. Ironbeam, the FCM) — this remains a per-trader, system-to-system comparison; only the shape of what's compared changed, from raw balance-vs-balance to Net-P&L-vs-Realized-P&L (Ref: BR_7.1.5).

   (b) Forex — structurally different from Futures, not just a different data source:

   • The trader's own PostgreSQL Virtual Ledger value, ledgers.virtual_equity — an internal system value, not a counterparty/custody-side value.
   • broker_equity (field name reused) = the trader's individual sub-account equity/balance on TraderEvolution or MT5 — the execution-platform side.
   • The comparison is therefore internal-ledger-vs-execution-platform for Forex, rather than execution-platform-vs-custodian as it is for Futures — see BR_7.1.2.

4. Apply the per-level tolerance band. The absolute difference between the two compared values — |Rithmic_Net_PnL - Ironbeam_Realized_PnL| for Futures, or |broker_equity - institution_balance| for Forex — is compared against a tolerance that scales with the trader's Current_Level (Tolerance_Threshold) — see BR_7.1.3 for the exact bands. This check remains diagnostic and non-blocking regardless of asset class.

5. Evaluate the result:

   • If the difference is within the applicable band (pnl_match = true) → no further action this cycle (see §6 Alt-1).

   • If the difference exceeds the applicable band (pnl_match = false) → the Middleware silently dispatches a high-priority Severity-1 (SEV-1) alert to the internal #ops_general Slack channel for post-disbursement database reconciliation by engineering, using the template below. The alert does not identify a root cause (fraud vs. clearing/rounding/fee timing) — Ops must investigate independently. The client's own framing is that most such alerts are expected to be "minor administrative artifacts, such as market data fee deductions," not malicious activity.

     🚨 CRITICAL: Payout Reconciliation Mismatch
     
     User ID: [user_id]
     Execution Platform: [Rithmic / MT5 / TraderEvolution]
     Broker Equity: $[broker_equity]
     Institution Balance: $[institution_balance]
     Variance: $[variance_amount]
     Status: Payout disbursed. Manual database reconciliation required immediately.

     This same template applies to both cases that reach this branch — a true tolerance-band mismatch and pnl_match = false from the endpoint directly — there is no separate template or wording for the two.

6. Always proceed, regardless of step 5's outcome. Flow 5 continues to UC_7.2 (Compliance Check) immediately. Step 5's outcome has no bearing on whether, when, or how much the trader is paid — see §4 Post-conditions and BR_7.1.1.

---

6. Alternative Flows

• Alt-1 — Difference within tolerance; no alert.
  • Context: at step 5, the absolute difference between broker_equity and institution_balance is at or below the applicable tolerance band for the trader's Current_Level.
  • No Slack alert is raised. Flow 5 proceeds to UC_7.2 exactly as it would after a mismatch — there is no behavioral difference visible outside this UC between Alt-1 and a mismatch beyond tolerance, other than the Slack alert itself. This is the expected common case.

---

7. Exceptional Flows

• Exc-1 — The reconciliation endpoint times out or returns a 5xx error (no verdict, as distinct from a mismatch).
  • The system still fails open — it proceeds with the automated payout based on the verified ISV platform equity.
  • It raises the same Silent Alert (SEV-1 to #ops_general, same template as §5 step 5) used for a tolerance mismatch, since there is no verdict to log as a pass. The alert's Status line still reads "Payout disbursed. Manual database reconciliation required immediately." — Flow 5 moves to UC_7.2 (Compliance Check) immediately regardless.

---

8. Business Rules

BR_7.1.1: Reconciliation is monitoring-only — it never gates, halts, or delays the payout

Regardless of the result of the comparison in §5 step 5 — within tolerance, beyond tolerance, or undeterminable due to an endpoint failure — Flow 5 always proceeds to UC_7.2 (Compliance Check) and, from there, to payout execution. There is no code path in which this UC blocks, holds, or delays money, locks the trader's dashboard.

---

BR_7.1.2: Forex comparison is internal Virtual Ledger vs. individual sub-account — LMAX (Omnibus) is never called

Futures and Forex are not the same comparison pattern with different data sources — they compare structurally different pairs:

• Futures: broker_equity (Rithmic, the ISV) vs. institution_balance (Ironbeam, the FCM/custodian) — both sides are external systems, a per-trader, system-to-system comparison.
• Forex: the trader's own PostgreSQL Virtual Ledger (ledgers.virtual_equity) vs. that same trader's individual TraderEvolution or MT5 sub-account equity/balance — one side internal (Stack Trading's own ledger), one side the execution platform. No institution/custodian-side value is read for Forex at all.

Why LMAX is excluded: the LIVE Forex account at LMAX is a corporate Omnibus account — every Forex trader's orders are aggregated together at LMAX, and LMAX has no visibility into individual trader sub-accounts. There is no per-trader balance this endpoint could read from LMAX, so POST /verify-payout-reconciliation never calls the LMAX API for an individual trader's payout.

The per-level tolerance bands in BR_7.1.3 apply identically to both comparison pairs — only the inputs being compared differ by asset class.

(Source: client-confirmed, relayed by user (BA session) 2026-10-26 — "Because our LMAX account is a corporate Omnibus account, all live Forex traders' orders are aggregated together at LMAX. LMAX has no visibility into individual trader sub-accounts. Therefore, do not call the LMAX API for individual trader payouts in Flow 5 (POST /verify-payout-reconciliation). For Forex payouts, the anti-fraud check compares the user's PostgreSQL Virtual Ledger (ledgers.virtual_equity) directly against their individual TraderEvolution or MT5 sub-account equity/balance (using the level-based tolerance thresholds shown in the sheet)." — supersedes the prior "pending client confirmation" / omnibus-provider framing)

---

BR_7.1.3: Per-level tolerance band

The allowed absolute difference between the two compared values scales with the trader's Current_Level, using 4 fixed bands:

---

BR_7.1.4: Fail-open on endpoint error or timeout, with Silent Alert

If POST /verify-payout-reconciliation times out or returns a 5xx error, the system still proceeds with the payout based on the verified ISV platform equity — the payout itself is never held up (A-06). This case now also raises the same Silent Alert (SEV-1 to #ops_general) used for a tolerance mismatch — see §5 step 5 for the template and Exc-1 for the full rationale. It is no longer treated identically to a silent within-tolerance pass.

(Source: QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-06; alert behavior per BA update 2026-10-08)

---

BR_7.1.5: Comparison shape differs by asset class — Futures is Net-P&L-vs-Realized-P&L; Forex remains balance-vs-balance

Futures (supersedes the prior balance-vs-balance framing for this asset class — client update): the comparison is Net P&L vs. Realized P&L, not raw balance vs. balance:

• Rithmic Net P&L = Rithmic_Account_Balance - Max_Futures_Notional.
• Ironbeam Realized P&L = cashBalance - Futures_Capital — derived from cashBalance because Ironbeam's balance endpoints (GET /v2/account/{accountId}/balance, GET /v2/account/getall) expose no dedicated realizedPnL field; since this UC runs right after Lock & Liquidate (Flow 4) with all positions flat (openTradeEquity = 0), realized P&L is already fully settled inside cashBalance.
• The check is |Rithmic_Net_PnL - Ironbeam_Realized_PnL| <= Tolerance_Threshold (BR_7.1.3) — still diagnostic and non-blocking: on breach, fire the silent SEV-1 Slack alert and proceed with the payout (Ref: BR_7.1.1).

Forex (unchanged — client-confirmed A-88, relayed 2026-09-28): the comparison remains strictly balance vs. balance — broker_equity (the trader's individual TraderEvolution/MT5 sub-account equity/balance) against institution_balance (the trader's own PostgreSQL Virtual Ledger ledgers.virtual_equity — see BR_7.1.2). It is not a P&L-based comparison for Forex.

This closes three points that were previously open, now scoped per asset class:

• Neither side reads or compares against historical_pnl or any cumulative-period P&L figure — Futures uses the two P&L figures defined above, Forex uses the two point-in-time balance/equity values.
• It does not matter that Flow 4's reset-ledger step already overwrote virtual_equity to Level_Starting_Capital before this UC runs (see P-1) — for Forex, virtual_equity is one side of the comparison by design (per BR_7.1.2), so the reset is expected input, not a timing bug to work around. For Futures, virtual_equity plays no role in the comparison either way.
• The comparison is a snapshot taken at the moment this UC runs, not an aggregation over the challenge/level period — both sides (for either asset class) are read fresh at call time (§5 step 2).

(Source: Forex — QnA_STAGE5_PAYOUT_WITHDRAWAL.md A-88, client confirmation relayed by BA, 2026-09-28. Futures — client update relayed by user (BA session), supersedes the prior balance-vs-balance framing for Futures only.)

---

9. Update History

---