Exhaustively Documented, Generally Experimental
A broker-agnostic intraday algo trading engine for Indian markets (AngelOne / Kotak Neo), built around a plug-and-play strategy-plugin core: every strategy is a self-contained class + config file, discovered automatically, so adding a new one touches no other file. See docs/architecture.md for the full design.
Execution / data: AngelOne SmartAPI (Kotak Neo supported for execution, see hybrid setup below) Exchanges: MCX commodity futures · NSE equities (via options signal) · NFO options Deployed on: EC2 (SEBI static-IP requirement for both brokers)
| Strategy | Instrument | Status | Result |
|---|---|---|---|
momentum_breakout |
SILVERM MCX 15m | ✅ Live winner | Walk-forward OOS +0.218R (85 trades), BUY_ONLY |
sr_fvg_breakout |
SILVERM MCX 15m | 🔶 Research in progress | OOS +0.132R but IS fee-negative; needs tuning |
options_directional |
NIFTY/BANKNIFTY | 🔴 Framework, paper-only | Not wired into live order placement |
Every other strategy tried (Supertrend, Opening Drive, VWAP-Fade, VWAP-Pullback, Range Scalp) was backtested, found to have no edge, and deleted — see docs/strategy_research_log.md for the full record of what was tried and why it didn't work. Nothing here is a guess; every "abandoned" verdict is backed by a walk-forward out-of-sample test.
All configs currently ship with paper_trade: true. Nothing here places real orders until you
change that deliberately — see docs/trading_roadmap.md for the gate
criteria before doing so.
git clone https://github.com/ajxv/edge.git && cd edge
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
nano .env # fill in API keys, client IDs, MPIN, TOTP secrets
# Run the example strategy (paper mode, no validated edge — see configs/examples/sma_crossover.yaml).
# This is the fastest way to see the engine run end to end against your own broker login.
python src/bot.py --config configs/examples/sma_crossover.yamlList every registered strategy:
python -c "from src.strategies.registry import available_strategies; print(available_strategies())"The example above (example_sma_crossover) is a plain SMA-crossover template, included to show
the plugin architecture, not because it has any edge. The one strategy in this repo with an actual
walk-forward-validated result is momentum_breakout (see Status below and
docs/strategy_research_log.md) — swap in
configs/live/mcx_momentum.yaml once you've read docs/capital_guide.md
and docs/trading_roadmap.md. To build your own strategy instead, see
docs/architecture.md — two
files, no other file touched.
For the fuller step-by-step version of the above (own broker account, own instrument, own strategy, validation before going live), see docs/getting_started.md.
configs/
examples/
sma_crossover.yaml template strategy, no validated edge, start here
live/
mcx_momentum.yaml the SILVERM winner, paper_trade: true, ready to paper-run
options.yaml options_directional, paper-only framework
research/
sr_fvg/silverm.yaml in-progress SR+FVG research config
A config's strategy.type selects the plugin; strategy.params holds that plugin's own
parameters, validated against its registered schema at load time. See
docs/architecture.md for
the full schema shape and how to add a new strategy (2 steps, no other file touched).
src/
bot.py Live/paper main loop, strategy-agnostic
broker_interface.py BaseBroker abstract contract
brokers/ angel_one.py (data), kotak_neo.py (execution, hybrid data_provider)
core/ candle_manager, order_manager, state_manager
services/ entry_service, exit_service, risk_manager
strategies/ base_strategy, registry, example_sma_crossover, momentum_breakout, sr_fvg_breakout, options_directional
models/config.py Generic Pydantic config schema
utils/ config_loader, strategy_factory, mcx_contract_manager
backtest/
backtest_engine.py Bar-by-bar simulator, same strategy interface as live
run_backtest.py Single-config, single-symbol backtest CLI
walk_forward.py IS/OOS split + Go/No-Go verdict
exit_matrix.py Sweep exit variants on a fixed entry config
Full walkthrough (live loop data flow, strategy plugin contract, backtest workflow, broker hybrid pattern and migration notes, state/risk management, deployment) in docs/architecture.md.
Kotak Neo executes orders (zero brokerage intraday) but has no historical-data API (confirmed against their support docs). AngelOne supplies market data instead:
KotakNeoBroker(data_provider=AngelOneBroker)
-> order placement, positions, margins -> Kotak Neo
-> get_ohlc (historical candles) -> delegates to AngelOne
The currently shipped live config uses AngelOne for both data and execution (active_broker_id: angel_one). The hybrid path is available but not required. Both brokers require a static IP
(SEBI regulation); the bot runs on EC2 with an Elastic IP — see
deploy/README.md.
- 1% risk per trade (configurable): position sized off the strategy's own structural stop
(
strategy.get_stop_price), the same call the backtest engine makes, so live sizing matches what was actually validated. - Daily circuit breakers: daily loss %, max trades/day, max consecutive losses.
- Paper trade mode: all signals computed and logged, no real orders sent (
paper_trade: true). - Guardrails: max open positions, max attempts per trend, cautionary symbol list.
MCX SILVERM (the validated strategy) needs real futures margin. See docs/capital_guide.md for current numbers and the honest math on why smaller capital doesn't work for this domain. If you're capital-constrained, read that doc before assuming you can just size down.
# Full walk-forward verdict on the live config (the number that matters before going live)
python backtest/walk_forward.py --config configs/live/mcx_momentum.yaml --split 2026-01-01 --capital 500000
# Single-symbol backtest with a full trade log
python backtest/run_backtest.py --symbol SILVERM --exchange MCX --config configs/live/mcx_momentum.yaml
# Compare exit-structure variants on a fixed entry config
python backtest/exit_matrix.py --config configs/live/mcx_momentum.yaml --split 2026-01-01Go/No-Go thresholds (backtest/performance_reporter.py): ≥80 trades, ≥45% win rate, ≥0.3R
expectancy, ≤20% max drawdown. Details in docs/architecture.md.
| File | Contents |
|---|---|
| docs/getting_started.md | Setting this up on your own broker account, own credentials, own strategy |
| docs/architecture.md | Full system reference (read this first) |
| docs/strategy_research_log.md | Every strategy tried, results, why abandoned |
| docs/trading_roadmap.md | Paper → live gate criteria, current path |
| docs/capital_guide.md | Capital requirements per domain, worked examples |
| docs/tuning_guide.md | Every config parameter, what it does, safe ranges |
| docs/strategy_guide.md | Momentum breakout mechanics, MCX fundamentals, log reading |
| docs/options_guide.md | Options education: Greeks, theta, IV, expiry structure |
| deploy/README.md | EC2 setup, Elastic IP, systemd service |
sudo cp deploy/systemd/tradebot.service /etc/systemd/system/
sudo systemctl enable tradebot
sudo systemctl start tradebot
sudo journalctl -u tradebot -fdeploy/systemd/tradebot.service's ExecStart pins a --config path. See
deploy/README.md for the full setup guide (Elastic IP is mandatory — both
brokers reject login without a whitelisted static IP).
Issues and PRs welcome, bug fixes and new broker adapters especially. Strategy contributions have one extra bar: no PR adding a strategy gets merged without walk-forward backtest evidence and an entry in the research log, GO or NO-GO. See CONTRIBUTING.md.
MIT-licensed, see LICENSE. This is a software engineering project, not investment advice or a signal service; see DISCLAIMER.md for the full terms before using any part of it with real capital.
Only momentum_breakout on SILVERM MCX has a walk-forward-validated edge in this repo, everything
else is either research-in-progress or an unwired framework. Always backtest thoroughly, paper
trade for at least 30 days, and confirm strategy profitability before using real money. Read
docs/capital_guide.md and
docs/trading_roadmap.md before starting.