fintics 1.0.3

A comprehensive framework for financial data analysis and backtesting trading strategies

Fintics - Trading Bot Framework

Advanced trading bot framework with backtesting and strategy optimization capabilities

Table of Contents

• Installation
• Quick Setup
• Command List
• Custom Strategy Creation
• Available Strategies
• Practical Examples
• Troubleshooting
• Advanced Usage
• Features
• Development

Installation

Prerequisites

Fintics requires TA-Lib, which must be installed at the system level before installing fintics.

macOS:

brew install ta-lib

Ubuntu/Debian:

sudo apt-get install ta-lib

Windows: Download the appropriate wheel file from here and install:

pip install TA_Lib‑0.4.xx‑cp3xx‑cp3xx‑win_amd64.whl

From PyPI (Recommended)

pip install fintics

From Source (For Development)

# Navigate to project directory
cd /path/to/Fintics

# Install (development mode)
pip install -e .

# Or standard installation
pip install .

After installation, the fintics command is available globally.

fintics help
fintics data list
fintics run AAPL --strategy RsiStrategy

Usage

Standard Usage:

fintics <COMMAND> [OPTIONS]

Alternative (Run as Python module):

python -m fintics.cli <COMMAND> [OPTIONS]

Command List

Help

fintics help
fintics -h

Strategy Management

List Available Strategies:

fintics strategy list

Create Custom Strategy Template:

fintics strategy create MyStrategy

# Creates MyStrategy.py
# - Optimization-ready (trial argument support)
# - Sample RSI strategy implementation
# - Comprehensive documentation included

Data Management

List Downloaded Data:

fintics data list

Download Data:

fintics data download <symbol> [--timeframe <TF>]

# Examples:
fintics data download GOOGL
fintics data download AAPL --timeframe 1H

Delete Data:

# Delete specific timeframe
fintics data delete <symbol> --timeframe <TF>

# Delete all timeframes
fintics data delete <symbol>

# Examples:
fintics data delete GOOGL --timeframe 1H
fintics data delete AAPL  # Delete all timeframes

Run Backtest

Basic Execution:

fintics run <symbol> [OPTIONS]

# Examples:
fintics run AAPL
fintics run MSFT --strategy RsiStrategy --start 2023-01-01
fintics run GOOGL --strategy BollingerBandsStrategy --params '{"t": 20, "std": 2.5}'

Using Custom Strategy File:

fintics run <symbol> --strategy-file <PATH> [OPTIONS]

# Examples:
fintics run AAPL --strategy-file ./MyStrategy.py
fintics run MSFT --strategy-file ./custom_strategies/advanced.py --plot

Display Results Plot:

fintics run AAPL --strategy RsiStrategy --plot

Options:

• --timeframe <TF> - Timeframe (e.g., 1H, 1D) [default: 1D]
• --strategy <NAME> - Built-in strategy name [default: KeepPositionStrategy]
• --strategy-file <PATH> - Path to custom strategy .py file
• --params <JSON> - Strategy parameters (JSON format) [default: {}]
• --start <DATE> - Start date (e.g., 2022-01-01)
• --end <DATE> - End date (e.g., 2025-12-31)
• --leverage <FLOAT> - Leverage [default: 1.0]
• --spread <FLOAT> - Spread [default: 0.0]
• --feerate <FLOAT> - Fee rate [default: 0.0]
• --onlybuy / --no-onlybuy - Long positions only [default: True]
• --reverse / --no-reverse - Reverse signals [default: False]
• --plot - Display performance chart [default: False]

Optimization

Optimize Single Strategy:

fintics optimize <symbol> [OPTIONS]

# Examples:
fintics optimize AAPL --strategy RsiStrategy
fintics optimize MSFT --strategy MacdStrategy --n_trials 200 --target sharperatio

Optimize Custom Strategy File:

fintics optimize <symbol> --strategy-file <PATH> [OPTIONS]

# Examples:
fintics optimize AAPL --strategy-file ./MyStrategy.py --n_trials 100
fintics optimize GOOGL --strategy-file ./advanced.py --n_trials 200 --plot

Optimize All Strategies:

fintics optimize_all <symbol> [OPTIONS]

# Examples:
fintics optimize_all BTCUSD --n_trials 50
fintics optimize_all GOOGL --n_trials 100 --target profit

# Note: --plot option is not available for optimize_all

Optimization Options:

• --n_trials <INT> - Number of optimization trials [default: 100]
• --target <METRIC> - Target optimization metric [default: profit]
  • Available: profit, sharperatio, winrate, etc.
