Simulate from a real trade series
propfirms_simulate_tradesSimulate a challenge by resampling the trader's OWN R-multiple trade series with a stationary block bootstrap instead of a win-rate model. WHY THIS BEATS WIN-RATE MATH: challenge rules are breached by streaks, not by averages - a daily-loss limit dies to a cluster of losses inside one day, and a trailing drawdown dies to a losing streak right after an equity peak. Real trade series are streaky (autocorrelation, volatility clustering, edge that comes and goes), and the stationary bootstrap resamples contiguous blocks of the actual series (geometric length, mean blockMeanLength, default 5 trades), so the trader's real streak structure survives into every simulated day. A parametric model with identical summary statistics shuffles trades independently and therefore understates breach risk for streaky traders. Use propfirms_simulate when only summary stats are available; use this whenever the actual trades are. Provide the series as rSeries (array of R-multiples: each trade's P&L divided by the amount risked on it), rSeriesText (pasted JSON/CSV/whitespace text, optional 'R' suffix per value), or one of the timestamped-log inputs below; exactly one of the four, at least 10 trades, 100+ strongly recommended. Returns the same full SimResult as propfirms_simulate (structuredContent, histograms off by default) plus a text summary that also reports the sample's win rate and mean R. TIMESTAMPED LOGS: tradeLogText accepts a pasted CSV/TSV trade log with a header row (open time and R required; close time and direction optional; loose header names are matched; timestamps without an offset are read as UTC). The R-series and, unless tradesPerDay is passed, the trades-per-day rate are derived from the log, and parse warnings are surfaced in the text output. NEWS WINDOWS: with a timestamped input, newsFilter runs the simulation TWICE on the same seed and options, once on the full history and once without the trades opened inside configurable windows around scheduled releases (a built-in recurring-template calendar of high- and medium-impact events across USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, plus optional custom event times). The returned SimResult is the news-avoided scenario; structuredContent.newsComparison carries both scenarios' pass probability, funded probability and EV, the excluded-trade count, and a calendar caveat that must be relayed verbatim. PORTFOLIO MODE: tradeLogTexts (2 to 5 logs) merges several timestamped histories into one chronological series and simulates the combined account, so cross-strategy loss clustering survives. Overlap across the histories is ALWAYS analyzed and attached as structuredContent.portfolioOverlap; the text summary carries the audit-risk verdict, and a 'high' verdict is an explicit warning that a prop firm may audit or refuse payouts for correlated accounts. SIMULATED RULES (engine v1): consistency rules (steps[].consistency) and funded payout gating (funded.payoutRules) are actually SIMULATED, not merely flagged - a distinguishing feature of this engine. Consistency uses a rational stop rule (the trader stops a day once more profit cannot help and keeps trading until the best-day share complies - flag 'consistency-stop-rule'); payouts follow a maximum-withdrawal model (withdraw everything the rules allow above buffer/caps, never below the loss floor; balances and floors carry across payouts - flag 'funded-withdrawal-model'); a funded consistency gate is checked per payout window (flag 'funded-consistency-window-approximated'). The pre-1.0 flag id 'funded-payout-resets-account' no longer exists. UNITS: every *Pct rule field and every percent-mode risk value is in PERCENT UNITS (5 = 5%, 0.5 = 0.5%). The one exception is winRate, which is a FRACTION in [0, 1] (0.55 = 55% winners). Probabilities in results are fractions in [0, 1]. DETERMINISM: identical inputs including seed reproduce byte-identical results on any platform. Include the seed and path count when reporting numbers so users can reproduce them exactly; re-run with a few different seeds to gauge Monte Carlo spread. ASSUMPTIONS: every result carries assumptions.flags - dataset-declared rules the engine does NOT simulate (e.g. scaling plans or soft daily lockouts, which make real odds worse than simulated) plus engine simplifications - and assumptions.disclaimer. These are material: always surface the flags and the disclaimer to the user alongside the numbers, never just the headline probability. Results are distributions under stated assumptions, not promises. Composes with any broker-statistics tool: if another MCP server exposes round-trip statistics (winRate, avgWin, avgLoss) or a raw R-multiple series from the user's real trades, feed them here to answer "given my actual trading, what are my odds on this challenge and what risk should I use?". Convert currency statistics to R-multiples by dividing by the average amount risked per trade: winRate stays a fraction, avgWinR = avgWin / avgRisk, avgLossR = |avgLoss| / avgRisk.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | RNG seed (integer or string). Default 42. Same inputs + seed reproduce byte-identical results - include the seed when reporting so users can reproduce the numbers. | |
| spec | No | Inline challenge ruleset, for challenges not in the directory or for what-if rule edits. Mutually exclusive with firmId/challengeId. Identify the challenge EITHER by directory reference (firmId + challengeId, discovered via propfirms_list_simulatable; firmId accepts the directory id or the firm's name) OR by a full inline `spec` object - the exact shape propfirms_challenge_rules returns, so you can fetch a directory entry, change one rule, and re-simulate to model rule variations. Provide exactly one of the two forms; providing both or neither is an error. Directory references need network access; inline specs are fully offline. | |
| paths | No | Monte Carlo paths (independent simulated trader journeys). Default 10,000 (well under a second); capped at 100,000 per tool call. Confidence intervals shrink roughly with the square root of paths. | |
| firmId | No | Directory firm id or firm name (e.g. 'ftmo' or 'FTMO'); discover with propfirms_list_simulatable. Must be paired with challengeId. Mutually exclusive with `spec`. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| rSeries | No | The trader's real trades as R-multiples in chronological order: each trade's P&L divided by the amount risked on it (+1.8 = won 1.8x risk, -1 = lost exactly the risk, -1.4 = stop slipped 40%). At least 10 trades; 100+ strongly recommended - short series make the simulation overconfident in the sample. Mutually exclusive with rSeriesText, tradeLogText, and tradeLogTexts. | |
| riskMode | No | How riskValue is interpreted. 'percent-of-balance' (default): risk compounds with the current balance. 'percent-of-initial': constant currency risk derived from the initial account size - how most prop traders size, since loss limits are fixed in currency. 'fixed-amount': explicit currency risked per 1R. | |
| riskValue | Yes | Risk per trade - the value of 1R. PERCENT UNITS for percent modes (0.5 = 0.5% risked per trade; a typical prop range is 0.25-2), or a currency amount for 'fixed-amount'. NOT a fraction. | |
| attemptCap | No | Maximum challenge attempts per path before that path gives up. Default 25. Journey statistics (expected attempts/cost, P(funded)) are censored at this cap. | |
| importRisk | No | Risk per trade for imports that carry P&L but no risk data (e.g. TradingView, MT5 deals, broker JSON, ThinkOrSwim): cash risked per trade ("25") or a percent of entry value ("1%"). Applies to tradeLogText/tradeLogTexts only, is labeled rSource inferred, and is never applied silently: without it such files are refused with needs-risk. | |
| newsFilter | No | What-if comparison: what are my odds if I do not OPEN trades around scheduled news? Requires a timestamped input (tradeLogText or tradeLogTexts). The simulation runs TWICE with the same seed and options, once on the full history and once with every trade opened inside [event - preMinutes, event + postMinutes] removed; trades opened earlier but held through an event are only counted, not removed. The returned SimResult is the news-AVOIDED scenario; structuredContent.newsComparison carries both scenarios' headline numbers, the excluded-trade count, and a calendar caveat that MUST be relayed to the user (the calendar is a recurring-template approximation of scheduled releases, not a historical feed). | |
| challengeId | No | Directory challenge id; discover with propfirms_list_simulatable. Must be paired with firmId. Mutually exclusive with `spec`. | |
| rSeriesText | No | The same series as pasted text: a JSON array, CSV, or whitespace/newline separated numbers, with an optional 'R' suffix per value (e.g. "1.8R, -1R, 0.4, 2.1"). Parsed with the library's parseRSeries; unparseable tokens are reported back. Mutually exclusive with rSeries, tradeLogText, and tradeLogTexts. | |
| tradeLogText | No | The trader's trades as one pasted TIMESTAMPED log instead of a bare series. Accepted formats, auto-detected: the generic CSV template (header: open time,close time,symbol,direction,quantity,entry price,exit price,stop loss,pnl,fees,r), plain timestamped CSV/TSV logs (open time + R columns), real platform exports: TradingView strategy-tester list of trades (both generations), MT4/MT5 account statements (CSV or pasted HTML), MT5 deals tables, and ThinkOrSwim account statements, plus broker trade-history JSON in the @luxalgo/broker-sdk shape (a bare fills array, {"trades": [...]}, or one snapshot account; fills replay FIFO into round trips with price-based P&L, disclosed). Timestamps WITHOUT an explicit offset are read as UTC. Files that carry P&L but no risk information need importRisk to become R-multiples; ambiguous rule readings are refused with diagnostics rather than guessed, and skipped rows are reported as warnings. Timestamps unlock two things a bare series cannot do: tradesPerDay is derived from the log when not given, and newsFilter can compare odds with and without trading around news. Mutually exclusive with rSeries, rSeriesText, and tradeLogTexts. | |
| tradesPerDay | No | Average trades per simulated trading day. REQUIRED with rSeries/rSeriesText, which carry no timestamps. Optional with tradeLogText/tradeLogTexts: when omitted it is derived from the log's own timestamps (trades divided by distinct UTC trading days) and the output says so. More trades per day means more ways to hit the daily loss limit within a single day. | |
| tradeLogTexts | No | PORTFOLIO MODE: 2 to 5 timestamped trade logs (same format as tradeLogText), one per strategy or account. They are merged into one chronological series and the combined account is simulated, which preserves cross-strategy loss clustering (exactly what daily and max loss limits punish). Overlap across the histories is ALWAYS analyzed and attached as structuredContent.portfolioOverlap with an audit-risk verdict; see the attached structuredContent.portfolioOverlap analysis for the methodology. Mutually exclusive with rSeries, rSeriesText, and tradeLogText. | |
| simulateFunded | No | Whether to simulate the funded stage (payouts, blowup risk) after passing. Default true - EV is only meaningful with it on; set false to study the evaluation alone. | |
| blockMeanLength | No | Mean block length of the stationary bootstrap (geometrically distributed blocks). Default 5 trades. 1 = i.i.d. resampling (destroys streaks - only for comparison); raise toward 10 if the trader's edge comes and goes in long regimes. | |
| fundedHorizonDays | No | Funded-stage horizon in trading days for the payout/EV simulation. Default 90 (about 4 calendar months). EV scales with this choice - state it when reporting EV. | |
| includeHistograms | No | Include histogram arrays (attempts, cost, net, drawdown) in the result. Default FALSE for this tool to keep responses compact; summary quantiles (p05...p95) are always included. | |
| tradesPerDayModel | No | 'fixed' (default): the same count every day. 'poisson': daily count drawn Poisson(tradesPerDay); days can then have zero trades, which do not count as trading days. |