MoyaiTrading v2 — User guide

The guide mirrors the architecture: one page per part of the system, written in the same change as the code it describes (CLAUDE.md Rule 6). Pages arrive as their features are built (ROADMAP.md). v1's guide stays at ../moyaitrading/docs/ and describes v1 only.

Contents

• How the pieces fit — for each roadmap step: why it comes where it does, and how it works with the steps before and after it.
• Setup — the project files, the virtual environment, the data path (local.yaml), and the devlog hook.
• Testing — how the tests are organised and run.
• Instruments — the contract facts (point value, tick size), how they reach the rest of the code, and rounding a price to the tick grid.
• Trading clock — the trading day (18:00 → 16:00 New York), session minutes, and why moments are UTC nanoseconds.
• Session windows — asia, europe, us, us_open, power_hour and the alias overnight: what they are for, where their boundaries are, and why they stay on New York time when Europe changes its clocks.
• Tick reader — an instrument's tick file handed out one trading day at a time: what a TickDay holds, what is refused, what is in the file, and how memory stays bounded.
• Building the tick file — v2's own tick file from the raw per-UTC-day archive: one short session traced from the archive to a TickDay, the ends of the archive, why it is staged and checked before it is installed, its speed against v1's build, and the one-time check against v1.
• Known defects — what the tick file is missing and why: the exchange calendar, vendor holes, March 2020's halts and limit locks, the contract rolls, the blackouts the engine will enforce, and how a run reports its exclusions.
• Bars — one trading day's ticks summarised into bars: a bar type is a cut plus one shared summary; one hour traced from ticks to 1-minute bars; start labels, end, no bar for an empty minute; sizes that divide the 22-hour day; why bars are built per day, in memory; the check against v1.
• Orders, trades and exit reasons — what a strategy asks for and what happened: one permabull_open trade traced from order to exit reason; SL and TP as distances from the fill; sizes in steps of 0.1 (micros); the nine exit reasons; what is refused and where; v1's Trade field by field.
• Fill rules — which tick fills an order, and at what price: one permabull_open entry traced to its tick; a stop gapped through on a CPI morning; resting and marketable limits; the next microsecond, not the next row; latency; the day order, halts and registry holes; the check against v1.
• P&L and R — what a closed trade earned: points, dollars, and R (points over the SL distance at entry); two real trades worked through; why a gapped SL is below −1R; a trade without an SL at entry has no R but counts everywhere else; 0.1 NQ = 1 MNQ.
• Excursions and holding time — what a trade went through: MAE, MFE, when each was reached, and the drop from the trade's own peak, on real trades; which ticks count and why at their own prices; a gapped SL; a trade carried over a weekend and a holiday session; holding time elapsed and while CME was open.
• The equity record — what the account was worth, one row per minute: close, best, worst and the drop inside the minute, in points per contract and points × size; one real day's 207,762 ticks as 390 rows with no drawdown lost; the grid and silent minutes; an exit marked at its tick, then banked at its fill; memory; the check against v1.
• Costs per round trip — what a fill costs: fees per real contract from a named schedule (TPT, the default; TS; GROSS), and a tick when a fill crossed the spread on a trade the other side printed, read from the aggressor flag; a real entry that missed the spread; why stops are already exact; micros; gross and net on a trade and in the equity record; how a run states its cost.
• Strategies — the contract a strategy signs: its bars, setup once a day, on_bar at each bar's end with a view that ends at bar k (reading bar k+1 is an error), the Position, one instruction or none; the registry; and the standing fallacy tests every registered strategy gets, future perturbation, price mirror and the fill-optimism probe, worked on 2023-01-17.
  • permabull_open — the first registered strategy: buy the 09:30 open, SL 50, TP 37.5, flat at 16:00; one real trade; why a day with no 09:29 bar is skipped; the whole file at TPT and under the fill-optimism probe; every day compared with v1.
  • permabull_open ideas — ten filters that might make it better, decidable at 09:29:59; what any filter must beat (57.1%); how to test them without fooling ourselves.