• --plot - Plot optimization results (not available for optimize_all)

Custom Strategy Creation Guide

1. Generate Template File

fintics strategy create MyStrategy

Generated MyStrategy.py:

import pandas as pd
from fintics.strategy import Strategy
from fintics.indicator import Indicator

class MyStrategy(Strategy):
    def __init__(self, df: pd.DataFrame, rsi_period: int = 14, ma_short: int = 10, 
                 ma_long: int = 30, trial=None, reverse: bool = False):
        # Parameter suggestions for optimization
        if trial:
            rsi_period = trial.suggest_int('rsi_period', 5, 30)
            ma_short = trial.suggest_int('ma_short', 5, 20)
            ma_long = trial.suggest_int('ma_long', 20, 50)
        
        # Calculate indicators
        rsi = Indicator.RSI(df['Close'], timeperiod=rsi_period)
        ma_short_values = Indicator.SMA(df['Close'], timeperiod=ma_short)
        ma_long_values = Indicator.SMA(df['Close'], timeperiod=ma_long)
        
        # Generate signals
        df['y'] = 0
        
        # Buy signal: MA crossover AND RSI < 70
        buy_condition = (
            (ma_short_values > ma_long_values) & 
            (ma_short_values.shift(1) <= ma_long_values.shift(1)) & 
            (rsi < 70)
        )
        df.loc[buy_condition, 'y'] = 1
        
        # Sell signal: MA crossover OR RSI > 70
        sell_condition = (
            (ma_short_values < ma_long_values) & 
            (ma_short_values.shift(1) >= ma_long_values.shift(1)) | 
            (rsi > 70)
        )
        df.loc[sell_condition, 'y'] = -1
        
        super().__init__(df)

2. Test Strategy

fintics run AAPL --strategy-file MyStrategy.py

3. Optimize Parameters

fintics optimize AAPL --strategy-file MyStrategy.py --n_trials 200 --plot

4. Run with Optimal Parameters

fintics run AAPL --strategy-file MyStrategy.py --params '{"rsi_period": 25, "ma_short": 15, "ma_long": 45}' --plot

Available Strategies

List all strategies:

fintics strategy list

49 built-in strategies available, including:

• RsiStrategy - RSI-based strategy
• MacdStrategy - MACD strategy
• BollingerBandsStrategy - Bollinger Bands strategy
• StochasticStrategy - Stochastic oscillator strategy
• IchimokuCloudStrategy - Ichimoku Cloud strategy
• And more...

Default parameters for each strategy are displayed in JSON format:

====================================================================================================
Strategy Name                       Default Parameters
----------------------------------------------------------------------------------------------------
RsiStrategy                        {"t": 14}
MacdStrategy                       {"fast": 12, "slow": 26, "signal": 9}
BollingerBandsStrategy             {"t": 4, "std": 2, "ma_type": 2}
ParabolicSarStrategy              {"acceleration": 0.02, "maximum": 0.2}
====================================================================================================
Total: 49 strategies

Practical Examples

Example 1: Download Data and Run Backtest

# Download data
fintics data download AAPL

# Backtest with RSI strategy
fintics run AAPL --strategy RsiStrategy --plot

# Specify date range
fintics run AAPL --strategy RsiStrategy --start 2023-01-01 --end 2024-12-31 --plot

Example 2: Create and Optimize Custom Strategy

# Create strategy template
fintics strategy create TrendFollowing

# Edit and implement logic
# nano TrendFollowing.py

# Test run
fintics run MSFT --strategy-file TrendFollowing.py

# Optimize parameters
fintics optimize MSFT --strategy-file TrendFollowing.py --n_trials 300 --target sharperatio --plot

# Run with optimal parameters
fintics run MSFT --strategy-file TrendFollowing.py --params '{"ma_short": 15, "ma_long": 45}' --plot

Example 3: Multi-Timeframe Analysis

# Download hourly data
fintics data download BTCUSD --timeframe 1H

# Backtest on 1H timeframe
fintics run BTCUSD --timeframe 1H --strategy MacdStrategy --plot

# Compare with daily timeframe
fintics run BTCUSD --timeframe 1D --strategy MacdStrategy --plot

Example 4: Data Management

# Check downloaded data
fintics data list

# Delete unnecessary data
fintics data delete GOOGL --timeframe 1H

# Delete all data for a symbol
fintics data delete OLD_SYMBOL

Troubleshooting

