AI4Finance-Foundation/FinRL-Trading

---

About

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:

$$w_t = \mathcal{R}_t\bigl(\mathcal{T}_t\bigl(\mathcal{A}_t\bigl(\mathcal{S}t(\mathcal{X}{\le t})\bigr)\bigr)\bigr)$$

where $\mathcal{S}$ denotes stock selection, $\mathcal{A}$ portfolio allocation, $\mathcal{T}$ timing adjustment, and $\mathcal{R}$ portfolio-level risk overlay. Each transformation is contract-preserving — you can swap any module (e.g. equal-weight $\to$ DRL allocator) without touching the rest of the pipeline, and the same weights flow identically through backtesting and live execution.

---

Architecture

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

---

Strategies

FinRL-X implements three use cases from the paper, each demonstrating different compositions of the weight-centric pipeline.

Use Case 1 — Portfolio Allocation Paradigms

Compares heterogeneous allocation methods under a unified interface:

All methods output the same weight vector, making them directly composable with timing and risk overlays.

Use Case 2 — Rolling Stock Selection + DRL

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.

Use Case 3 — Adaptive Multi-Asset Rotation

A research-grade, walk-forward-safe rotation strategy with daily risk monitoring:

# 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

---

Results

Historical Backtest (Jan 2018 – Oct 2025)

Paper Trading (Oct 2025 – Mar 2026)

Ensemble of Rolling Selection + Adaptive Rotation deployed on Alpaca paper trading:

Dynamic Sector Rotation

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.

---

Quick Start

Option A — One-Command Deploy

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

Option B — Manual Setup with venv

# 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.

Running Strategies via Python

# 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.ipynb

Note: Data files ({SYMBOL}_daily.csv) must exist under data/fmp_daily/ before running. deploy.sh downloads them automatically; for manual setup, either run deploy.sh --strategy adaptive_rotation --mode backtest once, or prepare CSV files with columns date,open,high,low,close,volume.

Configuration

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

Python API

# 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})

---

Evolution from FinRL

Migration from FinRL

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()

---

Comparison with Existing Platforms

---

Contributing

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 Request

Adding 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

---

Citation

@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}
}

License

Apache License 2.0 — see LICENSE.

Disclaimer

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.

---