TzuTrader Documentation¶

TzuTrader is a trading bot library for Nim that provides tools for building and testing algorithmic trading strategies.

⚠️ Important Disclaimer¶

This software is provided for educational and research purposes only.

• No Financial Advice: TzuTrader does not provide financial, investment, trading, or any other type of professional advice. Any strategies, indicators, or results shown are for informational purposes only.
• No Liability: The authors and contributors are not responsible for any financial losses, damages, or other consequences resulting from the use of this library.
• Trading Risks: Trading financial instruments involves substantial risk of loss. Past performance does not guarantee future results. Backtested results do not represent actual trading and may not reflect the impact of material market factors such as liquidity, slippage, and transaction costs.
• Use at Your Own Risk: Users are solely responsible for their trading decisions and should consult with qualified financial professionals before making any investment decisions.

By using TzuTrader, you acknowledge that you understand these risks and accept full responsibility for your actions.

Documentation Structure¶

TzuTrader provides three types of documentation, each serving a different purpose:

1. User Guide (Start Here!)¶

The User Guide helps you understand concepts and use the library effectively. Written for retail traders with programming experience, it emphasizes understanding over exhaustive coverage.

Chapters:

1. Getting Started - Install TzuTrader and run your first backtest
2. Working with Market Data - Understanding OHLCV data and CSV format
3. Understanding Technical Indicators - What indicators measure and when to use them
4. Building Trading Strategies - Using pre-built strategies and creating custom ones
5. Managing Your Portfolio - Capital allocation, position sizing, and performance tracking
6. Running Backtests - Testing strategies and interpreting results
7. Comparing Strategies - Scanning multiple symbols and ranking results
8. Advanced Workflows - Parameter optimization and batch processing
9. Best Practices - Testing methodology and risk management

2. Reference Guide¶

The Reference Guide provides complete specifications for all features, functions, and parameters. Use this when you need detailed technical information.

Chapters:

1. Core Concepts - OHLCV, signals, positions, and transactions
2. Data Management - CSV I/O, data streaming, and validation
3. Technical Indicators - Complete indicator reference with parameters
4. Trading Strategies - Strategy API and pre-built strategy specifications
5. Portfolio Management - Portfolio API and performance metrics
6. Backtesting Engine - Backtest configuration and report fields
7. Multi-Symbol Scanning - Scanner API, ranking, and filtering
8. Export Capabilities - JSON and CSV export formats
9. CLI Tool - Command-line interface complete reference

3. API Documentation¶

The API Documentation is auto-generated from source code comments. It provides detailed information about every function, type, and module.

Browse: API Documentation

Generate locally: nimble docs

Modules:

• tzutrader - Main module (all exports)
• core - Core types and data structures
• data - Data loading and management
• indicators - Technical indicators
• strategy - Strategy framework
• portfolio - Portfolio management
• trader - Backtesting engine
• scanner - Multi-symbol scanning
• exports - Export functionality

Quick Links¶

New to TzuTrader?¶

1. Read Getting Started
2. Follow the first backtest example
3. Explore the examples in the repository

Looking for Specific Information?¶

• How do I...? → Check the User Guide
• What parameters does X take? → Check the Reference Guide
• What functions are available? → Check the API Documentation

Common Tasks¶

• Load historical data from CSV
• Generate test data
• Calculate technical indicators
• Create a custom strategy
• Run a backtest
• Compare strategies across symbols
• Export results to JSON/CSV
• Use the CLI tool

Installation¶

git clone https://codeberg.org/jailop/tzutrader.git
cd tzutrader
nimble install -y

Requirements: Nim 2.0.0 or later

Quick Example¶

import tzutrader

# Load data
let data = readCSV("data/AAPL.csv")

# Create strategy
let strategy = newRSIStrategy(period = 14, oversold = 30, overbought = 70)

# Run backtest
let report = quickBacktest(
  symbol = "AAPL",
  strategy = strategy,
  data = data,
  initialCash = 100000.0,
  commission = 0.001
)

# View results
echo report.summary()

Limitations¶

At this moment, TzuTrader only supports price-based technical analysis using OHLCV (Open, High, Low, Close, Volume) data. All indicators and strategies in the library operate on this standardized market data format.

Current scope:

• Technical indicators calculate from OHLCV bars
• Pre-built strategies generate signals from price and volume patterns
• Backtesting simulates trading based on historical OHLCV data

Not currently supported:

• Order book data and market microstructure analysis
• Level 2 data or bid-ask spreads
• Alternative data sources (news sentiment, social media, economic indicators)
• Cross-asset correlation strategies requiring synchronized multi-market data
• Tick-level or sub-bar execution modeling

This focused scope allows TzuTrader to maintain its streaming architecture with constant memory usage. For most retail traders working with daily, hourly, or minute bars, OHLCV data provides sufficient information for technical analysis strategies. The library can be extended with custom indicators and strategies that work within this data framework.

About the Name¶

TzuTrader takes its name from Sun Tzu (孫子), the ancient Chinese military strategist and author of The Art of War. Written around the 5^th century BC, this treatise on military strategy has found application far beyond warfare, particularly in business and trading.

Several principles from The Art of War apply directly to algorithmic trading:

"Know the enemy and know yourself; in a hundred battles you will never be in peril." This translates to understanding both market conditions and your strategy's behavior through rigorous backtesting before risking capital.

"The general who wins the battle makes many calculations in his temple before the battle is fought." Systematic backtesting and strategy validation embody this preparation, allowing traders to test ideas thoroughly before deployment.

"In war, numbers alone confer no advantage." Similarly in trading, simply having more indicators or complex strategies does not guarantee success. What matters is disciplined execution of well-tested approaches.

"To secure ourselves against defeat lies in our own hands." Risk management and position sizing—core features of TzuTrader—are tools traders control directly, protecting capital regardless of market outcomes.

The name reflects the library's emphasis on preparation through backtesting, disciplined strategy development, and systematic decision-making based on tested rules rather than emotion or speculation.

Next Steps¶

Ready to start? Head to the Getting Started Guide and run your first backtest in under 15 minutes.