Q: "No cached data" error occurs

# Download the data first
fintics data download <SYMBOL> --timeframe 1D

Q: Custom Strategy not found

• Verify file path is correct
• Ensure Strategy class is defined
• Check from fintics.strategy import Strategy is imported
• Important: File name must match class name (e.g., MyStrategy.py must contain class MyStrategy)

Q: Optimization is slow

• Reduce --n_trials (start with 50-100)
• Limit data range with --start/--end

Q: setup command cannot detect shell

Supported shells: zsh, bash, fish

Manually add alias:

# Add to ~/.zshrc or ~/.bashrc
alias fintics='python -m fintics.cli'

Advanced Usage

Leverage and Spread Consideration

fintics run BTCUSD --strategy RsiStrategy --leverage 2.0 --spread 0.001 --feerate 0.0005

Allow Short Positions

fintics run AAPL --strategy RsiStrategy --no-onlybuy

Reverse Signals

fintics run MSFT --strategy RsiStrategy --reverse

Batch Optimize All Strategies

fintics optimize_all GOOGL --n_trials 100 --target sharperatio

Parameter Specification

You can copy and paste JSON format displayed in strategy list:

# Check strategy list
fintics strategy list | grep "Parabolic"
# Output: ParabolicSarStrategy {"acceleration": 0.02, "maximum": 0.2}

# Copy and use directly
fintics run AAPL --strategy ParabolicSarStrategy --params '{"acceleration": 0.02, "maximum": 0.2}'

🎉 Features

• ✅ 49 Built-in Trading Strategies - Ready-to-use professional strategies
• ✅ Powerful Backtest Engine - Comprehensive backtesting with real-world constraints
• ✅ Optuna-based Optimization - Advanced parameter optimization
• ✅ TradingView Data Integration - Download data via TradingView
• ✅ Custom Strategy Support - Create and optimize your own strategies
• ✅ Comprehensive Performance Metrics - 20+ metrics including Sharpe ratio, profit factor, drawdown, etc.
• ✅ Command-line Interface - Easy-to-use CLI with intuitive commands
• ✅ Plot Visualization - Visual performance analysis with charts
• ✅ Multi-timeframe Support - Backtest on various timeframes (1H, 1D, etc.)
• ✅ Data Management - Download, list, and delete cached data

New Features

Custom Strategy Creation

fintics strategy create MyStrategy

• Generates optimization-ready template
• File name must match class name
• Includes sample implementation with multiple indicators

Enhanced Optimization Results

• Display all 20+ BacktestResult metrics
• Top 10 results comparison table
• Detailed best result summary

Example output:

================================================================================
OPTIMIZATION RESULTS
================================================================================

Best profit: 106106.7226
Best params: {"t": 102}

--------------------------------------------------------------------------------
Best Result Summary:
--------------------------------------------------------------------------------
  profit              :     106106.7226
  growth              :     158769.6156
  avg_profit          :        614.2976
  win_rate            :          0.2617
  n_trades            :            149
  efficiency          :          0.6776
  PD                  :     343721.1616
  PDE                 :     247719.0732
  max_dd_rate         :         -0.3087
  sharperatio         :          4.5104
  profitfactor        :          5.1147
  ...and more metrics
================================================================================

Flexible Data Management

# Delete specific timeframe
fintics data delete GOOGL --timeframe 1H

# Delete all timeframes for a symbol
fintics data delete GOOGL

Performance Visualization

# Add --plot to see charts
fintics run AAPL --strategy RsiStrategy --plot
fintics optimize MSFT --strategy MacdStrategy --n_trials 100 --plot

Tips

• Use Plots: Use --plot option to visualize results
• Start Small: Begin optimization with --n_trials 50
• Limit Date Range: Use --start/--end to limit testing period
• Custom Strategies: Improve based on existing built-in strategies
• Data Cleanup: Regularly delete old data to save space

Summary

Fintics CLI provides:

✅ 49 Built-in Strategies - High-quality strategies ready to use
✅ Custom Strategy Creation - Easy implementation from templates
✅ Automatic Optimization - Advanced parameter optimization with Optuna
✅ Visualization - Intuitive understanding with plot features
✅ Flexible Data Management - Download, delete, multi-timeframe support
✅ User-friendly CLI - Intuitive command structure

🔧 Development

Run Tests

pytest tests/ -v

Code Formatting

black fintics/
isort fintics/

📝 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests.

📞 Support

For help:

fintics help

For issues and feature requests, please visit the project repository.