Getting Started with TorchTrade

This guide will help you install TorchTrade and run your first trading environment.

Prerequisites

• Python 3.11 or higher
• CUDA (optional, for GPU acceleration)
• UV - Fast Python package installer

Installation

1. Install UV

UV is a fast Python package installer and environment manager:

# On Unix/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the Repository

git clone https://github.com/TorchTrade/torchtrade.git
cd torchtrade

3. Install Dependencies

# Install TorchTrade and all dependencies
uv sync

# Optional: Install with extra features
uv sync --extra examples         # Deps the scripts under examples/ need
uv sync --extra llm              # LLM actors (OpenAI API + local vLLM/transformers)
uv sync --extra chronos          # Chronos forecasting transforms
uv sync --all-extras             # Install all optional dependencies

# Activate the virtual environment
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

4. Verify Installation

# Run tests to verify everything works
uv run pytest tests/ -v

Your First Environment

Let's create a simple trading environment using historical OHLCV data.

Step 1: Prepare Your Data

TorchTrade expects OHLCV data with the following columns:

import pandas as pd

# Your data should have these columns
df = pd.DataFrame({
    'timestamp': [...],  # datetime or parseable strings
    'open': [...],       # opening prices
    'high': [...],       # high prices
    'low': [...],        # low prices
    'close': [...],      # closing prices
    'volume': [...]      # trading volume
})

Note: You can also use our pre-processed datasets from HuggingFace/Torch-Trade which include various cryptocurrency pairs with 1-minute OHLCV data.

Step 2: Create an Environment

from torchtrade.envs.offline import SequentialTradingEnv, SequentialTradingEnvConfig
import pandas as pd

# Load your data
df = pd.read_csv("btcusdt_1m.csv")
df['timestamp'] = pd.to_datetime(df['timestamp'])

# Configure environment
config = SequentialTradingEnvConfig(
    time_frames=["1min", "5min", "15min"],        # 1m, 5m, 15m bars
    window_sizes=[12, 8, 8],       # Lookback windows
    execute_on="5Min",      # Execute every 5 minutes
    initial_cash=1000,             # Starting capital
    transaction_fee=0.0025,        # 0.25% fee
    slippage=0.001                 # 0.1% slippage
)

# Create environment
env = SequentialTradingEnv(df, config)

Training Your First Policy

Quick Training Run

# Train PPO with default config
uv run python examples/online_rl/ppo/train.py

# Customize with Hydra overrides
uv run python examples/online_rl/ppo/train.py \
    env.symbol="BTC/USD" \
    optim.lr=1e-4 \
    loss.gamma=0.95

See the Examples page for all available algorithms (PPO, DQN, IQL, DSAC, GRPO) and usage guides.

Common Use Cases

Loading Historical Data from HuggingFace

import datasets
import pandas as pd

# Load pre-processed Bitcoin data
ds = datasets.load_dataset("Torch-Trade/btcusdt_spot_1m_03_2023_to_12_2025")
df = ds["train"].to_pandas()
df['timestamp'] = pd.to_datetime(df['timestamp'])

# Create environment
env = SequentialTradingEnv(df, config)

Multi-Timeframe Configuration

config = SequentialTradingEnvConfig(
    time_frames=["1min", "5min", "15min", "60min"],        # 1m, 5m, 15m, 1h
    window_sizes=[12, 8, 8, 24],       # Lookback per timeframe
    execute_on="5Min",          # Execute every 5 minutes
    initial_cash=[1000, 5000],         # Domain randomization
)

The environment will provide observations: - market_data_1Minute_12: [12, num_features] - Last 12 one-minute bars - market_data_5Minute_8: [8, num_features] - Last 40 minutes - market_data_15Minute_8: [8, num_features] - Last 120 minutes - market_data_60Minute_24: [24, num_features] - Last 24 hours

Using Stop-Loss / Take-Profit

from torchtrade.envs.offline import SequentialTradingEnvSLTP, SequentialTradingEnvSLTPConfig

config = SequentialTradingEnvSLTPConfig(
    stoploss_levels=[-0.02, -0.05],     # -2%, -5%
    takeprofit_levels=[0.05, 0.10],     # +5%, +10%
    time_frames=["1min", "5min", "15min"],
    window_sizes=[12, 8, 8],
    execute_on="5Min",
    initial_cash=1000
)

env = SequentialTradingEnvSLTP(df, config)

# Action space: 1 (HOLD) + 2×2 (SL/TP combinations) = 5 actions
# Action 0: HOLD
# Action 1: BUY with SL=-2%, TP=+5%
# Action 2: BUY with SL=-2%, TP=+10%
# Action 3: BUY with SL=-5%, TP=+5%
# Action 4: BUY with SL=-5%, TP=+10%

Live Trading Setup

For live trading with real exchanges, you'll need API credentials.

Alpaca (Crypto Spot)

Alpaca offers commission-free paper trading for testing strategies without risk. See Alpaca Paper Trading Docs for API credentials setup.

# Create .env file
cat > .env << EOF
ALPACA_API_KEY=your_alpaca_api_key
ALPACA_SECRET_KEY=your_alpaca_secret_key
EOF

import os

from dotenv import load_dotenv
from torchtrade.envs.live.alpaca import AlpacaTorchTradingEnv, AlpacaTradingEnvConfig

load_dotenv()  # reads the .env written above; os.getenv does not read files

config = AlpacaTradingEnvConfig(
    symbol="BTC/USD",
    time_frames=["1Min", "5Min"],
    window_sizes=[12, 8],
    execute_on="5Min",
    paper=True  # Start with paper trading!
)

env = AlpacaTorchTradingEnv(
    config,
    api_key=os.getenv("ALPACA_API_KEY"),
    api_secret=os.getenv("ALPACA_SECRET_KEY"),
)

Binance (Crypto Futures)

If you want to trade on Binance, register here in case you have no account. Binance also allows for demo trading, see here.

# Add to .env
BINANCE_API_KEY=your_binance_api_key
BINANCE_SECRET_KEY=your_binance_secret_key

import os

from dotenv import load_dotenv
from torchtrade.envs.live.binance import (
    BinanceFuturesTorchTradingEnv,
    BinanceFuturesTradingEnvConfig
)

load_dotenv()  # reads the .env written above; os.getenv does not read files

config = BinanceFuturesTradingEnvConfig(
    symbol="BTCUSDT",
    time_frames=["1m", "5m"],
    window_sizes=[12, 8],
    execute_on="1m",
    leverage=5,                        # 5x leverage
    demo=True,                         # Use testnet
)

env = BinanceFuturesTorchTradingEnv(
    config,
    api_key=os.getenv("BINANCE_API_KEY"),
    api_secret=os.getenv("BINANCE_SECRET_KEY"),
)

Note: Alpaca and Binance are just two examples of live environments/brokers that TorchTrade supports. For more details on all available exchanges and configurations, see Online Environments. We're always open to including additional brokers - if you'd like to request support for a new exchange, please create an issue or contact us directly at torchtradecontact@gmail.com.

Next Steps

• Offline Environments - Deep dive into backtesting environments
• Online Environments - Live trading with exchange APIs
• Examples - Training scripts for all algorithms

Troubleshooting

• "No module named 'torchtrade'" → Activate the venv: source .venv/bin/activate
• "CUDA out of memory" → Reduce frames_per_batch or set device: "cpu"
• "Columns do not match required format" → Ensure columns are ['timestamp', 'open', 'high', 'low', 'close', 'volume']
• "Environment returns NaN rewards" → Check for NaN/zero prices: df = df.dropna()