• Params and config layering — the numbers a strategy's rules are written in: one packaged default (the params class), the project file .moyai/strategies/<name>.yaml, the run's arguments, merged key by key; strict refusals (unknown keys, text for numbers, NaN); why v1's ftm_orb risk was 535 or 5,350 depending on a missing key; why 16:00 must be quoted.
• Firm programs — a prop firm's rules as a checked file: the stages of Lucid's 50K LucidFlex traced from YAML to the object; every field with its unit; contract limits and scaling rules; whole files, never layered, and why (v1's local file replaced its packaged program); the refusals; what a program does not hold (sizing); v1's fields one by one.
• The account in the run — a prop firm's program played out tick by tick (10.2a): the real April 2024 account lost at its floor on 04-09 before the SL; the floor and target as orders on the trade; eod and intraday floors and the lock; sizing to the stop, the target or in contracts; scope, after, open_next; the known pass rates of a trailing floor. The consistency rule played with a daily cap, and min_days with filler trades (10.2b): at 3 NQ a $2,236.50 day becomes a $1,501.50 one, and an account wins in two capped days.
• Economics — what a prop-firm run cost and paid, in cash (10.3): the balance is not money, only fees and payouts are; one 2024 attempt worth +$3,500; the EV per finished attempt, attempts per payout and cash a month; open attempts left out and shown; why one stage alone has no EV; the known answer F × split − fee.
• Running a backtest — the one entry point: a RunSpec says what a run is (strategy, params, symbol, days, costs, latency, forced exits, short sessions), run_backtest runs it and refuses every mistake before a tick is read, and the Result records what made it (resolved params, blackouts, exclusions, tick file, commit) so it reruns without .moyai/; worked on the week of Martin Luther King Jr. Day 2023.
• Metrics — what a finished run says: trade statistics net first, gross and dollars beside; R with its coverage; distributions as deciles, the values left in the run; breakdowns by exit reason and group, year, session and hour; daily Sharpe with its standard error, Sortino, Calmar; the drawdown on the minute record and the costs paid inside it; the run-up, exact across minutes and bounded inside one; episodes, months and years; None where v1 said 0; the check against v1.
• Trade log — a run's trades as files: one row per trade in trades.csv (the record, then its dollars, R, both holding times and the short-session and roll flags), the cancels beside it, run.json for what made the run; times to the nanosecond in New York time; read back exactly, so 5.4's comparison and 7.1's statistics come out the same from the file.
• The backtest report — one run as one HTML file that needs nothing beside it: the data in once as JSON, every view drawn and redrawn in the browser; the MLK week traced from the run to the page; the two drawdowns; what is computed in Python and what in the page, and how headless Edge checks the page against Python; v1's report panel by panel.
• The backtest report prototype — the design step 7.3 built from: an HTML app rather than a static page, found over five prototypes; what each section shows, how to regenerate it, and what it taught (the size, four silent chart bugs, a run-up the record bounds only).
• The prop-firm report prototype — step 10.5's design in progress: 7.3's page with a prop section, reviewed and changed prototype by prototype.
• The command line — python -m moyai run, list, init, ticks build: the MLK week run from one typed line, every line of what it prints and why (defaults starred, params by layer, costs, data, commit); each option one RunSpec field; accounts as named files in .moyai/accounts/; init never overwriting; refusals as exit 1 without a traceback; why not a bare moyai, and why the output is UTF-8. On a terminal, a run shows day 812 of 2,073 while it walks.
• The background runner — one run in a child process, so a window can show its progress and stop it: the MLK week traced through parent and child with its timings; start, poll, cancel and the five messages; why poll and not callbacks, why the folder comes back and not the 167 MB Result; the days counted from the file's footer; a cancel that cannot leave a half-written folder; refusals and bugs across the process boundary.
• The GUI — python -m moyai gui: a run traced from the form to Open report; the four tabs; forms built from the classes, with each field's description as its hover card, so a new strategy needs no GUI work; the ETA; a log never cleared but bounded; the Runs list read from names first; saving to .moyai/; the program editor's readouts in R; why pywebview, and why without the GPU. Its design: round 1 and round 2 of the prototype.
• Strategies on a Quantower chart — each strategy as a [STRATEGY] indicator on Quantower's own data (Rule 13, 14.3): Rithmic's weekly limit measured in trades, the two logs that show what a request cost, building and installing, and the four quota measurements.
• Governance — how correctness is checked: design, standing fallacy tests, and the on-demand auditor; plus the fallacy checklist.