Four gates between a chart and a live order, a reconciliation loop that treats the broker as the only source of truth, and a regime filter that keeps the bot in cash most of the time. This is the architecture, drawn out.
Most trading bots are a single script: fetch data, compute a signal, send an order. That design is fine until the day the database is empty, or the broker disagrees with your local records, or a bull-market backtest quietly convinces you to trade through a bear market. Mercurio is built defensively, because every one of those failures has already happened to us once -- and each one is now a named lesson in the codebase.
This article is the map. It is built around three interactive diagrams of the system's real control flow. You can drag to pan and use the controls to zoom. Each diagram is generated from the same specification the engine documents, so it cannot drift out of date with hand-drawn boxes.
The edge is the technical strategy. Everything else -- the AI layer, the risk manager, the regime gate, the reconciler -- exists to protect that edge from itself and from the real world. Layers can only ever reduce risk, never amplify it.
Mercurio is a hybrid: a Python trading engine and FastAPI gateway on one side, a Next.js dashboard on the other, with PostgreSQL for persistence and Alpaca as the broker. The pieces are deliberately decoupled so the engine can keep trading even if the dashboard, the database, or the AI service is down.
A trade does not happen because one indicator lit up. It happens because a signal survived a gauntlet. The trend strategy proposes; four independent gates dispose. Any single gate can route the candidate to cash, and the gates are ordered cheapest-to-most-expensive so the system does the least work to reject a bad idea.
Every signal passes four independent gates. Any one of them can send it to cash. Only a signal that clears all four becomes a bracket order at Alpaca.
Putting the regime gate before the expensive AI call is not cosmetic. In a bear or choppy market the gate rejects nearly everything, so the system almost never spends an AI budget call on a trade it was never going to take. Cheap filters first is both safer and cheaper.
The most dangerous bug we ever shipped was not in a strategy. It was a deploy where the database came up empty, the engine saw zero local records for its live positions, concluded they were all orphans, and queued market-sell orders for the entire portfolio. The orders were cancelled in time. The lesson was permanent: the broker, not our database, is the source of truth.
So reconciliation is not a nightly batch job -- it is a permanent loop that runs every cycle. It reads Alpaca's actual positions, compares them against the local trade log, repairs any drift in our metadata, and mirrors any fills the engine missed back into Alpaca's record. The dashboard only ever shows reconciled numbers.
On every cycle the reconciler treats the broker as ground truth, repairs local metadata, mirrors any missing fills back to Alpaca, and feeds the dashboard reconciled numbers. State can never silently drift.
Because Alpaca is ground truth, the dashboard cannot flatter us. Right now the live paper account shows a realized loss of about -$722 across 536 round-trips at a 51% win rate. That is the reconciled number, straight from the broker. We would rather show a real loss than a comfortable fiction -- and we never present a backtest figure as a live one.
Trend following on a tech-heavy universe makes money in sustained bull markets and loses it almost everywhere else. We proved that the hard way: over a full five-year cycle including the 2022 bear, the raw strategy is net negative. The fix is not a cleverer entry -- it is the discipline to not trade at all when the weather is wrong.
The regime gate reads the S&P 500's own daily trend. Longs are unlocked only after the index closes above both its 50-day and 200-day moving averages for ten consecutive sessions. Until that streak is met, the engine sits in cash. It is a slow, deliberately conservative switch.
The gate reads the S&P 500's own daily trend. Longs are only unlocked after the index closes above both its 50- and 200-day averages for ten consecutive sessions. Anything less means cash.
The ten-day confirmation is not an arbitrary number -- it survived walk-forward testing where dozens of flashier ideas did not. It improved results on both the in-sample and out-of-sample windows, which is the only kind of improvement we trust.
| Regime configuration | In-sample Sharpe | Out-of-sample Sharpe |
|---|---|---|
| Directional (long + short) | +0.99 IS | -0.13 OOS (fails) |
| Bull-only (no confirmation) | 0.51 | 0.50 |
| Bull-only + 10-day confirm | 1.13 | 0.58 |
The mechanism is visible in one statistic: in the 2022 bear market, the bull-only filter without confirmation still took 200 longs and lost roughly $6,900. With the ten-day confirmation, the streak never reached ten, so it took zero longs and sat the whole bear out. The gate did its job by doing nothing.
Each subsystem degrades independently instead of taking the others down with it. This is what lets a retail-scale bot run unattended:
Kill switches, loss-streak counters, the drawdown breaker, and the daily-reset flag all persist to a state store. An early version kept them in memory; a mid-day restart wiped them and re-enabled strategies that had been killed for losing. Now any state that can move money survives a restart by design.
None of this is a marketing diagram drawn after the fact. The pipeline lives in orchestrator.py, the gates in risk_manager.py and intermarket.py, and the validation in portfolio_backtest.py. If a diagram here and the code ever disagree, the code wins -- and that is a bug for us to fix.
If you want the evidence behind the strategy these systems protect, read the backtesting deep dive and why trend following was the only survivor.
Disclaimer. Mercurio runs on paper capital. Live figures cited here are reconciled paper-trading results, not real-money performance; backtest figures are historical simulations. Nothing here is financial advice. Past performance does not guarantee future results.
