marketTrade/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python-based algorithmic trading system for financial markets that implements technical indicator analysis, signal generation, decision making, and risk management. It integrates with Tinkoff Invest API for market data and trading.

Development Setup

Environment Setup

• Python 3.9-3.12 (managed via Poetry)
• Install dependencies: poetry install
• Activate virtual environment: poetry shell
• Environment variables are in .env (contains Tinkoff API tokens)

Docker Development

• Build image: docker build -f dockerfiles/Dockerfile -t market-trade .
• Main Dockerfile uses Poetry 1.7.1 and Python 3.11
• Requires SSH mount for private tinkoff-grpc dependency

Running Tests

• Test files located in market_trade/tests/
• Run test: python market_trade/tests/test_decision.py
• Run specific test: python market_trade/tests/test_dataloader.py

Data Tools

Scripts in tools/ directory for data collection:

• save_currencies_data.py - Collect currency market data
• save_shares_data.py - Collect stock market data
• get_shares_stats.py - Generate trading statistics
• Usage: python tools/<script_name>.py [options]

Architecture

Core Trading Pipeline (docs/trading-flow.md)

The system follows this data flow:

1. SELECT INSTRUMENT - Choose trading instrument
2. GET_CANDLES(10000) - Fetch historical candlestick data
3. RETRO TRAINING - Backtest signals on historical data
4. STREAM PROCESSING:
   • Receive real-time market messages
   • Accumulate data in sliding window
   • Update window with each new message
   • Generate trading signals

Module Structure

market_trade/core/ - Core Trading Logic

Signal Processing Chain:

1. Indicators (indicators.py, indicators_v2.py) - Technical indicator calculation

   • Base class: coreIndicator
   • Bollinger Bands: ind_BB
   • All indicator classes (Ind_*.py): ADX, Alligator, DonchianChannel, Envelopes, Gator, Ishimoku, LRI, STD, Stochastic, bollingerBands

2. Signals (signals.py, signals_v2.py) - Signal generation from indicators

   • Base class: coreSignalTrande with three modes:
     • online - Real-time signal generation
     • retro - Expanding window backtesting
     • retroFast - Sliding window backtesting
   • Signal implementations: signal_BB (Bollinger Bands signal)
   • Aggregator: signalAgrigator manages multiple signal instances

3. Decision Manager (decisionManager.py, decisionManager_v2.py) - Trading decisions

   • Class: decsionManager
   • Combines signals from signalAgrigator
   • Uses trandeVoter for probability matrix generation
   • Methods:
     • getSignalTest() - Test signal generation
     • generateMatrixProbability() - Create probability matrices from backtest
     • getOnlineAns() - Real-time decision making

4. Trade Voter (trandeVoter.py) - Probability-based decision weighting

   • Generates probability matrices from historical signal performance
   • Weights multiple signals to produce final decision

5. Risk Manager (riskManager.py) - Position sizing and risk controls

   • Class: riskManager
   • Combines signal decisions with risk parameters

6. Deal Manager (dealManager.py) - Trade execution and management

   • Class: DealManager
   • Manages active positions and orders

Helper Modules:

• CoreTradeMath.py - Mathematical operations for indicators (moving averages, STD)
• CoreDraw.py - Visualization utilities for indicators and signals

market_trade/data/ - Data Loading

• dataloader.py - Contains DukaMTInterface class
  • Converts Dukascopy format candlestick data to internal format
  • Separates bid/ask candlesticks from multi-indexed CSV
  • Handles both file paths and DataFrames

market_trade/tests/ - Testing

• Test files demonstrate usage patterns:
  • test_decision.py - Shows complete decision manager workflow with retro training
  • test_dataloader.py - Data loading tests

External Dependencies

• tinkoff-grpc - Private GitHub repo for Tinkoff Invest API integration
  • Located at: git@github.com:strategy155/tinkoff_grpc.git
  • Used in tools for market data collection
• Data Analysis: pandas, numpy, scipy, matplotlib, plotly, mplfinance
• Web Scraping: requests-html, beautifulsoup4, selenium
• Development: JupyterLab (notebooks in notebooks/)

Key Constants (market_trade/constants.py)

• ROOT_PATH - Project root directory
• CANDLESTICK_DATASETS_PATH - Path to candlestick data: data/candlesticks/
• TEST_CANDLESTICKS_PATH - Test dataset: data/EURUSD_price_candlestick.csv
• TINKOFF_TOKEN_STRING - Production API token (from .env)
• SANDBOX_TOKEN_STRING - Sandbox API token (from .env)
• TINKOFF_API_ADDRESS - API endpoint: 'invest-public-api.tinkoff.ru:443'

Data Formats

Candlestick Data

Expected DataFrame columns:

• date - Timestamp
• open, high, low, close - OHLC price data
• For bid/ask data: Multi-indexed with ('bid'/'ask', 'open'/'high'/'low'/'close')

Signal Configuration Dictionary

{
    'signal_name': {
        'className': signal_class,  # e.g., sig_BB
        'indParams': {...},          # Indicator parameters
        'signalParams': {            # Signal parameters
            'source': 'close',       # Source price column
            'target': 'close'        # Target price column for analysis
        },
        'batchSize': 30              # Window size
    }
}

Development Notes

• Code contains Russian comments and variable names (e.g., "агрегатор", "индикаторы")
• Version 2 modules (*_v2.py) represent newer implementations
• The system uses sliding window approach for real-time signal generation
• Backtesting generates probability matrices that weight signal reliability
• Data symlink: data/ -> /var/data0/markettrade_data