A broker-agnostic execution engine for a single daily-bar setup. The strategy is about forty lines. The other 95% of the codebase exists to answer one question: what happens when the process dies halfway through placing an order?
The Standout Feature
Most hobby bots are one environment variable away from live capital. This one is not. Before any real-money broker call, the engine reads its own journal and refuses to proceed unless a genuine paper track record already exists — at least 60 closed paper trades at a positive realized expectancy. The rule started life in a markdown design doc, which meant a single flag could quietly skip it, so it was moved into Engine._guard_promotion_gate where it runs on every single pass.
That is not a placeholder — it is the actual state of the order journal on disk, and it is exactly why no real capital has ever moved through this engine. Overriding the gate is possible, but only by setting a deliberately unpleasant environment variable named OVERRIDE_PROMOTION_GATE=I_ACCEPT_UNVALIDATED_RISK, and doing so writes a warning into the log and the journal. You cannot trip it by accident.
DRY_RUN=true and ALLOW_LIVE=false are the shipped defaults. A live-capable adapter raises rather than starts unless you set ALLOW_LIVE=true yourself. The default broker is a local simulator with no network and no keys.
Passing gate 1 is not enough. The engine then asks the journal for (n, expectancy) and raises unless n >= 60 and expectancy is strictly positive. The error message reports the current count and expectancy so a blocked run explains itself.
A gate_detail() breakdown reports closed trades per broker, because "I have closed trades but the gate says zero" has two very different causes — simulator trades, which are never eligible, and trades whose exit price was never recovered, which are excluded rather than fabricated.
The Problem
Every hobby trading bot has the same failure modes, and none of them are about picking the wrong stock. It crashes between sending an order and recording it, restarts, and sends the order again. It fills an entry and never gets a stop in. It sells a position twice because two exit orders were live against one lot. It quietly manages a position you opened by hand. Each of those loses real money in a way a backtest will never show you.
What I Built
Every signal maps to a deterministic client_order_id, and a SQLite journal claims that id before the broker call. Crash and restart, the same id is re-derived and the order is skipped rather than re-sent. A test fires twelve concurrent writers at one journal from separate connections and asserts exactly one wins the claim and eleven lose — the real failure mode being a scheduled job firing twice, or a retry racing the original run.
DRY_RUN=true and ALLOW_LIVE=false are the defaults. A live-capable broker adapter refuses to start unless you explicitly opt in. There is also a halt kill switch that blocks all new entries.
A stop goes in immediately after a fill. Failing to place one is logged as an error, never swallowed. The stop and the 2R target are linked, so one filling cancels the other — otherwise the stale leg eventually sells shares you no longer own.
Bot-owned positions are recorded in a bot_positions table at fill time, keyed by strategy, symbol and entry bar. Any position without a journal row is assumed to be mine and is never managed or exited.
Everything goes through one Broker interface, so paper and live run identical code paths. You are never testing something different from what you run.
reconcile rebuilds the journal against the broker after a crash, and manage is fully idempotent — safe to run on a cron as often as you like, because it never places a second copy of an order.
How It Works
scan # signals only — never places an order, no API keys needed status # account, guards, open positions run # scan + trade + manage (DRY_RUN=true just logs the intent) manage # maintain exits on bot-owned positions — idempotent halt / resume # kill switch reconcile # repair the journal against the broker after a crash
manage pass. That is strictly weaker, and the code and docs say so rather than pretending the two are equivalent. The cancel itself is crash-safe: the leg is marked cancel_pending in the journal before the broker call, so a crash in that gap gets repaired instead of leaving a live sell order against shares that are already gone.
Install & Quickstart
The repository is private today, so there is no public clone URL — access is by request rather than a link. Once you have a copy, setup is a virtualenv, an editable install and a copy of the example environment file. The default broker is a local paper simulator: no network, no credentials, nothing that can reach a real account.
uv venv && uv pip install -e .
cp .env.example .env # .env is gitignored
python cli.py scan # signals only — never places an order, no keys needed python cli.py status # account, guards, positions python cli.py run # scan + trade + manage (DRY_RUN=true just logs intent) python cli.py manage # maintain exits on bot-owned positions — idempotent python cli.py halt # kill switch: blocks all new entries python cli.py resume python cli.py reconcile # repair the journal against the broker after a crash
Watchlist is one ticker per line in watchlist.txt, or pass --symbols SPY,NVDA. Broker adapters are optional extras, so only the one you pick gets installed. Start with scan — it reaches no broker and needs no credentials at all.
| BROKER= | Official API | Paper mode | Notes |
|---|---|---|---|
| paper | n/a | Yes | Local simulator. No network, no keys. Start here. |
| alpaca | Yes | Yes | Recommended for equities. Only adapter with broker-native OCO exits. |
| rh_crypto | Yes | No | Official Robinhood Crypto API. Crypto only; the setup was never tested on crypto. |
| robinhood | No | No | Unofficial equities adapter. Not a recommended path — see below. |
On the unofficial Robinhood equities adapter: it exists in the codebase and the README documents it as a bad idea. Robinhood publishes no public stocks API, so that adapter impersonates the mobile app — it breaks Robinhood's terms of service, accounts have been restricted for automated access, it can break without notice, it has no paper mode, and it requires storing a password and TOTP seed locally. It is disclosed here for completeness, not offered as an option. Use Alpaca.
The Stack
Four adapters implement one Broker interface, so paper and live run identical code paths and you are never testing something different from what you run. The default is the local simulator. Alpaca is the recommended real adapter, because it publishes an official API, offers a genuine paper mode, and is the only one that can express a broker-native OCO exit pair.
Honest Status
160 tests cover the safety properties directly — duplicate suppression under concurrency, promotion-gate enforcement, unprotected-position detection, ownership boundaries, closed-bar-only signals. The engine runs against the paper simulator today.
It has never traded live money and the journal on disk holds zero orders. The promotion gate is shut and stays shut until a paper record exists. No sales, no users, no returns are being claimed here.
It does not publish alerts, sell picks, or run as a service for anyone. It is a program you run on your own machine against your own broker credentials, and it manages only the positions it opened itself.
The setup it executes — AVWAP-reclaim — did not survive my own adversarial re-test: the signal's own contribution measured +0.030R with a 95% CI of [−0.014, +0.077], crossing zero. That is not a validated edge. This is a well-engineered execution engine wrapped around a strategy I do not believe in enough to fund.
The reasoning behind the guardrails is written out on its own: what has to be true before paper becomes live, why the journal is the system of record, and which brokers publish an API worth building against.
FAQ
It executes one daily-bar setup end to end: it scans a watchlist after the close, sizes a position from a fixed percentage of equity risked against the entry-to-stop distance, places the entry, immediately attaches a stop and a 2R target, and then manages those exits until one fills or a 20-bar time stop fires. There is no intraday logic and none was validated.
No, and it structurally refuses to. Two separate gates stand in the way: a live-capable broker adapter will not start unless ALLOW_LIVE is explicitly set to true, and beyond that the promotion gate blocks real funds until a genuine paper track record exists. The record today is zero closed paper trades, so the gate is shut.
It is a check inside the engine that refuses to trade real money until the journal shows at least 60 closed paper trades at a positive realized expectancy. The rule originally lived only in a markdown design doc, which meant a single environment variable could bypass it, so it was moved into code where it runs on every pass. Overriding it requires a deliberately named environment variable and it logs a warning when used.
Every signal maps to a deterministic client order id, and a SQLite journal claims that id before the broker call rather than after it. On restart the same id is re-derived and the order is skipped instead of being sent twice. A concurrency test runs twelve competing writers against one journal and asserts that exactly one of them wins the claim.
Alpaca, for two reasons: it publishes an official API, and it offers a real paper-trading mode so the safety work can be exercised without money at stake. It is also the only adapter that can express a broker-native OCO exit pair, which means the losing leg is cancelled server-side even while this process is dead. Start on the local paper simulator, which needs no network and no keys.
No, and that is stated deliberately. The setup it executes did not survive an adversarial re-test: the signal's own incremental contribution measured +0.030R with a 95% confidence interval crossing zero, which is not a validated edge. This is an execution engine wrapped around a strategy that has not earned real capital.
There is no paid tier, no account and no telemetry, and it runs entirely on your own machine. The repository is private at the moment rather than published, so access is by request instead of a public clone URL.
This trading bot is an educational and research tool. It is not financial advice, not investment advice, and not a recommendation to buy or sell any security. Every result referenced on this page is backtested or simulated rather than live trading performance, and backtested and past results do not indicate future results. Automated trading carries substantial risk of loss, including the total loss of principal, and software defects, broker outages and network failures can all cause losses beyond what a backtest shows. You are solely responsible for your own trading decisions. See Terms, Privacy and Refunds.
Related: the screener and the audit that broke its result · position-sizing and risk calculators · TradeLog, the offline R-multiple journal · all apps and projects.