A deployment-consistent trading system that unifies data processing, strategy composition, backtesting, and broker execution through a weight-centric interface.
Paper | Quick Start | Strategies | Results | Discord
FinRL-X is a next-generation, AI-native quantitative trading infrastructure that redefines how researchers and practitioners build, test, and deploy algorithmic trading strategies.
Introduced in our paper "FinRL-X: An AI-Native Modular Infrastructure for Quantitative Trading" (arXiv:2603.21330), FinRL-X succeeds the original FinRL framework with a fully modernized architecture designed for the LLM and agentic AI era.
FinRL-X is not just a library — it is a full-stack trading platform engineered around modularity, reproducibility, and production-readiness, supporting everything from ML-based stock selection and professional backtesting to live brokerage execution.
At its core is a weight-centric architecture — the target portfolio weight vector is the sole interface contract between strategy logic and downstream execution:
where
| Layer | Role | Components |
|---|---|---|
| Data | Unified market data pipeline | FMP, Yahoo Finance, WRDS; LLM sentiment preprocessing; SQLite cache |
| Strategy | Weight-centric signal generation | Stock selection, portfolio allocation, timing adjustment, risk overlay |
| Backtest | Offline evaluation | bt-powered engine with multi-benchmark comparison and transaction costs |
| Execution | Live/paper trading | Alpaca multi-account integration with pre-trade risk checks |
finrl-trading/
├── src/
│ ├── config/ # ⚙️ Centralized configuration management
│ │ └── settings.py # Pydantic-based settings + environment variables
│ ├── data/ # 🗄️ Data acquisition and processing
│ │ ├── data_fetcher.py # Multi-source integration (Yahoo / FMP / WRDS)
│ │ ├── data_processor.py # Feature engineering & data cleaning
│ │ └── data_store.py # SQLite persistence with caching
│ ├── backtest/ # 📊 Backtesting engine
│ │ └── backtest_engine.py # bt-powered engine with benchmark comparison
│ ├── strategies/ # 🤖 Trading strategies
│ │ ├── base_strategy.py # Abstract strategy framework
│ │ └── ml_strategy.py # Random Forest stock selection
│ ├── trading/ # 💰 Live trading execution
│ │ ├── alpaca_manager.py # Alpaca API integration (multi-account)
│ │ ├── trade_executor.py # Order management & risk controls
│ │ └── performance_analyzer.py # Real-time P&L tracking
│ └── main.py # 🚀 CLI entry point
├── examples/
│ ├── FinRL_Full_Workflow.ipynb # 📓 Complete workflow tutorial (start here!)
│ └── README.md
├── data/ # Runtime data storage (gitignored)
├── logs/ # Application logs (gitignored)
├── requirements.txt
└── setup.py
FinRL-X implements three use cases from the paper, each demonstrating different compositions of the weight-centric pipeline.
Compares heterogeneous allocation methods under a unified interface:
| Method | Type | Description |
|---|---|---|
| Equal Weight | Classical | Uniform 1/N allocation |
| Mean-Variance | Classical | Markowitz optimization |
| Minimum Variance | Classical | Minimize portfolio volatility |
| DRL Allocator | Learning | PPO/SAC continuous weight generation |
| KAMA Timing | Signal | Kaufman adaptive trend overlay |
All methods output the same weight vector, making them directly composable with timing and risk overlays.
Quarterly selection of top-25% NASDAQ-100 stocks via ML fundamental scoring, combined with DRL-based portfolio allocation. Strict no-lookahead semantics prevent data leakage.
A research-grade, walk-forward-safe rotation strategy with daily risk monitoring:
| Component | Detail |
|---|---|
| Asset Groups | Growth Tech, Real Assets, Defensive — max 2 active per week |
| Group Selection | Information Ratio relative to QQQ benchmark |
| Intra-Group Ranking | Residual momentum with robust Z-score exception handling |
| Market Regime | Slow regime (26-week trend + VIX) + Fast Risk-Off (3-day shock) |
| Risk Controls | Trailing stop-loss, absolute stop-loss, cooldown periods |
| Rebalance | Weekly (full) + daily monitoring (fast risk-off, stop-loss adjustments) |
# Run the adaptive rotation backtest
./deploy.sh --strategy adaptive_rotation --mode backtest --start 2023-01-01 --end 2024-12-31
# Paper trade with Alpaca
./deploy.sh --strategy adaptive_rotation --mode paper --dry-run
| Metric | Rolling Strategy | Adaptive Rotation | QQQ | SPY |
|---|---|---|---|---|
| Cumulative Return | 5.98x | 4.80x | 4.02x | 2.80x |
| Annualized Return | 25.85% | 22.32% | 19.56% | 14.14% |
| Annualized Volatility | 27.85% | 20.30% | 24.20% | 19.61% |
| Sharpe Ratio | 0.93 | 1.10 | 0.81 | 0.72 |
| Max Drawdown | -38.95% | -21.46% | -35.12% | -33.72% |
| Calmar Ratio | 0.66 | 1.04 | 0.56 | 0.42 |
| Win Rate | 54.36% | 54.77% | 56.25% | 55.28% |
Ensemble of Rolling Selection + Adaptive Rotation deployed on Alpaca paper trading:
| Metric | Strategy | SPY | QQQ |
|---|---|---|---|
| Cumulative Return | 1.20x | 0.97x | 0.95x |
| Total Return | +19.76% | -2.51% | -4.79% |
| Annualized Return | 62.16% | -6.60% | -12.32% |
| Annualized Volatility | 31.75% | 11.96% | 16.79% |
| Sharpe Ratio | 1.96 | -0.55 | -0.73 |
| Max Drawdown | -12.22% | -5.35% | -7.88% |
| Calmar Ratio | 5.09 | -1.23 | -1.56 |
| Win Rate | 64.89% | 52.13% | 54.02% |
The Adaptive Rotation strategy dynamically shifts capital across three asset groups — Growth Tech, Real Assets, and Defensive — based on market regime signals. During risk-on regimes, the portfolio tilts toward high-momentum growth and commodity plays; when regime detection flags risk-off or fast risk-off conditions, capital rotates into bonds and utilities with an automatic cash buffer. Weekly rebalancing is complemented by daily stop-loss and fast risk-off monitoring, enabling rapid de-risking without waiting for the next scheduled rebalance.
deploy.sh handles everything automatically: dependency check, data download, and strategy execution.
git clone https://github.com/AI4Finance-Foundation/FinRL-Trading.git
cd FinRL-Trading
# Backtest (downloads data + runs strategy)
./deploy.sh --strategy adaptive_rotation --mode backtest
# Custom date range
./deploy.sh --strategy adaptive_rotation --mode backtest --start 2020-01-01 --end 2025-12-31
# Single date signal
./deploy.sh --strategy adaptive_rotation --mode single --date 2024-12-31
# Paper trading (requires Alpaca credentials in .env)
./deploy.sh --strategy adaptive_rotation --mode paper --dry-run # preview
./deploy.sh --strategy adaptive_rotation --mode paper # execute
# See all options
./deploy.sh --help# 1. Clone
git clone https://github.com/AI4Finance-Foundation/FinRL-Trading.git
cd FinRL-Trading
# 2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # Linux / macOS
# venv\Scripts\activate # Windows
# 3. Install dependencies
pip install -r requirements.txt
# 4. (Optional) Configure API keys for paper trading
cp .env.example .env
# Edit .env — set APCA_API_KEY, APCA_API_SECRET, etc.# Backtest — Adaptive Rotation (2023-01-01 to 2024-12-31)
python src/strategies/run_adaptive_rotation_strategy.py \
--config src/strategies/AdaptiveRotationConf_v1.2.1.yaml \
--backtest --start 2023-01-01 --end 2024-12-31
# Single date signal
python src/strategies/run_adaptive_rotation_strategy.py \
--config src/strategies/AdaptiveRotationConf_v1.2.1.yaml \
--date 2024-12-31
# Full workflow tutorial (Jupyter)
jupyter notebook examples/FinRL_Full_Workflow.ipynbNote: Data files (
{SYMBOL}_daily.csv) must exist underdata/fmp_daily/before running.deploy.shdownloads them automatically; for manual setup, either rundeploy.sh --strategy adaptive_rotation --mode backtestonce, or prepare CSV files with columnsdate,open,high,low,close,volume.
cp .env.example .env# Alpaca (required for paper/live trading)
APCA_API_KEY=your_key
APCA_API_SECRET=your_secret
APCA_BASE_URL=https://paper-api.alpaca.markets
# Data source (optional; Yahoo Finance is the free default)
FMP_API_KEY=your_fmp_key# Data
from src.data.data_fetcher import get_data_manager
manager = get_data_manager()
prices = manager.get_price_data(['AAPL', 'MSFT'], '2020-01-01', '2024-12-31')
# Strategy
from src.strategies.ml_strategy import MLStockSelectorStrategy
strategy = MLStockSelectorStrategy(config)
result = strategy.generate_weights(data)
# Backtest
from src.backtest.backtest_engine import BacktestEngine, BacktestConfig
engine = BacktestEngine(BacktestConfig(start_date='2020-01-01', end_date='2024-12-31'))
result = engine.run_backtest("My Strategy", weights, prices)
# Live trade
from src.trading.alpaca_manager import create_alpaca_account_from_env, AlpacaManager
alpaca = AlpacaManager([create_alpaca_account_from_env()])
alpaca.execute_portfolio_rebalance(target_weights={'AAPL': 0.3, 'MSFT': 0.7})| FinRL (2020) | FinRL-X (2026) | |
|---|---|---|
| Paradigm | DRL-only | AI-Native (ML + DRL + LLM-ready) |
| Architecture | Coupled monolith | Decoupled modular layers |
| Interface | Gym state/action spaces | Weight-centric contract |
| Data | 14 manual processors | Auto-select: Yahoo / FMP / WRDS |
| Backtesting | Hand-rolled loops | bt engine + multi-benchmark |
| Live Trading | Basic Alpaca | Multi-account + risk controls |
| Config | config.py |
Pydantic + .env |
| Paper | arXiv:2011.09607 | arXiv:2603.21330 |
FinRL → FinRL-X
─────────────────────────────────────────────────────────────
finrl/meta/data_processor.py → src/data/data_fetcher.py
finrl/train.py → strategy.generate_weights()
finrl/trade.py → TradeExecutor.execute_portfolio_rebalance()
config.py + config_tickers.py → src/config/settings.py (Pydantic + .env)
gym.Env subclassing → BaseStrategy.generate_weights()
| Feature | FinRL-X | Qlib | TradingAgents | Zipline/Backtrader | QuantConnect Lean |
|---|---|---|---|---|---|
| Primary Orientation | End-to-End System | ML Research | Agent-Based Trading | Backtesting | End-to-End Platform |
| Broker Integration | Yes | - | - | - | Yes |
| Deployment-Consistent Interface | Yes | - | - | - | Partial |
| Reinforcement Learning Support | Yes | Limited | Yes | - | Partial |
| Modular Strategy Pipeline | Yes | - | - | - | Partial |
| Portfolio-Level Risk Overlay | Yes | - | - | - | Partial |
| Open Source License | Apache 2.0 | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 |
git checkout -b feature/your-feature
pip install -r requirements.txt
# make changes, add tests
git commit -m "Add: your feature"
git push origin feature/your-feature
# open a Pull RequestAdding a custom strategy:
from src.strategies.base_strategy import BaseStrategy, StrategyConfig, StrategyResult
class MyStrategy(BaseStrategy):
def generate_weights(self, data, **kwargs) -> StrategyResult:
# your alpha logic — return portfolio weights
pass@inproceedings{yang2026finrlx,
title = {FinRL-X: An AI-Native Modular Infrastructure for Quantitative Trading},
author = {Yang, Hongyang and Zhang, Boyu and She, Yang and Liao, Xinyu and Zhang, Xiaoli},
booktitle = {Proceedings of the 2nd International Workshop on Decision Making and Optimization in Financial Technologies (DMO-FinTech)},
year = {2026},
note = {Workshop at PAKDD 2026}
}Apache License 2.0 — see LICENSE.
This software is for educational and research purposes only. Not financial advice. Always consult qualified professionals before making investment decisions. Past performance does not guarantee future results.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}