kfox/crypto_trader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Local changes: Updated model training, removed debug instrumentation, and configuration improvements

Browse Source
This commit is contained in:
kfox
2025-12-26 01:15:43 -05:00
commit cc60da49e7
388 changed files with 57127 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/api/Makefile Normal file
View File

@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

35
docs/api/make.bat Normal file
View File

@@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

29
docs/api/source/alerts.rst Normal file
View File

@@ -0,0 +1,29 @@
Alert System
============
Alert system for price, indicator, risk, and system notifications.
Alert Engine
------------
.. automodule:: src.alerts.engine
:members:
:undoc-members:
:show-inheritance:
Alert Manager
-------------
.. automodule:: src.alerts.manager
:members:
:undoc-members:
:show-inheritance:
Alert Channels
--------------
.. automodule:: src.alerts.channels
:members:
:undoc-members:
:show-inheritance:

37
docs/api/source/backtesting.rst Normal file
View File

@@ -0,0 +1,37 @@
Backtesting Engine
==================
The backtesting engine enables strategy evaluation on historical data.
Backtesting Engine
------------------
.. automodule:: src.backtesting.engine
:members:
:undoc-members:
:show-inheritance:
Performance Metrics
-------------------
.. automodule:: src.backtesting.metrics
:members:
:undoc-members:
:show-inheritance:
Slippage and Fees
-----------------
.. automodule:: src.backtesting.slippage
:members:
:undoc-members:
:show-inheritance:
Data Provider
-------------
.. automodule:: src.backtesting.data_provider
:members:
:undoc-members:
:show-inheritance:

80
docs/api/source/conf.py Normal file
View File

@@ -0,0 +1,80 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import sys
import os
# Add the project root to the path
sys.path.insert(0, os.path.abspath('../../..'))
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'Crypto Trader'
copyright = '2025, kfox'
author = 'kfox'
release = '0.1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon', # For Google-style docstrings
'sphinx_autodoc_typehints', # Type hints in docs
]
templates_path = ['_templates']
exclude_patterns = []
# Napoleon settings for Google-style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
# Autodoc settings
autodoc_default_options = {
'members': True,
'undoc-members': True,
'show-inheritance': True,
'special-members': '__init__',
}
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_theme_options = {
'collapse_navigation': False,
'display_version': True,
'logo_only': False,
}
# -- Options for intersphinx extension ---------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'pandas': ('https://pandas.pydata.org/docs/', None),
'sqlalchemy': ('https://docs.sqlalchemy.org/en/latest/', None),
'ccxt': ('https://docs.ccxt.com/en/latest/', None),
}
# -- Options for todo extension ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
todo_include_todos = True

94
docs/api/source/data.rst Normal file
View File

@@ -0,0 +1,94 @@
Data Collection and Indicators
================================
Data collection, storage, and technical indicator calculations.
Technical Indicators
--------------------
.. automodule:: src.data.indicators
:members:
:undoc-members:
:show-inheritance:
Data Collector
--------------
.. automodule:: src.data.collector
:members:
:undoc-members:
:show-inheritance:
Data Storage
------------
.. automodule:: src.data.storage
:members:
:undoc-members:
:show-inheritance:
Data Quality
------------
.. automodule:: src.data.quality
:members:
:undoc-members:
:show-inheritance:
Pricing Service
---------------
The unified pricing service manages multiple data providers with automatic failover.
.. automodule:: src.data.pricing_service
:members:
:undoc-members:
:show-inheritance:
Pricing Providers
-----------------
Base Provider Interface
~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: src.data.providers.base_provider
:members:
:undoc-members:
:show-inheritance:
CCXT Provider
~~~~~~~~~~~~~
.. automodule:: src.data.providers.ccxt_provider
:members:
:undoc-members:
:show-inheritance:
CoinGecko Provider
~~~~~~~~~~~~~~~~~~
.. automodule:: src.data.providers.coingecko_provider
:members:
:undoc-members:
:show-inheritance:
Cache Manager
-------------
Intelligent caching system for pricing data.
.. automodule:: src.data.cache_manager
:members:
:undoc-members:
:show-inheritance:
Health Monitor
--------------
Provider health monitoring and failover management.
.. automodule:: src.data.health_monitor
:members:
:undoc-members:
:show-inheritance:

40
docs/api/source/exchanges.rst Normal file
View File

@@ -0,0 +1,40 @@
Exchange Adapters
=================
The exchange adapter system provides a unified interface for trading on multiple cryptocurrency exchanges.
Base Exchange Adapter
---------------------
.. automodule:: src.exchanges.base
:members:
:undoc-members:
:show-inheritance:
Exchange Factory
----------------
.. automodule:: src.exchanges.factory
:members:
:undoc-members:
:show-inheritance:
Coinbase Exchange
-----------------
.. automodule:: src.exchanges.coinbase
:members:
:undoc-members:
:show-inheritance:
WebSocket Support
-----------------
The Coinbase adapter includes WebSocket subscription methods:
- ``subscribe_ticker()``: Subscribe to real-time price updates
- ``subscribe_orderbook()``: Subscribe to order book changes
- ``subscribe_trades()``: Subscribe to trade executions
These methods support real-time data streaming for UI updates.

27
docs/api/source/index.rst Normal file
View File

@@ -0,0 +1,27 @@
Crypto Trader API Documentation
================================
Welcome to the Crypto Trader API documentation. This documentation provides comprehensive reference for all public APIs, classes, and functions in the Crypto Trader application.
.. toctree::
:maxdepth: 2
:caption: API Reference:
modules
exchanges
strategies
trading
backtesting
portfolio
risk
data
market_data
alerts
security
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

312
docs/api/source/market_data.rst Normal file
View File

@@ -0,0 +1,312 @@
Market Data API
===============
REST API endpoints for market data and pricing information.
Market Data Endpoints
---------------------
OHLCV Data
~~~~~~~~~~
**GET** ``/api/market-data/ohlcv/{symbol}``
Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a symbol.
**Parameters:**
- ``symbol`` (path, required): Trading pair symbol (e.g., "BTC/USD")
- ``timeframe`` (query, optional): Timeframe for candles (default: "1h")
- Valid values: "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"
- ``limit`` (query, optional): Number of candles to return (default: 100, max: 1000)
- ``exchange`` (query, optional): Exchange name (deprecated, uses pricing service)
**Response:**
.. code-block:: json
[
{
"time": 1609459200,
"open": 50000.0,
"high": 51000.0,
"low": 49000.0,
"close": 50000.0,
"volume": 1000.0
}
]
**Example:**
.. code-block:: bash
curl http://localhost:8000/api/market-data/ohlcv/BTC%2FUSD?timeframe=1h&limit=100
Ticker Data
~~~~~~~~~~~
**GET** ``/api/market-data/ticker/{symbol}``
Get current ticker data for a symbol, including price, volume, and provider information.
**Parameters:**
- ``symbol`` (path, required): Trading pair symbol (e.g., "BTC/USD")
**Response:**
.. code-block:: json
{
"symbol": "BTC/USD",
"bid": 50000.0,
"ask": 50001.0,
"last": 50000.5,
"high": 51000.0,
"low": 49000.0,
"volume": 1000000.0,
"timestamp": 1609459200000,
"provider": "CCXT-Kraken"
}
**Example:**
.. code-block:: bash
curl http://localhost:8000/api/market-data/ticker/BTC%2FUSD
Provider Health
~~~~~~~~~~~~~~~
**GET** ``/api/market-data/providers/health``
Get health status for pricing providers.
**Parameters:**
- ``provider`` (query, optional): Specific provider name to get health for
**Response:**
.. code-block:: json
{
"active_provider": "CCXT-Kraken",
"health": {
"CCXT-Kraken": {
"status": "healthy",
"last_check": "2025-01-01T12:00:00Z",
"last_success": "2025-01-01T12:00:00Z",
"success_count": 100,
"failure_count": 2,
"avg_response_time": 0.123,
"consecutive_failures": 0,
"circuit_breaker_open": false
}
}
}
**Example:**
.. code-block:: bash
curl http://localhost:8000/api/market-data/providers/health?provider=CCXT-Kraken
Provider Status
~~~~~~~~~~~~~~~
**GET** ``/api/market-data/providers/status``
Get detailed status for all pricing providers, including cache statistics.
**Response:**
.. code-block:: json
{
"active_provider": "CCXT-Kraken",
"providers": {
"CCXT-Kraken": {
"status": "healthy",
"last_check": "2025-01-01T12:00:00Z",
"success_count": 100,
"failure_count": 2,
"avg_response_time": 0.123
},
"CoinGecko": {
"status": "unknown",
"success_count": 0,
"failure_count": 0
}
},
"cache": {
"size": 50,
"max_size": 1000,
"hits": 1000,
"misses": 200,
"hit_rate": 83.33,
"evictions": 0,
"avg_age_seconds": 30.5
}
}
**Example:**
.. code-block:: bash
curl http://localhost:8000/api/market-data/providers/status
Provider Configuration
~~~~~~~~~~~~~~~~~~~~~~
**GET** ``/api/market-data/providers/config``
Get current provider configuration.
**Response:**
.. code-block:: json
{
"primary": [
{
"name": "kraken",
"enabled": true,
"priority": 1
},
{
"name": "coinbase",
"enabled": true,
"priority": 2
}
],
"fallback": {
"name": "coingecko",
"enabled": true,
"api_key": ""
},
"caching": {
"ticker_ttl": 2,
"ohlcv_ttl": 60,
"max_cache_size": 1000
},
"websocket": {
"enabled": true,
"reconnect_interval": 5,
"ping_interval": 30
}
}
**Example:**
.. code-block:: bash
curl http://localhost:8000/api/market-data/providers/config
Update Provider Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**PUT** ``/api/market-data/providers/config``
Update provider configuration.
**Request Body:**
.. code-block:: json
{
"primary": [
{
"name": "kraken",
"enabled": true,
"priority": 1
}
],
"caching": {
"ticker_ttl": 5,
"ohlcv_ttl": 120
}
}
**Response:**
.. code-block:: json
{
"message": "Configuration updated successfully",
"config": {
"primary": [...],
"fallback": {...},
"caching": {...},
"websocket": {...}
}
}
**Example:**
.. code-block:: bash
curl -X PUT http://localhost:8000/api/market-data/providers/config \
-H "Content-Type: application/json" \
-d '{"caching": {"ticker_ttl": 5}}'
WebSocket Updates
-----------------
The WebSocket endpoint at ``/ws`` broadcasts real-time price updates.
**Connection:**
.. code-block:: javascript
const ws = new WebSocket('ws://localhost:8000/ws');
ws.onopen = () => {
// Subscribe to symbol updates
ws.send(JSON.stringify({
type: 'subscribe',
symbol: 'BTC/USD'
}));
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
if (message.type === 'price_update') {
console.log('Price update:', message);
}
};
**Message Types:**
- ``subscribe``: Subscribe to price updates for a symbol
- ``unsubscribe``: Unsubscribe from price updates
- ``price_update``: Price update broadcast (contains exchange, symbol, price, timestamp)
- ``provider_status_update``: Provider status change notification
**Price Update Message:**
.. code-block:: json
{
"type": "price_update",
"exchange": "pricing",
"symbol": "BTC/USD",
"price": "50000.50",
"timestamp": "2025-01-01T12:00:00Z"
}
Error Responses
---------------
All endpoints may return standard HTTP error codes:
- ``400 Bad Request``: Invalid request parameters
- ``404 Not Found``: Symbol or provider not found
- ``500 Internal Server Error``: Server error
Error response format:
.. code-block:: json
{
"detail": "Error message describing what went wrong"
}

18
docs/api/source/modules.rst Normal file
View File

@@ -0,0 +1,18 @@
Modules
=====
.. automodule:: src.core
:members:
:undoc-members:
:show-inheritance:
Core Modules
------------
.. toctree::
:maxdepth: 2
core/config
core/database
core/logger

21
docs/api/source/portfolio.rst Normal file
View File

@@ -0,0 +1,21 @@
Portfolio Management
====================
Portfolio tracking and analytics for monitoring trading performance.
Portfolio Tracker
-----------------
.. automodule:: src.portfolio.tracker
:members:
:undoc-members:
:show-inheritance:
Portfolio Analytics
-------------------
.. automodule:: src.portfolio.analytics
:members:
:undoc-members:
:show-inheritance:

37
docs/api/source/risk.rst Normal file
View File

@@ -0,0 +1,37 @@
Risk Management
===============
Risk management system for controlling trading exposure and losses.
Risk Manager
------------
.. automodule:: src.risk.manager
:members:
:undoc-members:
:show-inheritance:
Stop Loss
---------
.. automodule:: src.risk.stop_loss
:members:
:undoc-members:
:show-inheritance:
Position Sizing
---------------
.. automodule:: src.risk.position_sizing
:members:
:undoc-members:
:show-inheritance:
Risk Limits
-----------
.. automodule:: src.risk.limits
:members:
:undoc-members:
:show-inheritance:

29
docs/api/source/security.rst Normal file
View File

@@ -0,0 +1,29 @@
Security
========
Security features for API key management and encryption.
Encryption
----------
.. automodule:: src.security.encryption
:members:
:undoc-members:
:show-inheritance:
Key Manager
-----------
.. automodule:: src.security.key_manager
:members:
:undoc-members:
:show-inheritance:
Audit Logging
-------------
.. automodule:: src.security.audit
:members:
:undoc-members:
:show-inheritance:

120
docs/api/source/strategies.rst Normal file
View File

@@ -0,0 +1,120 @@
Strategy Framework
==================
The strategy framework enables creation and management of trading strategies.
Base Strategy
-------------
.. automodule:: src.strategies.base
:members:
:undoc-members:
:show-inheritance:
Strategy Registry
-----------------
.. automodule:: src.strategies.base
:members: StrategyRegistry
:undoc-members:
:show-inheritance:
Technical Strategies
--------------------
RSI Strategy
~~~~~~~~~~~
.. automodule:: src.strategies.technical.rsi_strategy
:members:
:undoc-members:
:show-inheritance:
MACD Strategy
~~~~~~~~~~~~~
.. automodule:: src.strategies.technical.macd_strategy
:members:
:undoc-members:
:show-inheritance:
Moving Average Strategy
~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.technical.moving_avg_strategy
:members:
:undoc-members:
:show-inheritance:
DCA Strategy
~~~~~~~~~~~~
.. automodule:: src.strategies.dca.dca_strategy
:members:
:undoc-members:
:show-inheritance:
Grid Strategy
~~~~~~~~~~~~~
.. automodule:: src.strategies.grid.grid_strategy
:members:
:undoc-members:
:show-inheritance:
Momentum Strategy
~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.momentum.momentum_strategy
:members:
:undoc-members:
:show-inheritance:
Confirmed Strategy
~~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.technical.confirmed_strategy
:members:
:undoc-members:
:show-inheritance:
Divergence Strategy
~~~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.technical.divergence_strategy
:members:
:undoc-members:
:show-inheritance:
Bollinger Mean Reversion Strategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.technical.bollinger_mean_reversion
:members:
:undoc-members:
:show-inheritance:
Consensus Strategy (Ensemble)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: src.strategies.ensemble.consensus_strategy
:members:
:undoc-members:
:show-inheritance:
Timeframe Manager
-----------------
.. automodule:: src.strategies.timeframe_manager
:members:
:undoc-members:
:show-inheritance:
Strategy Scheduler
----------------
.. automodule:: src.strategies.scheduler
:members:
:undoc-members:
:show-inheritance:

45
docs/api/source/trading.rst Normal file
View File

@@ -0,0 +1,45 @@
Trading Engine
==============
The trading engine handles order execution, position management, and exchange interactions.
Trading Engine
--------------
.. automodule:: src.trading.engine
:members:
:undoc-members:
:show-inheritance:
Order Manager
-------------
.. automodule:: src.trading.order_manager
:members:
:undoc-members:
:show-inheritance:
Paper Trading
-------------
.. automodule:: src.trading.paper_trading
:members:
:undoc-members:
:show-inheritance:
Advanced Orders
---------------
.. automodule:: src.trading.advanced_orders
:members:
:undoc-members:
:show-inheritance:
Futures Trading
---------------
.. automodule:: src.trading.futures
:members:
:undoc-members:
:show-inheritance:

378
docs/architecture/autopilot.md Normal file
View File

@@ -0,0 +1,378 @@
# Autopilot Architecture
This document describes the architecture of the Autopilot system, including both Pattern-Based and ML-Based modes.
## Overview
The Autopilot system provides autonomous trading signal generation using an **Intelligent Autopilot** powered by machine learning-based strategy selection.
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ Unified Autopilot API │
│ (/api/autopilot/start-unified) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ ML-Based │ │ Signal Display │
│ Autopilot │ │ (Dashboard) │
├───────────────────┤ └───────────────────┘
│ MarketAnalyzer │
│ StrategySelector │
│ PerformanceTracker│
└───────────────────┘
│
▼
┌───────────────────────┐
│ Signal Generation │
│ (StrategySignal) │
└───────────────────────┘
│
▼
┌───────────────────┐
│ Auto-Execution │
│ (Optional) │
└───────────────────┘
```
## ML-Based Autopilot Flow
> [!NOTE]
> **Global Model Architecture**: The system uses a single "Global Model" trained on data from *all* configured symbols. This allows for shared learning (patterns from BTC help predict ETH) and efficient resource usage.
> [!IMPORTANT]
> **Single-Asset Focus**: The current ML model is designed for **single-asset strategies** (e.g., Momentum, RSI, Grid). It analyzes each coin in isolation. It does **NOT** currently support multi-asset strategies like **Arbitrage**, which require analyzing correlations between multiple coins simultaneously.
```
Market Data (OHLCV)
│
▼
┌───────────────────┐
│ MarketAnalyzer │
│ - Analyze │
│ conditions │
│ - Determine │
│ regime │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ StrategySelector │
│ - Global ML Model │
│ - Select best │
│ strategy │
│ - Calculate │
│ confidence │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Selected Strategy │
│ - Generate signal│
│ - Calculate size │
└─────────┬─────────┘
│
▼
StrategySignal
```
## API Endpoints
### Unified Endpoints
- `POST /api/autopilot/start-unified` - Start autopilot
- `POST /api/autopilot/stop-unified` - Stop autopilot
- `GET /api/autopilot/status-unified/{symbol}` - Get autopilot status
### Legacy Endpoints (Removed)
- `POST /api/autopilot/start` - (Removed)
- `POST /api/autopilot/intelligent/start` - (Removed)
## Mode Selection Logic
The unified endpoints now exclusively support the "intelligent" mode. Code handling other modes has been removed.
```python
def start_unified_autopilot(config: UnifiedAutopilotConfig):
# Always starts intelligent autopilot
autopilot = get_intelligent_autopilot(
symbol=config.symbol,
exchange_id=config.exchange_id,
timeframe=config.timeframe,
interval=config.interval,
paper_trading=config.paper_trading
)
if config.auto_execute:
autopilot.enable_auto_execution = True
autopilot.start()
```
## Auto-Execution Integration
Auto-execution is integrated directly into the ML-based workflow:
```python
# Auto-Execution
if auto_execute and signal and confidence > threshold:
trading_engine.execute_order(
symbol=signal.symbol,
side=signal.signal_type,
quantity=strategy.calculate_position_size(signal, balance),
...
)
```
## Pre-Flight Order Validation
Before submitting orders, the autopilot validates that the order will succeed:
```python
async def _can_execute_order(side, quantity, price) -> Tuple[bool, str]:
# 1. Check minimum order value ($1 USD)
if order_value < 1.0:
return False, "Order value below minimum"
# 2. For BUY: check sufficient balance (with fee buffer)
if side == BUY:
if balance < (order_value + fee_estimate):
return False, "Insufficient funds"
# 3. For SELL: check position exists
if side == SELL:
if no_position:
return False, "No position to sell"
return True, "OK"
```
**Benefits:**
- Prevents creation of PENDING orders that would be REJECTED
- Cleaner order history (no garbage orders)
- Faster execution (skip validation at execution layer)
## Smart Order Type Selection
The autopilot intelligently chooses between LIMIT and MARKET orders:
| Scenario | Order Type | Rationale |
|----------|-----------|-----------|
| Strong signal (>80%) | MARKET | High confidence, execute now |
| Normal BUY signal | LIMIT (-0.1%) | Get better entry, pay maker fees |
| Take-profit SELL | LIMIT (+0.1%) | Get better exit price |
| Stop-loss SELL | MARKET | Urgent exit, protect capital |
```python
def _determine_order_type_and_price(side, signal_strength, price, is_stop_loss):
# Strong signals or stop-losses use MARKET
if signal_strength > 0.8 or is_stop_loss:
return MARKET, None
# Normal signals use LIMIT with 0.1% better price
if side == BUY:
limit_price = price * 0.999 # 0.1% below market
else:
limit_price = price * 1.001 # 0.1% above market
return LIMIT, limit_price
```
**Stop-Loss vs Take-Profit Detection:**
- If `current_price < entry_price`: Stop-loss (use MARKET)
- If `current_price > entry_price`: Take-profit (use LIMIT)
## Data Flow
1. **Market Data Collection**: OHLCV data from database
2. **Market Analysis**: MarketAnalyzer determines conditions
3. **Strategy Selection**: ML model selects best strategy
4. **Signal Generation**: Selected strategy generates signal
5. **Opportunity Evaluation**: Check confidence and criteria
6. **Execution** (if enabled): Execute trade
7. **Learning**: Record trade for model improvement
## Component Responsibilities
- **MarketAnalyzer**: Analyzes market conditions and determines regime
- **StrategySelector**: ML model for selecting optimal strategy
- **PerformanceTracker**: Tracks strategy performance for learning
- **IntelligentAutopilot**: Orchestrates ML-based selection and execution
## Configuration
```python
{
"symbol": "BTC/USD",
"exchange_id": 1,
"timeframe": "1h",
"interval": 60.0, # Analysis cycle in seconds
"paper_trading": True,
"min_confidence_threshold": 0.75,
"max_trades_per_day": 10,
"auto_execute": False
}
```
## State Management
- `_running`: Boolean flag
- `_last_analysis`: Last analysis result
- `_selected_strategy`: Currently selected strategy
- `_trades_today`: Trade count for daily limit
- `_ohlcv_data`: Current market data
- `_strategy_instances`: Cached strategy instances
- `_intelligent_autopilots`: Global registry of active instances
## Error Handling
Both modes implement error handling:
- **Market Data Errors**: Fallback to cached data or skip cycle
- **Pattern Detection Errors**: Return no pattern, continue monitoring
- **Sentiment Analysis Errors**: Use neutral sentiment, continue
- **ML Model Errors**: Fallback to rule-based selection
- **Execution Errors**: Log error, continue monitoring
## Performance Considerations
- **Moderate**: ML model adds overhead but is optimized for speed
- **Adaptive**: Performance improves with more training data
- **Scalable**: Model can handle multiple symbols with shared learning
## ML Model Training
The ML model training system supports background training via Celery with configurable parameters.
### Training Configuration
Training is configured via the Bootstrap Config API and persisted in the application config:
| Parameter | Description | Default |
|-----------|-------------|---------|
| `days` | Historical data (days) to fetch | 90 |
| `timeframe` | OHLCV candle timeframe | `1h` |
| `min_samples_per_strategy` | Minimum samples needed per strategy | 10 |
| `symbols` | Cryptocurrencies to train on | `["BTC/USD", "ETH/USD"]` |
### API Endpoints
```
GET /api/autopilot/bootstrap-config # Get current config
PUT /api/autopilot/bootstrap-config # Update config
POST /api/autopilot/intelligent/retrain # Trigger retraining
GET /api/autopilot/tasks/{task_id} # Poll training status
GET /api/autopilot/intelligent/model-info # Get model info
POST /api/autopilot/intelligent/reset # Reset model
```
### Background Training Architecture
```
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Settings Page │────▶│ FastAPI │────▶│ Celery Worker │
│ (React) │ │ Backend │ │ (train_task) │
└─────────────────┘ └──────────────┘ └─────────────────┘
│ │ │
│ Poll status │ get_config() │ Reset singletons
│◀─────────────────────│ │ Bootstrap data
│ │ │ Train model
│ │ │ Save to disk
│ │◀─────────────────────│
│ SUCCESS + metrics │ │
│◀─────────────────────│ │
│ │ │
▼ ▼ ▼
UI shows results Model auto-loads Model file saved
```
### Training Task Flow
1. **Singleton Reset**: Reset `StrategySelector`, `PerformanceTracker`, and `Database` singletons to prevent async conflicts
2. **Check Existing Data**: Query performance tracker for existing training samples
3. **Bootstrap (if needed)**: Fetch OHLCV data for each symbol with progress updates
4. **Train Model**: Train ML model with cross-validation and walk-forward validation
5. **Save Model**: Persist trained model to `~/.local/share/crypto_trader/models/`
6. **Return Metrics**: Return training accuracy and model metadata
### Model Auto-Reload
The `StrategySelector.get_model_info()` method automatically checks for new model files:
```python
def get_model_info(self):
# Always check if a newer model is available on disk
self._try_load_saved_model() # Compare timestamps, reload if newer
return {...}
```
This ensures the API process picks up newly trained models without restart.
### Error Handling
- **Celery Task Errors**: Serialized to JSON with traceback for frontend display
- **Polling Errors**: Frontend stops polling after 3 consecutive failures
- **Connection Errors**: Singletons reset to prevent `asyncpg.InterfaceError`
## Strategy Grouping
To improve ML accuracy, individual strategies are grouped into 5 logical categories. The model predicts the best **group**, then rule-based logic selects the optimal strategy within that group.
### Strategy Groups
| Group | Strategies | Market Conditions |
|-------|-----------|-------------------|
| **Trend Following** | moving_average, macd, confirmed | Strong trends (ADX > 25) |
| **Mean Reversion** | rsi, bollinger_mean_reversion, grid, divergence | Ranging markets, oversold/overbought |
| **Momentum** | momentum, volatility_breakout | High volume spikes, breakouts |
| **Market Making** | market_making, dca | Low volatility, stable markets |
| **Sentiment Based** | sentiment, pairs_trading, consensus | External signals available |
### Benefits
- **Reduced Classes**: 5 groups vs 14 strategies (~20% random baseline vs ~7%)
- **Better Generalization**: Model learns group characteristics rather than memorizing individual strategies
- **Combined Confidence**: `group_confidence × strategy_confidence` for final score
## Improved Bootstrap Sampling
Training data is collected using intelligent sampling rather than fixed intervals:
### Sampling Strategies
1. **Regime-Change Detection**: Sample when market regime changes (e.g., trending → ranging)
2. **Minimum Time Spacing**: 24-hour gaps between samples for 1h timeframe
3. **Periodic Sampling**: Every 48 hours regardless of regime changes
### Timeframe Spacing
| Timeframe | Min Spacing (candles) | Actual Time |
|-----------|----------------------|-------------|
| 1m | 1440 | 24 hours |
| 15m | 96 | 24 hours |
| 1h | 24 | 24 hours |
| 4h | 6 | 24 hours |
| 1d | 1 | 24 hours |
## Security Considerations
- **Auto-Execution**: Requires explicit user confirmation
- **Paper Trading**: Default mode for safety
- **Risk Limits**: Enforced regardless of mode
- **API Keys**: Encrypted storage
- **Audit Logging**: All autopilot actions logged
## Future Enhancements
- Hybrid mode combining both approaches
- Real-time mode switching
- Multi-symbol autopilot management
- Advanced risk management integration
- Performance analytics dashboard
- Persistent training configuration (file/database storage)

135
docs/architecture/backtesting.md Normal file
View File

@@ -0,0 +1,135 @@
# Backtesting Engine Architecture
This document describes the backtesting engine design.
## Backtesting Components
```
Backtesting Engine
├──► Data Provider
│ │
│ └──► Historical Data Loading
│
├──► Strategy Execution
│ │
│ ├──► Data Replay
│ ├──► Signal Generation
│ └──► Order Simulation
│
├──► Realism Models
│ │
│ ├──► Slippage Model
│ ├──► Fee Model
│ └──► Order Book Simulation
│
└──► Metrics Calculation
│
├──► Performance Metrics
└──► Risk Metrics
```
## Data Replay
Historical data is replayed chronologically:
```
Historical Data (Time Series)
│
▼
Time-based Iteration
│
├──► For each timestamp:
│ │
│ ├──► Update market data
│ ├──► Notify strategies
│ ├──► Process signals
│ └──► Execute orders
│
└──► Continue until end date
```
## Order Simulation
Simulated order execution:
```
Order Request
│
▼
Order Type Check
│
├──► Market Order
│ │
│ └──► Execute at current price + slippage
│
└──► Limit Order
│
└──► Wait for price to reach limit
│
└──► Execute when filled
```
## Slippage Modeling
Realistic slippage simulation:
```
Market Order
│
▼
Current Price
│
├──► Buy Order: Price + Slippage
└──► Sell Order: Price - Slippage
│
└──► Add Market Impact (for large orders)
```
## Fee Modeling
Exchange fee calculation:
```
Order Execution
│
▼
Order Type Check
│
├──► Maker Order (Limit)
│ │
│ └──► Apply Maker Fee
│
└──► Taker Order (Market)
│
└──► Apply Taker Fee
```
## Performance Metrics
Calculated metrics:
- **Total Return**: (Final Capital - Initial Capital) / Initial Capital
- **Sharpe Ratio**: (Return - Risk-free Rate) / Volatility
- **Sortino Ratio**: (Return - Risk-free Rate) / Downside Deviation
- **Max Drawdown**: Largest peak-to-trough decline
- **Win Rate**: Winning Trades / Total Trades
- **Profit Factor**: Gross Profit / Gross Loss
## Parameter Optimization
Optimization methods:
- **Grid Search**: Test all parameter combinations
- **Genetic Algorithm**: Evolutionary optimization
- **Bayesian Optimization**: Efficient parameter search
## Backtest Results
Stored results:
- Performance metrics
- Trade history
- Equity curve
- Drawdown chart
- Parameter values

233
docs/architecture/data_flow.md Normal file
View File

@@ -0,0 +1,233 @@
# Data Flow Architecture
This document describes how data flows through the Crypto Trader system.
## Real-Time Data Flow
```
Exchange WebSocket
│
▼
Exchange Adapter
│
▼
Data Collector
│
├──► Data Quality Validation
│
├──► Data Storage (Database)
│
└──► Timeframe Manager
│
├──► Strategy 1 (1h timeframe)
├──► Strategy 2 (15m timeframe)
└──► Strategy 3 (1d timeframe)
│
▼
Signal Generation
│
▼
Trading Engine
```
## Trading Signal Flow
```
Market Data Update
│
▼
Strategy.on_data()
│
▼
Indicator Calculation
│
▼
Signal Generation
│
▼
Trading Engine
│
├──► Risk Manager (Pre-trade Check)
│ │
│ ├──► Position Sizing
│ ├──► Drawdown Check
│ └──► Daily Loss Check
│
▼
Order Manager
│
├──► Paper Trading (if enabled)
│ │
│ └──► Paper Trading Simulator
│
└──► Live Trading
│
▼
Exchange Adapter
│
▼
Exchange API
│
▼
Order Execution
│
▼
Order Manager (Update Status)
│
▼
Position Tracker
│
▼
Portfolio Analytics
```
## Backtesting Data Flow
```
Historical Data Provider
│
▼
Backtesting Engine
│
├──► Data Replay (Time-based)
│
├──► Strategy Execution
│ │
│ ├──► Signal Generation
│ │
│ └──► Order Simulation
│ │
│ ├──► Slippage Model
│ ├──► Fee Model
│ └──► Order Book Simulation
│
└──► Performance Calculation
│
├──► Metrics Calculation
│ │
│ ├──► Returns
│ ├──► Sharpe Ratio
│ ├──► Sortino Ratio
│ └──► Drawdown
│
└──► Results Storage
```
## Portfolio Update Flow
```
Trade Execution
│
▼
Position Update
│
├──► Position Tracker
│ │
│ ├──► Update Quantity
│ ├──► Update Entry Price
│ └──► Calculate P&L
│
└──► Portfolio Analytics
│
├──► Recalculate Metrics
│ │
│ ├──► Total Value
│ ├──► Unrealized P&L
│ ├──► Realized P&L
│ └──► Performance Metrics
│
└──► Alert System
│
└──► Risk Alerts (if triggered)
```
## Data Storage Flow
```
Data Collection
│
▼
Data Quality Check
│
├──► Valid Data
│ │
│ └──► Database Storage
│ │
│ ├──► Market Data Table
│ ├──► Trades Table
│ └──► Positions Table
│
└──► Invalid Data
│
└──► Error Logging
│
└──► Gap Detection
│
└──► Gap Filling (if enabled)
```
## Multi-Timeframe Synchronization
```
1m Data Stream
│
├──► Strategy (1m)
│
└──► Resample to 5m
│
├──► Strategy (5m)
│
└──► Resample to 1h
│
├──► Strategy (1h)
│
└──► Resample to 1d
│
└──► Strategy (1d)
```
## Alert Flow
```
Data Update / Event
│
▼
Alert Engine
│
├──► Check Alert Conditions
│ │
│ ├──► Price Alerts
│ ├──► Indicator Alerts
│ ├──► Risk Alerts
│ └──► System Alerts
│
└──► Trigger Alert (if condition met)
│
├──► Desktop Notification
├──► Sound Alert
└──► Email Notification (if configured)
```
## Error Recovery Flow
```
Error Detected
│
▼
Error Recovery System
│
├──► Log Error
│
├──► Attempt Recovery
│ │
│ ├──► Retry Operation
│ ├──► Fallback Mechanism
│ └──► State Restoration
│
└──► Health Monitor
│
├──► Check System Health
│
└──► Auto-restart (if critical)
```

288
docs/architecture/database_schema.md Normal file
View File

@@ -0,0 +1,288 @@
# Database Schema
This document describes the database schema for Crypto Trader.
## Database Options
- **SQLite**: Default, bundled, zero configuration
- **PostgreSQL**: Optional, for advanced users with large datasets
## Core Tables
### Exchanges
Stores exchange configuration and credentials.
```sql
CREATE TABLE exchanges (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE NOT NULL,
api_key TEXT, -- Encrypted
secret_key TEXT, -- Encrypted
password TEXT, -- Encrypted (for some exchanges)
api_permissions TEXT DEFAULT 'read_only',
is_enabled BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Strategies
Stores trading strategy configuration.
```sql
CREATE TABLE strategies (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE NOT NULL,
description TEXT,
strategy_type TEXT NOT NULL,
parameters TEXT, -- JSON
is_enabled BOOLEAN DEFAULT FALSE,
is_paper_trading BOOLEAN DEFAULT TRUE,
exchange_id INTEGER REFERENCES exchanges(id),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Trades
Stores executed trades.
```sql
CREATE TABLE trades (
id INTEGER PRIMARY KEY,
order_id TEXT UNIQUE NOT NULL,
symbol TEXT NOT NULL,
side TEXT NOT NULL, -- 'buy' or 'sell'
type TEXT NOT NULL, -- 'market', 'limit', etc.
price REAL,
amount REAL,
cost REAL,
fee REAL DEFAULT 0.0,
status TEXT DEFAULT 'open',
is_paper_trade BOOLEAN DEFAULT TRUE,
executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
strategy_id INTEGER REFERENCES strategies(id)
);
```
### Positions
Stores open and closed positions.
```sql
CREATE TABLE positions (
id INTEGER PRIMARY KEY,
symbol TEXT NOT NULL,
exchange_id INTEGER REFERENCES exchanges(id),
quantity REAL NOT NULL,
entry_price REAL NOT NULL,
current_price REAL,
unrealized_pnl REAL,
realized_pnl REAL,
is_open BOOLEAN DEFAULT TRUE,
position_type TEXT DEFAULT 'spot', -- 'spot', 'futures', 'margin'
leverage REAL DEFAULT 1.0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP,
UNIQUE(symbol, exchange_id, position_type)
);
```
### Orders
Stores order history and status.
```sql
CREATE TABLE orders (
id INTEGER PRIMARY KEY,
exchange_order_id TEXT UNIQUE NOT NULL,
client_order_id TEXT,
symbol TEXT NOT NULL,
side TEXT NOT NULL,
type TEXT NOT NULL,
price REAL,
amount REAL,
filled_amount REAL DEFAULT 0.0,
remaining_amount REAL DEFAULT 0.0,
cost REAL DEFAULT 0.0,
status TEXT DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
strategy_id INTEGER REFERENCES strategies(id),
is_paper_trade BOOLEAN DEFAULT TRUE
);
```
### Market Data
Stores historical OHLCV data.
```sql
CREATE TABLE market_data (
id INTEGER PRIMARY KEY,
symbol TEXT NOT NULL,
timeframe TEXT NOT NULL,
timestamp TIMESTAMP NOT NULL,
open REAL NOT NULL,
high REAL NOT NULL,
low REAL NOT NULL,
close REAL NOT NULL,
volume REAL NOT NULL,
exchange_id INTEGER REFERENCES exchanges(id),
UNIQUE(symbol, timeframe, timestamp)
);
```
### Portfolio Snapshots
Stores portfolio snapshots over time.
```sql
CREATE TABLE portfolio_snapshots (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
total_value REAL NOT NULL,
cash_balance REAL NOT NULL,
asset_holdings TEXT, -- JSON
exchange_id INTEGER REFERENCES exchanges(id)
);
```
### Backtest Results
Stores backtesting results.
```sql
CREATE TABLE backtest_results (
id INTEGER PRIMARY KEY,
strategy_id INTEGER REFERENCES strategies(id),
start_date TIMESTAMP NOT NULL,
end_date TIMESTAMP NOT NULL,
initial_capital REAL NOT NULL,
final_capital REAL NOT NULL,
total_return REAL NOT NULL,
sharpe_ratio REAL,
sortino_ratio REAL,
max_drawdown REAL,
win_rate REAL,
other_metrics TEXT, -- JSON
run_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Risk Limits
Stores risk management limits.
```sql
CREATE TABLE risk_limits (
id INTEGER PRIMARY KEY,
strategy_id INTEGER REFERENCES strategies(id),
exchange_id INTEGER REFERENCES exchanges(id),
limit_type TEXT NOT NULL,
value REAL NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP
);
```
### Alerts
Stores alert configurations.
```sql
CREATE TABLE alerts (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
alert_type TEXT NOT NULL,
condition TEXT NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
triggered_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Rebalancing Events
Stores portfolio rebalancing history.
```sql
CREATE TABLE rebalancing_events (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
exchange_id INTEGER REFERENCES exchanges(id),
old_allocations TEXT, -- JSON
new_allocations TEXT, -- JSON
executed_trades TEXT, -- JSON
status TEXT DEFAULT 'completed'
);
```
### App State
Stores application state for recovery.
```sql
CREATE TABLE app_state (
id INTEGER PRIMARY KEY,
key TEXT UNIQUE NOT NULL,
value TEXT, -- JSON
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### Audit Log
Stores security audit events.
```sql
CREATE TABLE audit_log (
id INTEGER PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
event_type TEXT NOT NULL,
user_id TEXT,
details TEXT -- JSON
);
```
## Indexes
Key indexes for performance:
- `market_data(symbol, timeframe, timestamp)` - Unique index
- `trades(symbol, executed_at)` - For trade queries
- `positions(symbol, exchange_id, is_open)` - For position lookups
- `orders(status, created_at)` - For order management
- `strategies(is_enabled)` - For active strategy queries
## Relationships
- **Exchanges** → **Strategies** (one-to-many)
- **Exchanges** → **Trades** (one-to-many)
- **Strategies** → **Trades** (one-to-many)
- **Strategies** → **Backtest Results** (one-to-many)
- **Exchanges** → **Positions** (one-to-many)
- **Exchanges** → **Market Data** (one-to-many)
## Data Retention
Configurable retention policies:
- **Market Data**: Configurable (default: 1 year)
- **Trades**: Permanent
- **Orders**: Permanent
- **Portfolio Snapshots**: Configurable (default: 1 year)
- **Logs**: Configurable (default: 30 days)
## Backup and Recovery
- **Automatic Backups**: Before critical operations
- **Manual Backups**: Via export functionality
- **Recovery**: From backup files or database dumps

176
docs/architecture/exchange_integration.md Normal file
View File

@@ -0,0 +1,176 @@
# Exchange Integration Architecture
This document describes how exchange adapters integrate with the trading system.
## Adapter Pattern
All exchanges use the adapter pattern to provide a unified interface:
```
Trading Engine
│
▼
BaseExchange (Interface)
│
├──► CoinbaseExchange
├──► BinanceExchange (future)
└──► KrakenExchange (future)
```
## Base Exchange Interface
All exchanges implement `BaseExchange`:
```python
class BaseExchange(ABC):
async def connect()
async def disconnect()
async def fetch_balance()
async def place_order()
async def cancel_order()
async def fetch_order_status()
async def fetch_ohlcv()
async def subscribe_ohlcv()
async def subscribe_trades()
async def subscribe_order_book()
async def fetch_open_orders()
async def fetch_positions()
async def fetch_markets()
```
## Exchange Factory
The factory pattern creates exchange instances:
```
ExchangeFactory
│
├──► get_exchange(name)
│ │
│ ├──► Lookup registered adapter
│ ├──► Get API keys from KeyManager
│ └──► Instantiate adapter
│
└──► register_exchange(name, adapter_class)
```
## Exchange Registration
Exchanges are registered at module import:
```python
# In exchange module
from src.exchanges.factory import ExchangeFactory
ExchangeFactory.register_exchange("coinbase", CoinbaseExchange)
```
## CCXT Integration
Most exchanges use the CCXT library:
```python
import ccxt.pro as ccxt
class CoinbaseExchange(BaseExchange):
def __init__(self, ...):
self.exchange = ccxt.coinbaseadvanced({
'apiKey': api_key,
'secret': secret_key,
'enableRateLimit': True,
})
```
## WebSocket Support
Real-time data via WebSockets:
```python
async def subscribe_ohlcv(self, symbol, timeframe, callback):
"""Subscribe to OHLCV updates."""
await self.exchange.watch_ohlcv(symbol, timeframe, callback)
```
## Rate Limiting
All exchanges respect rate limits:
- CCXT handles rate limiting automatically
- `enableRateLimit: True` in exchange config
- Custom rate limiting for non-CCXT exchanges
## Error Handling
Exchange-specific error handling:
```python
try:
order = await self.exchange.create_order(...)
except ccxt.NetworkError as e:
# Handle network errors
logger.error(f"Network error: {e}")
raise
except ccxt.ExchangeError as e:
# Handle exchange errors
logger.error(f"Exchange error: {e}")
raise
```
## Connection Management
- **Connection Pooling**: Reuse connections when possible
- **Auto-Reconnect**: Automatic reconnection on disconnect
- **Health Monitoring**: Monitor connection health
- **Graceful Shutdown**: Properly close connections
## Adding New Exchanges
See [Adding Exchanges](../developer/adding_exchanges.md) for detailed guide.
## Exchange-Specific Features
Some exchanges have unique features:
- **Coinbase**: Requires passphrase for some operations
- **Binance**: Futures and margin trading
- **Kraken**: Different order types
These are handled in exchange-specific adapters.
## WebSocket Implementation
### Coinbase WebSocket Support
The Coinbase adapter includes WebSocket subscription methods:
- **subscribe_ticker()**: Subscribe to real-time price updates
- **subscribe_orderbook()**: Subscribe to order book changes
- **subscribe_trades()**: Subscribe to trade executions
### WebSocket Architecture
```
Exchange WebSocket API
↓
CoinbaseAdapter.subscribe_*()
↓
Callback Functions
↓
DataCollector (with signals)
↓
UI Widgets (via signals)
```
### Reconnection Strategy
- Automatic reconnection on disconnect
- Message queuing during disconnection
- Heartbeat/ping-pong for connection health
- Fallback to polling if WebSocket unavailable
### Implementation Notes
- Uses `websockets` library for async WebSocket connections
- Callbacks are wrapped to emit Qt signals for UI updates
- Basic implementation provided; can be extended for full Coinbase Advanced Trade WebSocket API

185
docs/architecture/overview.md Normal file
View File

@@ -0,0 +1,185 @@
# Architecture Overview
This document provides a high-level overview of the Crypto Trader architecture.
## System Architecture
Crypto Trader follows a modular architecture with clear separation of concerns:
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (React + Vite) │
│ Dashboard | Strategies | Portfolio | Backtest | Settings│
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Backend API (FastAPI) │
│ Autopilot | Trading | Market Data | WebSocket │
└─────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Redis │ │ Celery │ │ PostgreSQL │
│ State/Cache │←───│ Workers │ │ Database │
└──────────────┘ └──────────────┘ └──────────────────┘
▲ │
│ ▼
┌─────────────────────────────────────────────────────────┐
│ Trading Engine │
│ Order Management | Position Tracking | Risk Management │
└─────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Strategies │ │ Exchanges │ │ Portfolio │
│ Framework │ │ Adapters │ │ Tracker │
└──────────────┘ └──────────────┘ └──────────────┘
```
## Core Components
### 1. Frontend Layer
- **Framework**: React with TypeScript
- **Build Tool**: Vite
- **Components**: Dashboard, Strategy Manager, Portfolio View, Backtest View, Settings
- **State Management**: React Query, Context API
- **Styling**: Material-UI (MUI)
### 2. Backend API
- **Framework**: FastAPI (async Python)
- **Features**: RESTful API, WebSocket support, auto-docs (Swagger/OpenAPI)
- **Authentication**: JWT tokens (planned)
- **Responsibilities**: Orchestrates all business logic
### 3. Redis (State Management)
- **Purpose**: Distributed state management and caching
- **Use Cases**:
- Autopilot registry (prevents multiple instances)
- Daily trade count persistence (survives restarts)
- Session caching (planned)
- Real-time data caching (planned)
- **Configuration**: `src/core/config.py` → `redis` section
### 4. Celery (Background Tasks)
- **Purpose**: Offload CPU-intensive tasks from the API
- **Use Cases**:
- ML model training (`train_model_task`)
- Data bootstrapping (`bootstrap_task`)
- Report generation (`generate_report_task`)
- **Broker**: Redis
- **Worker Command**: `celery -A src.worker.app worker --loglevel=info`
### 5. Trading Engine
- **Responsibilities**: Order execution, position management, risk checks
- **Components**: Trading engine, order manager, paper trading simulator
- **Integration**: Connects strategies to exchanges
### 6. Strategy Framework
- **Base Class**: `BaseStrategy` provides common interface
- **Registry**: Manages available strategies (RSI, MACD, Bollinger, etc.)
- **ML Selection**: `IntelligentAutopilot` uses ML to select optimal strategies
- **Features**: Multi-timeframe support, scheduling, parameter management
### 7. Exchange Adapters
- **Pattern**: Adapter pattern for unified interface
- **Factory**: Dynamic exchange instantiation
- **Current**: Coinbase Advanced Trade API, Binance Public
- **Data Providers**: CCXT-based providers with automatic failover
### 8. Risk Management
- **Components**: Risk manager, stop-loss, position sizing, limits
- **Integration**: Pre-trade checks, real-time monitoring
- **Features**: Drawdown limits, daily loss limits, position limits
### 9. Backtesting Engine
- **Features**: Historical data replay, realistic simulation
- **Components**: Engine, metrics, slippage model, fee model
- **Optimization**: Parameter optimization support
### 10. Portfolio Management
- **Tracking**: Real-time position tracking
- **Analytics**: Performance metrics, risk analysis
- **Rebalancing**: Automatic portfolio rebalancing (planned)
## Data Flow
### Trading Flow
1. User starts autopilot → API receives request
2. Redis lock checked/set → Prevents duplicate instances
3. Strategy generates signal
4. Risk manager validates trade
5. Order manager creates order
6. Exchange adapter executes order
7. Position tracker updates positions
8. Redis updates trade count
### ML Training Flow (Background)
1. User triggers `/retrain` API
2. API queues `train_model_task` to Celery
3. API returns task ID immediately (non-blocking)
4. Celery worker picks up task
5. Worker bootstraps data if needed
6. Worker trains model
7. User polls `/tasks/{task_id}` for status
## Technology Stack
- **Language**: Python 3.11+
- **Frontend**: React 18, TypeScript, Vite
- **Backend**: FastAPI, Uvicorn
- **Database**: PostgreSQL with SQLAlchemy
- **Cache/State**: Redis
- **Task Queue**: Celery
- **Exchange Library**: CCXT
- **Data Analysis**: Pandas, NumPy
- **Machine Learning**: LightGBM, scikit-learn
- **Technical Analysis**: pandas-ta, TA-Lib
- **Async**: asyncio
- **Testing**: pytest, React Testing Library
## Design Patterns
- **Adapter Pattern**: Exchange adapters
- **Factory Pattern**: Exchange and strategy creation
- **Strategy Pattern**: Trading strategies
- **Observer Pattern**: Data updates to strategies
- **Singleton Pattern**: Configuration, database connections, Redis client
## Security Architecture
- **API Key Encryption**: Fernet encryption
- **Secure Storage**: Keyring integration
- **Audit Logging**: All security events logged
- **Permission Management**: Read-only vs trading modes
## Scalability Considerations
- **Async Operations**: Non-blocking I/O throughout
- **Redis State**: Enables horizontal scaling of API workers
- **Celery Workers**: Can scale independently for heavy workloads
- **Database Optimization**: Indexed queries, connection pooling
- **Data Retention**: Configurable retention policies
## Extension Points
- **Exchange Adapters**: Add new exchanges via adapter interface
- **Strategies**: Create custom strategies via base class
- **Indicators**: Add custom indicators
- **Order Types**: Extend advanced order types
- **Risk Rules**: Add custom risk management rules
- **Celery Tasks**: Add new background tasks in `src/worker/tasks.py`

165
docs/architecture/risk_management.md Normal file
View File

@@ -0,0 +1,165 @@
# Risk Management Architecture
This document describes the risk management system.
## Risk Management Components
```
Risk Manager
├──► Pre-Trade Checks
│ │
│ ├──► Position Sizing
│ ├──► Daily Loss Limit
│ └──► Portfolio Allocation
│
├──► Real-Time Monitoring
│ │
│ ├──► Drawdown Monitoring
│ ├──► Position Monitoring
│ └──► Portfolio Monitoring
│
└──► Stop Loss Management
│
├──► Stop Loss Orders
└──► Trailing Stops
```
## Pre-Trade Risk Checks
Before executing any trade:
1. **Position Sizing Check**
- Verify position size within limits
- Check portfolio allocation
- Validate against risk parameters
2. **Daily Loss Limit Check**
- Calculate current daily P&L
- Compare against daily loss limit
- Block trades if limit exceeded
3. **Drawdown Check**
- Calculate current drawdown
- Compare against max drawdown limit
- Block trades if limit exceeded
4. **Portfolio Allocation Check**
- Verify total exposure within limits
- Check per-asset allocation
- Validate diversification requirements
## Position Sizing Methods
### Fixed Percentage
```python
position_size = capital * percentage
```
### Kelly Criterion
```python
f = (bp - q) / b
position_size = capital * f
```
### Volatility-Based
```python
position_size = (capital * risk_percentage) / (stop_loss_distance * price)
```
## Risk Limits
Configurable limits:
- **Max Drawdown**: Maximum allowed drawdown percentage
- **Daily Loss Limit**: Maximum daily loss percentage
- **Position Size Limit**: Maximum position value
- **Portfolio Exposure**: Maximum portfolio exposure percentage
## Stop Loss Management
### Stop Loss Types
- **Fixed Stop Loss**: Fixed price level
- **Trailing Stop**: Adjusts with price movement
- Percentage-based: Adjusts by fixed percentage
- ATR-based: Adjusts based on volatility (Average True Range)
- **Percentage Stop**: Percentage below entry
- **ATR-based Stop**: Based on Average True Range (volatility-adjusted)
- Automatically calculates stop distance using ATR multiplier
- Adapts to market volatility conditions
- Configurable ATR period (default: 14) and multiplier (default: 2.0)
- Works with both fixed and trailing stops
### ATR-Based Dynamic Stops
ATR-based stops provide better risk management in volatile markets:
```python
stop_loss_manager.set_stop_loss(
position_id=1,
stop_price=entry_price,
use_atr=True,
atr_multiplier=Decimal('2.0'),
atr_period=14,
ohlcv_data=market_data,
trailing=True
)
```
**Benefits:**
- Adapts to market volatility
- Tighter stops in low volatility, wider in high volatility
- Reduces stop-outs during normal market noise
- Better risk-adjusted returns
**Calculation:**
- Stop distance = ATR × multiplier
- For long positions: stop_price = entry_price - (ATR × multiplier)
- For short positions: stop_price = entry_price + (ATR × multiplier)
### Stop Loss Execution
```
Price Update
│
▼
Stop Loss Check
│
├──► Stop Loss Triggered?
│ │
│ └──► Execute Market Sell
│
└──► Update Trailing Stop (if applicable)
```
## Real-Time Monitoring
Continuous monitoring of:
- Portfolio value
- Unrealized P&L
- Drawdown levels
- Position sizes
- Risk metrics
## Risk Alerts
Automatic alerts for:
- Drawdown threshold exceeded
- Daily loss limit reached
- Position size exceeded
- Portfolio exposure exceeded
## Integration Points
Risk management integrates with:
- **Trading Engine**: Pre-trade validation
- **Order Manager**: Position tracking
- **Portfolio Tracker**: Real-time monitoring
- **Alert System**: Risk alerts

135
docs/architecture/security.md Normal file
View File

@@ -0,0 +1,135 @@
# Security Architecture
This document describes the security architecture of Crypto Trader.
## Security Layers
```
Application Layer
├──► API Key Encryption
├──► Permission Management
└──► Audit Logging
│
▼
Storage Layer
├──► Encrypted Storage
└──► Secure Key Management
```
## API Key Encryption
### Encryption Process
```
Plain API Key
│
▼
Fernet Encryption
│
▼
Encrypted Key (Stored in Database)
```
### Key Management
- **Encryption Key**: Stored securely (environment variable or keyring)
- **Key Generation**: Automatic on first use
- **Key Rotation**: Manual rotation process
## Permission Management
### Permission Levels
- **Read-Only**: Data collection, backtesting only
- **Trading Enabled**: Full trading capabilities
### Permission Enforcement
```
API Request
│
▼
Permission Check
│
├──► Read-Only Request
│ │
│ └──► Allow (read operations)
│
└──► Trading Request
│
├──► Trading Enabled?
│ │
│ ├──► Yes: Allow
│ └──► No: Reject
```
## Secure Storage
### Keyring Integration
- **Linux**: Secret Service (GNOME Keyring)
- **macOS**: Keychain
- **Windows**: Windows Credential Manager
### Fallback Storage
If keyring unavailable:
- Environment variable (development only)
- Encrypted file with user permission
## Audit Logging
All security events are logged:
- API key changes
- Permission changes
- Trading operations
- Configuration changes
- Error events
### Audit Log Format
```python
{
"timestamp": "2025-12-13T19:00:00Z",
"event_type": "API_KEY_CHANGED",
"user_id": "system",
"details": {
"exchange": "coinbase",
"action": "updated"
}
}
```
## Data Privacy
- **Local Storage**: All data stored locally
- **No Telemetry**: No data sent externally
- **Encryption**: Sensitive data encrypted at rest
- **Access Control**: File system permissions
## Best Practices
1. **Use Read-Only Keys**: When possible, use read-only API keys
2. **IP Whitelisting**: Enable IP whitelisting on exchange accounts
3. **Regular Rotation**: Rotate API keys periodically
4. **Secure Environment**: Keep encryption keys secure
5. **Audit Review**: Regularly review audit logs
## Threat Model
### Threats Addressed
- **API Key Theft**: Encryption at rest
- **Unauthorized Trading**: Permission checks
- **Data Breach**: Local storage, encryption
- **Man-in-the-Middle**: HTTPS for API calls
- **Key Logging**: Secure keyring storage
### Security Boundaries
- **Application Boundary**: Application code
- **Storage Boundary**: Encrypted database
- **Network Boundary**: Secure API connections
- **System Boundary**: File system permissions

208
docs/architecture/strategy_framework.md Normal file
View File

@@ -0,0 +1,208 @@
# Strategy Framework Architecture
This document describes the strategy framework design.
## Strategy Hierarchy
```
BaseStrategy (Abstract)
│
├──► Technical Strategies
│ ├──► RSIStrategy
│ ├──► MACDStrategy
│ ├──► MovingAverageStrategy
│ ├──► ConfirmedStrategy (Multi-Indicator)
│ ├──► DivergenceStrategy
│ └──► BollingerMeanReversionStrategy
│
├──► Ensemble Strategies
│ └──► ConsensusStrategy
│
├──► Other Strategies
│ ├──► DCAStrategy
│ ├──► GridStrategy
│ └──► MomentumStrategy
│
└──► CustomStrategy (user-defined)
```
## Base Strategy Interface
All strategies implement:
```python
class BaseStrategy(ABC):
async def on_data(new_data: pd.DataFrame)
async def generate_signal() -> Dict[str, Any]
async def calculate_position_size(capital, risk) -> float
async def start()
async def stop()
```
## Strategy Lifecycle
```
1. Initialization
└──► __init__(parameters)
2. Activation
└──► start()
3. Data Processing
└──► on_data(new_data)
└──► generate_signal()
└──► Trading Engine
4. Deactivation
└──► stop()
```
## Strategy Registry
Manages available strategies:
```python
StrategyRegistry
├──► register_strategy(name, class)
├──► get_strategy_class(name)
└──► list_available()
```
## Multi-Timeframe Support
Strategies can use multiple timeframes:
```
Primary Timeframe (1h)
│
├──► Signal Generation
│
└──► Higher Timeframe (1d) - Trend Confirmation
│
└──► Lower Timeframe (15m) - Entry Timing
```
## Strategy Scheduling
Strategies can be scheduled:
- **Continuous**: Run on every new candle
- **Time-based**: Run at specific times
- **Condition-based**: Run when conditions met
## Signal Generation
Signal flow:
```
Data Update
│
▼
Indicator Calculation
│
▼
Strategy Logic
│
▼
Signal Generation
│
├──► "buy" - Generate buy signal
├──► "sell" - Generate sell signal
└──► "hold" - No action
```
## Position Sizing
Strategies calculate position sizes:
- **Fixed Percentage**: Fixed % of capital
- **Kelly Criterion**: Optimal position sizing based on win rate
- **Volatility-Based**: Adjusts based on market volatility (ATR)
## Advanced Features
### Trend Filtering
All strategies can optionally use ADX-based trend filtering:
```python
signal = strategy.apply_trend_filter(
signal,
ohlcv_data,
adx_period=14,
min_adx=25.0
)
```
This filters out signals when:
- ADX < threshold (weak trend/chop)
- Signal direction doesn't match trend direction
### Multi-Indicator Confirmation
The ConfirmedStrategy requires multiple indicators to agree before generating signals, reducing false signals by 20-30%.
### Divergence Detection
Divergence strategies detect price vs. indicator divergences:
- Bullish divergence: Price lower low, indicator higher low → BUY
- Bearish divergence: Price higher high, indicator lower high → SELL
### Ensemble Methods
ConsensusStrategy aggregates signals from multiple strategies:
- Weighted voting by strategy performance
- Minimum consensus threshold
- Dynamic weighting based on recent performance
- **Kelly Criterion**: Optimal position sizing
- **Volatility-based**: Based on ATR
- **Risk-based**: Based on stop-loss distance
## Strategy Parameters
Configurable parameters:
- Strategy-specific parameters (e.g., RSI period)
- Risk parameters (position size, stop-loss)
- Timeframe settings
- Symbol selection
## Strategy Execution
Execution flow:
```
Strategy Signal
│
▼
Trading Engine
│
├──► Risk Check
│
├──► Position Sizing
│
└──► Order Execution
│
├──► Paper Trading
└──► Live Trading
```
## Strategy Performance
Performance tracking:
- Win rate
- Total return
- Sharpe ratio
- Max drawdown
- Number of trades
## Extensibility
Easy to add new strategies:
1. Inherit from `BaseStrategy`
2. Implement required methods
3. Register with `StrategyRegistry`
4. Configure and use

270
docs/architecture/ui_architecture.md Normal file
View File

@@ -0,0 +1,270 @@
# UI Architecture
This document describes the user interface architecture and how the frontend integrates with the backend API.
## Overview
The UI is built with React and TypeScript, using Material-UI for components. The frontend communicates with the FastAPI backend through REST API endpoints and WebSocket connections for real-time updates.
## Architecture
```
React Frontend → REST API / WebSocket → FastAPI Backend → Python Services → Database
```
## Frontend Structure
```
frontend/src/
├── pages/ # Page components (Trading, Portfolio, Strategies, etc.)
├── components/ # Reusable UI components
├── api/ # API client functions
├── hooks/ # Custom React hooks
└── types/ # TypeScript type definitions
```
## Page Components
### DashboardPage
- Overview of trading activity
- Key metrics and charts
- Quick actions
### TradingPage
- Order placement form
- Positions table
- Order history
- Real-time price updates
### PortfolioPage
- Portfolio summary
- Holdings table
- Risk metrics
- Performance charts
### StrategiesPage
- Strategy list and management
- Strategy configuration
- Start/stop controls
- Performance metrics
### BacktestPage
- Backtest configuration
- Results display
- Export functionality
### SettingsPage
- Exchange management
- Configuration settings
- API key management
## Real-Time Updates
### WebSocket Connection
The frontend connects to the backend WebSocket endpoint (`/ws/`) for real-time updates:
- Price updates
- Order status changes
- Position updates
- Strategy status changes
### Implementation
```typescript
// Using WebSocket hook
import { useWebSocket } from '@/hooks/useWebSocket';
function TradingPage() {
const { data, connected } = useWebSocket('/ws/');
// Handle real-time price updates
useEffect(() => {
if (data?.type === 'price_update') {
// Update UI with new price
}
}, [data]);
}
```
## API Integration
### API Client
All API calls go through the API client which handles:
- Request/response serialization
- Error handling
- Authentication (if added)
```typescript
// Example API call
import { tradingApi } from '@/api/trading';
const placeOrder = async () => {
const order = await tradingApi.placeOrder({
exchangeId: 1,
symbol: 'BTC/USD',
side: 'buy',
type: 'market',
quantity: 0.1,
paperTrading: true
});
};
```
### React Query
The frontend uses React Query for:
- Data fetching
- Caching
- Automatic refetching
- Optimistic updates
```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { portfolioApi } from '@/api/portfolio';
function PortfolioPage() {
const { data, isLoading } = useQuery({
queryKey: ['portfolio'],
queryFn: () => portfolioApi.getCurrent()
});
const updateMutation = useMutation({
mutationFn: portfolioApi.update,
onSuccess: () => {
// Invalidate and refetch
queryClient.invalidateQueries({ queryKey: ['portfolio'] });
}
});
}
```
## State Management
### Component State
- Local component state with `useState`
- Form state management
- UI-only state (modals, tabs, etc.)
### Server State
- React Query for server state
- Automatic caching and synchronization
- Optimistic updates
### Global State
- Context API for theme, auth (if needed)
- Minimal global state - prefer server state
## Component Patterns
### Container/Presentational Pattern
```typescript
// Container component (handles data fetching)
function TradingPageContainer() {
const { data } = useQuery({ queryKey: ['orders'], queryFn: fetchOrders });
return <TradingPage orders={data} />;
}
// Presentational component (pure UI)
function TradingPage({ orders }) {
return (
<Box>
<OrdersTable orders={orders} />
</Box>
);
}
```
### Custom Hooks
Extract reusable logic into custom hooks:
```typescript
function useOrders() {
const { data, isLoading, error } = useQuery({
queryKey: ['orders'],
queryFn: () => tradingApi.getOrders()
});
const placeOrder = useMutation({
mutationFn: tradingApi.placeOrder
});
return { orders: data, isLoading, error, placeOrder };
}
```
## Error Handling
### API Errors
```typescript
try {
await tradingApi.placeOrder(order);
} catch (error) {
if (error.response?.status === 400) {
// Handle validation error
} else if (error.response?.status === 500) {
// Handle server error
}
}
```
### Error Boundaries
Use React Error Boundaries to catch and display errors gracefully:
```typescript
<ErrorBoundary fallback={<ErrorPage />}>
<TradingPage />
</ErrorBoundary>
```
## Performance Optimization
### Code Splitting
Use React.lazy for code splitting:
```typescript
const TradingPage = lazy(() => import('@/pages/TradingPage'));
<Suspense fallback={<Loading />}>
<TradingPage />
</Suspense>
```
### Memoization
Use React.memo, useMemo, and useCallback to prevent unnecessary re-renders:
```typescript
const MemoizedTable = React.memo(OrdersTable);
const filteredData = useMemo(() => {
return data.filter(/* ... */);
}, [data, filter]);
```
## Testing
See [Testing Guide](../developer/testing.md) for frontend testing strategies.
## Styling
- Material-UI components and theming
- Consistent design system
- Dark/light theme support
- Responsive design
## Accessibility
- Semantic HTML
- ARIA labels where needed
- Keyboard navigation
- Screen reader support

116
docs/deployment/README.md Normal file
View File

@@ -0,0 +1,116 @@
# Deployment Guide
This guide covers deploying Crypto Trader in various environments.
## Table of Contents
1. [AppImage Deployment](appimage.md) - Building and distributing AppImage
2. [Bluefin Linux](bluefin.md) - Bluefin Linux specific instructions
3. [PostgreSQL Setup](postgresql.md) - PostgreSQL configuration
4. [Updates](updates.md) - Update mechanism and versioning
## Deployment Options
### AppImage (Recommended)
- Single executable file
- No installation required
- Portable across Linux distributions
- Includes all dependencies
### From Source
- Full control over installation
- Customizable configuration
- Development and production use
## System Requirements
- **OS**: Linux (Bluefin recommended), macOS, Windows
- **Python**: 3.11+ (for source installation)
- **Node.js**: 18+ (for frontend)
- **Memory**: 4GB minimum, 8GB recommended
- **Storage**: 1GB+ for application and data
- **Network**: Internet connection required
- **Redis**: Version 5.0+ (for state management)
- **PostgreSQL**: Version 14+ (for database)
## Quick Deployment
### AppImage
1. Download AppImage
2. Make executable: `chmod +x crypto_trader-*.AppImage`
3. Run: `./crypto_trader-*.AppImage`
### From Source
1. Clone repository
2. Install dependencies: `pip install -r requirements.txt`
3. Install frontend dependencies: `cd frontend && npm install`
4. Start Redis (see Redis section below for options)
5. Start Celery worker: `celery -A src.worker.app worker --loglevel=info &`
6. Start backend: `uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 &`
7. Start frontend: `cd frontend && npm run dev`
Or use the helper script:
```bash
./scripts/start_all.sh
```
## Required Services
### Redis
Redis is required for distributed state management and Celery background tasks (e.g., ML model training).
```bash
# Install (Ubuntu/Debian)
sudo apt-get install redis-server
```
**Starting Redis**:
```bash
# Option 1: Using system service (requires sudo)
sudo service redis-server start
# Option 2: Direct daemon mode (for containers/restricted environments)
redis-server --daemonize yes
# Verify
redis-cli ping # Should return PONG
```
> **Note**: In containerized environments (Toolbox, Distrobox, etc.) where `sudo` is not available, use the direct daemon mode option.
### Celery Worker
Celery handles background tasks like ML training:
```bash
# Start worker
celery -A src.worker.app worker --loglevel=info
# Start with specific queues
celery -A src.worker.app worker -Q ml_training,celery --loglevel=info
```
## Post-Deployment
After deployment:
1. Configure exchanges
2. Set up risk management
3. Verify Redis connection: `python scripts/verify_redis.py`
4. Test with paper trading
5. Review configuration
6. Start with small positions
## Production Considerations
- Use a process manager (systemd, supervisor) for services
- Configure Redis persistence (AOF or RDB)
- Set up monitoring and alerting
- Enable HTTPS for the API
- Configure proper firewall rules

171
docs/deployment/postgresql.md Normal file
View File

@@ -0,0 +1,171 @@
# PostgreSQL Setup
This guide covers optional PostgreSQL database configuration.
## When to Use PostgreSQL
PostgreSQL is recommended for:
- Large datasets (millions of trades)
- Multiple users
- Advanced queries
- Production deployments
- High-performance requirements
## Installation
### Install PostgreSQL
**Fedora/Bluefin**:
```bash
sudo dnf install postgresql postgresql-server
sudo postgresql-setup --initdb
sudo systemctl enable postgresql
sudo systemctl start postgresql
```
**Ubuntu/Debian**:
```bash
sudo apt-get install postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql
```
## Database Setup
### Create Database
```bash
sudo -u postgres psql
```
```sql
CREATE DATABASE crypto_trader;
CREATE USER crypto_trader_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE crypto_trader TO crypto_trader_user;
\q
```
### Configure Connection
Update `config.yaml`:
```yaml
database:
type: postgresql
host: localhost
port: 5432
database: crypto_trader
user: crypto_trader_user
password: ${DB_PASSWORD} # Use environment variable
```
### Set Environment Variable
```bash
export DB_PASSWORD='your_password'
```
Or add to `~/.bashrc`:
```bash
echo 'export DB_PASSWORD="your_password"' >> ~/.bashrc
```
## Migration from SQLite
### Export from SQLite
```bash
sqlite3 trading.db .dump > dump.sql
```
### Import to PostgreSQL
```bash
psql -U crypto_trader_user -d crypto_trader -f dump.sql
```
## Performance Tuning
### PostgreSQL Configuration
Edit `/etc/postgresql/*/main/postgresql.conf`:
```ini
shared_buffers = 256MB
effective_cache_size = 1GB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 4MB
min_wal_size = 1GB
max_wal_size = 4GB
```
### Indexes
Key indexes are created automatically. For custom queries, add indexes:
```sql
CREATE INDEX idx_trades_symbol_date ON trades(symbol, executed_at);
CREATE INDEX idx_market_data_symbol_timeframe ON market_data(symbol, timeframe, timestamp);
```
## Backup and Recovery
### Backup
```bash
pg_dump -U crypto_trader_user crypto_trader > backup.sql
```
### Restore
```bash
psql -U crypto_trader_user crypto_trader < backup.sql
```
### Automated Backups
Set up cron job:
```bash
0 2 * * * pg_dump -U crypto_trader_user crypto_trader > /backup/crypto_trader_$(date +\%Y\%m\%d).sql
```
## Security
### Connection Security
- Use strong passwords
- Restrict network access
- Use SSL connections for remote access
- Regular security updates
### User Permissions
- Use dedicated database user
- Grant only necessary permissions
- Don't use superuser for application
## Troubleshooting
**Connection refused?**
- Check PostgreSQL is running: `sudo systemctl status postgresql`
- Verify connection settings
- Check firewall rules
**Authentication failed?**
- Verify username and password
- Check `pg_hba.conf` configuration
- Review PostgreSQL logs
**Performance issues?**
- Check PostgreSQL configuration
- Review query performance
- Add appropriate indexes
- Monitor resource usage

131
docs/deployment/updates.md Normal file
View File

@@ -0,0 +1,131 @@
# Update Mechanism
This guide covers the built-in update mechanism for Crypto Trader.
## Update System
Crypto Trader includes a built-in update checker and installer for AppImage deployments.
## Update Check
### Automatic Check
Updates are checked on application startup (if enabled):
```yaml
updates:
check_on_startup: true
repository_url: "https://github.com/user/crypto_trader"
```
### Manual Check
Check for updates from the application:
1. Navigate to Help > Check for Updates
2. Application checks GitHub releases
3. Notifies if update available
## Update Process
### Automatic Update
1. **Check for Updates**
- Compares current version with latest release
- Downloads update information
2. **Download Update**
- Downloads new AppImage
- Shows progress
- Verifies download
3. **Install Update**
- Creates backup of current version
- Replaces with new version
- Makes executable
4. **Restart**
- Prompts to restart
- Launches new version
### Manual Update
1. Download new AppImage
2. Replace old file
3. Make executable: `chmod +x crypto_trader-*.AppImage`
4. Run new version
## Version Management
### Version Format
Follows semantic versioning: `MAJOR.MINOR.PATCH`
Example: `1.2.3`
### Version Comparison
- **Major**: Breaking changes
- **Minor**: New features (backward compatible)
- **Patch**: Bug fixes (backward compatible)
## Update Configuration
### Disable Auto-Check
```yaml
updates:
check_on_startup: false
```
### Custom Repository
```yaml
updates:
repository_url: "https://github.com/your-org/crypto_trader"
```
## Update Notifications
Users are notified when:
- Update is available on startup
- Manual check finds update
- Critical security update available
## Rollback
If update causes issues:
1. Locate backup: `crypto_trader-*.AppImage.backup`
2. Restore backup:
```bash
mv crypto_trader-*.AppImage.backup crypto_trader-*.AppImage
chmod +x crypto_trader-*.AppImage
```
3. Run previous version
## Best Practices
1. **Test Updates**: Test updates in development first
2. **Backup**: Always backup before updating
3. **Release Notes**: Review release notes before updating
4. **Staged Rollout**: Consider staged rollout for major updates
## Troubleshooting
**Update check fails?**
- Check internet connection
- Verify repository URL
- Review application logs
**Download fails?**
- Check disk space
- Verify download URL
- Check network connection
**Installation fails?**
- Check file permissions
- Verify AppImage integrity
- Review error logs

262
docs/deployment/web_architecture.md Normal file
View File

@@ -0,0 +1,262 @@
# Web Architecture Deployment Guide
This guide covers deploying the new web-based architecture for Crypto Trader.
## Overview
The application has been migrated from PyQt6 desktop app to a modern web-based architecture:
- **Frontend**: React + TypeScript + Material-UI
- **Backend**: FastAPI (Python)
- **Deployment**: Docker
## Architecture
```
┌─────────────────────────────────────────┐
│ Web Browser (Client) │
│ React + Material-UI + TypeScript │
└─────────────────┬───────────────────────┘
│ HTTP/WebSocket
┌─────────────────▼───────────────────────┐
│ Python Backend API (FastAPI) │
│ - Trading Engine (existing code) │
│ - Strategy Framework (existing code) │
│ - Portfolio Management (existing code) │
└─────────────────┬───────────────────────┘
│
┌─────────────────▼───────────────────────┐
│ Database (SQLite/PostgreSQL) │
└─────────────────────────────────────────┘
```
## Quick Start
### Development
1. **Start Backend**:
```bash
cd backend
python -m uvicorn main:app --reload --port 8000
```
2. **Start Frontend**:
```bash
cd frontend
npm install
npm run dev
```
3. **Access Application**:
- Frontend: http://localhost:3000
- API Docs: http://localhost:8000/docs
- API: http://localhost:8000/api
### Docker Deployment
1. **Build and Run**:
```bash
docker-compose up --build
```
2. **Access Application**:
- Application: http://localhost:8000
- API Docs: http://localhost:8000/docs
## API Endpoints
### Trading
- `POST /api/trading/orders` - Create order
- `GET /api/trading/orders` - List orders
- `GET /api/trading/orders/{id}` - Get order
- `POST /api/trading/orders/{id}/cancel` - Cancel order
- `GET /api/trading/positions` - Get positions
- `GET /api/trading/balance` - Get balance
### Portfolio
- `GET /api/portfolio/current` - Get current portfolio
- `GET /api/portfolio/history` - Get portfolio history
- `POST /api/portfolio/positions/update-prices` - Update prices
### Strategies
- `GET /api/strategies/` - List strategies
- `GET /api/strategies/available` - List available strategy types
- `POST /api/strategies/` - Create strategy
- `GET /api/strategies/{id}` - Get strategy
- `PUT /api/strategies/{id}` - Update strategy
- `DELETE /api/strategies/{id}` - Delete strategy
- `POST /api/strategies/{id}/start` - Start strategy
- `POST /api/strategies/{id}/stop` - Stop strategy
### Backtesting
- `POST /api/backtesting/run` - Run backtest
- `GET /api/backtesting/results/{id}` - Get backtest results
### Exchanges
- `GET /api/exchanges/` - List exchanges
- `GET /api/exchanges/{id}` - Get exchange
### WebSocket
- `WS /ws/` - WebSocket connection for real-time updates
## Configuration
### Environment Variables
Create `.env` file:
```env
# API Configuration
VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000/ws/
# Database (optional)
DATABASE_URL=sqlite:///./data/crypto_trader.db
```
### Docker Environment
Environment variables can be set in `docker-compose.yml`:
```yaml
environment:
- DATABASE_URL=sqlite:///./data/crypto_trader.db
- PYTHONPATH=/app
```
## Data Persistence
Data is stored in the `./data` directory, which is mounted as a volume in Docker:
```yaml
volumes:
- ./data:/app/data
```
## Development
### Backend Development
1. Install dependencies:
```bash
pip install -r requirements.txt
pip install -r backend/requirements.txt
```
2. Run with hot-reload:
```bash
python -m uvicorn backend.main:app --reload
```
### Frontend Development
1. Install dependencies:
```bash
cd frontend
npm install
```
2. Run development server:
```bash
npm run dev
```
3. Build for production:
```bash
npm run build
```
## Production Deployment
### Docker Production
1. Build production image:
```bash
docker build -t crypto-trader:latest .
```
2. Run container:
```bash
docker run -d \
-p 8000:8000 \
-v $(pwd)/data:/app/data \
-v $(pwd)/config:/app/config \
--name crypto-trader \
crypto-trader:latest
```
### Reverse Proxy (Nginx)
Example Nginx configuration:
```nginx
server {
listen 80;
server_name crypto-trader.example.com;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /ws/ {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}
```
## Migration from PyQt6
The existing Python code has been preserved:
- Trading engine (`src/trading/`)
- Strategy framework (`src/strategies/`)
- Portfolio tracker (`src/portfolio/`)
- Backtesting engine (`src/backtesting/`)
- All other core modules
Only the UI layer has been replaced with a web interface.
## Troubleshooting
### Backend Issues
- **Port already in use**: Change port in `docker-compose.yml` or use `--port` flag
- **Database errors**: Check database file permissions in `./data` directory
- **Import errors**: Ensure `PYTHONPATH=/app` is set
### Frontend Issues
- **API connection errors**: Check `VITE_API_URL` in `.env` file
- **WebSocket connection fails**: Verify WebSocket URL and backend is running
- **Build errors**: Clear `node_modules` and reinstall: `rm -rf node_modules && npm install`
### Docker Issues
- **Build fails**: Check Dockerfile syntax and dependencies
- **Container won't start**: Check logs: `docker-compose logs`
- **Volume permissions**: Ensure `./data` directory is writable
## Benefits of Web Architecture
1. **Modern UI**: Access to entire web ecosystem (Material-UI, charts, etc.)
2. **Cross-platform**: Works on any device with a browser
3. **Easier deployment**: Docker is simpler than AppImage
4. **Better development**: Hot-reload, better tooling
5. **Maintainability**: Easier to update and deploy
6. **Accessibility**: Access from anywhere via browser
## Next Steps
1. Add authentication (JWT tokens)
2. Implement WebSocket price updates
3. Add more charting capabilities
4. Enhance strategy management UI
5. Add mobile-responsive design

40
docs/developer/README.md Normal file
View File

@@ -0,0 +1,40 @@
# Developer Guide
Welcome to the Crypto Trader developer guide. This guide will help you set up a development environment, understand the codebase, and contribute to the project.
## Table of Contents
1. [Development Setup](setup.md) - Setting up your development environment
2. [Architecture Overview](architecture.md) - System architecture and design
3. [Coding Standards](coding_standards.md) - Code style and conventions
4. [Adding Exchanges](adding_exchanges.md) - How to add new exchange adapters
5. [Creating Strategies](creating_strategies.md) - Strategy development guide
6. [Testing](testing.md) - Testing guidelines and practices
7. [Contributing](contributing.md) - Contribution guidelines
8. [Release Process](release_process.md) - Release and deployment process
## Quick Start
1. [Set up development environment](setup.md)
2. [Review architecture](architecture.md)
3. [Read coding standards](coding_standards.md)
4. [Run tests](testing.md#running-tests)
5. [Make your first contribution](contributing.md)
## Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write/update tests
5. Ensure all tests pass
6. Update documentation
7. Submit a pull request
## Getting Help
- Review the [API Documentation](../api/index.html)
- Check existing issues and pull requests
- Ask questions in discussions
- Review code examples in the codebase

216
docs/developer/adding_exchanges.md Normal file
View File

@@ -0,0 +1,216 @@
# Adding New Exchange Adapters
This guide explains how to add support for new cryptocurrency exchanges.
## Exchange Adapter Architecture
All exchange adapters inherit from `BaseExchange` and implement a standardized interface. This allows the trading engine to work with any exchange through a common API.
## Implementation Steps
### 1. Create Exchange Module
Create a new file in `src/exchanges/`:
```python
# src/exchanges/your_exchange.py
from src.exchanges.base import BaseExchange
from src.exchanges.factory import ExchangeFactory
import ccxt.pro as ccxt
import logging
logger = logging.getLogger(__name__)
class YourExchangeAdapter(BaseExchange):
"""Adapter for Your Exchange."""
def __init__(self, name: str, api_key: str, secret_key: str, password: str = None):
super().__init__(name, api_key, secret_key, password)
self.exchange = ccxt.yourexchange({
'apiKey': self.api_key,
'secret': self.secret_key,
'enableRateLimit': True,
})
async def connect(self):
"""Establish connection to exchange."""
await self.exchange.load_markets()
self.is_connected = True
logger.info(f"Connected to {self.name}")
# Implement all required methods from BaseExchange
# ...
```
### 2. Implement Required Methods
Implement all abstract methods from `BaseExchange`:
- `connect()` - Establish connection
- `disconnect()` - Close connection
- `fetch_balance()` - Get account balance
- `place_order()` - Place order
- `cancel_order()` - Cancel order
- `fetch_order_status()` - Get order status
- `fetch_ohlcv()` - Get historical data
- `subscribe_ohlcv()` - Real-time OHLCV
- `subscribe_trades()` - Real-time trades
- `subscribe_order_book()` - Real-time order book
- `fetch_open_orders()` - Get open orders
- `fetch_positions()` - Get positions (futures)
- `fetch_markets()` - Get available markets
### 3. Register Exchange
Register the exchange in `src/exchanges/__init__.py`:
```python
from .your_exchange import YourExchangeAdapter
from .factory import ExchangeFactory
ExchangeFactory.register_exchange("your_exchange", YourExchangeAdapter)
```
### 4. Handle Exchange-Specific Features
Some exchanges have unique features:
- **Authentication**: Some exchanges use different auth methods
- **Rate Limits**: Respect exchange rate limits
- **WebSocket**: Implement exchange-specific WebSocket protocol
- **Order Types**: Support exchange-specific order types
### 5. Write Tests
Create tests in `tests/unit/exchanges/test_your_exchange.py`:
```python
import pytest
from unittest.mock import Mock, patch
from src.exchanges.your_exchange import YourExchangeAdapter
class TestYourExchangeAdapter:
"""Tests for Your Exchange adapter."""
@pytest.fixture
def adapter(self):
return YourExchangeAdapter(
name="test",
api_key="test_key",
secret_key="test_secret"
)
@pytest.mark.asyncio
async def test_connect(self, adapter):
"""Test connection."""
with patch.object(adapter.exchange, 'load_markets'):
await adapter.connect()
assert adapter.is_connected
# Add more tests...
```
## Using CCXT
Most exchanges can use the `ccxt` library:
```python
import ccxt.pro as ccxt
exchange = ccxt.pro.yourexchange({
'apiKey': api_key,
'secret': secret_key,
'enableRateLimit': True,
})
# Use ccxt methods
balance = await exchange.fetch_balance()
order = await exchange.create_order(...)
```
## Exchange-Specific Considerations
### Authentication
Some exchanges require additional authentication:
```python
# Example: Exchange requiring passphrase
self.exchange = ccxt.coinbase({
'apiKey': api_key,
'secret': secret_key,
'password': passphrase, # Coinbase requires this
})
```
### Rate Limits
Always enable rate limiting:
```python
self.exchange = ccxt.yourexchange({
'enableRateLimit': True, # Important!
})
```
### WebSocket Support
For real-time data, implement WebSocket connections:
```python
async def subscribe_ohlcv(self, symbol: str, timeframe: str, callback):
"""Subscribe to OHLCV updates."""
# Exchange-specific WebSocket implementation
await self.exchange.watch_ohlcv(symbol, timeframe, callback)
```
## Testing Your Adapter
### Unit Tests
Test all methods with mocked exchange responses:
```python
@pytest.mark.asyncio
async def test_fetch_balance(self, adapter):
"""Test balance fetching."""
mock_balance = {'BTC': {'free': 1.0, 'used': 0.0, 'total': 1.0}}
with patch.object(adapter.exchange, 'fetch_balance', return_value=mock_balance):
balance = await adapter.fetch_balance()
assert 'BTC' in balance
```
### Integration Tests
Test with real exchange (use testnet/sandbox if available):
```python
@pytest.mark.integration
async def test_real_connection(self):
"""Test real connection (requires API keys)."""
adapter = YourExchangeAdapter(...)
await adapter.connect()
assert adapter.is_connected
```
## Documentation
Document your exchange adapter:
1. Add docstrings to all methods
2. Document exchange-specific features
3. Add usage examples
4. Update API documentation
## Best Practices
1. **Error Handling**: Handle exchange-specific errors
2. **Rate Limiting**: Always respect rate limits
3. **Retry Logic**: Implement retry for transient failures
4. **Logging**: Log important operations
5. **Testing**: Test thoroughly before submitting
## Example: Complete Exchange Adapter
See `src/exchanges/coinbase.py` for a complete example implementation.

226
docs/developer/coding_standards.md Normal file
View File

@@ -0,0 +1,226 @@
# Coding Standards
This document outlines the coding standards and conventions for Crypto Trader.
## Code Style
### Python Style Guide
Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) with the following additions:
- **Line Length**: Maximum 100 characters
- **Indentation**: 4 spaces (no tabs)
- **Imports**: Grouped and sorted (stdlib, third-party, local)
- **Naming**:
- Classes: `PascalCase`
- Functions/Variables: `snake_case`
- Constants: `UPPER_SNAKE_CASE`
- Private: `_leading_underscore`
### Code Formatting
Use `black` for automatic formatting:
```bash
black src/ tests/
```
### Type Hints
Always use type hints for function signatures:
```python
def calculate_position_size(
capital: float,
risk_percentage: float
) -> float:
"""Calculate position size."""
return capital * risk_percentage
```
### Docstrings
Use Google-style docstrings:
```python
def fetch_balance(self) -> Dict[str, Any]:
"""Fetches the account balance.
Args:
None
Returns:
Dictionary containing balance information with keys:
- 'free': Available balance
- 'used': Used balance
- 'total': Total balance
Raises:
ConnectionError: If exchange connection fails
ValueError: If exchange credentials are invalid
"""
pass
```
## File Organization
### Module Structure
```python
"""Module docstring describing the module."""
# Standard library imports
import os
from typing import Dict, List
# Third-party imports
import pandas as pd
from sqlalchemy import Column
# Local imports
from ..core.logger import get_logger
from .base import BaseClass
# Constants
DEFAULT_VALUE = 100
# Module-level variables
logger = get_logger(__name__)
# Classes
class MyClass:
"""Class docstring."""
pass
# Functions
def my_function():
"""Function docstring."""
pass
```
## Error Handling
### Exception Handling
```python
try:
result = risky_operation()
except SpecificError as e:
logger.error(f"Operation failed: {e}")
raise
except Exception as e:
logger.exception("Unexpected error")
raise RuntimeError("Operation failed") from e
```
### Logging
Use appropriate log levels:
- **DEBUG**: Detailed information for debugging
- **INFO**: General informational messages
- **WARNING**: Warning messages
- **ERROR**: Error messages
- **CRITICAL**: Critical errors
```python
logger.debug("Detailed debug information")
logger.info("Operation completed successfully")
logger.warning("Deprecated function used")
logger.error("Operation failed")
logger.critical("System failure")
```
## Testing Standards
### Test Naming
```python
def test_function_name_should_do_something():
"""Test description."""
pass
class TestClassName:
"""Test class description."""
def test_method_should_handle_case(self):
"""Test method description."""
pass
```
### Test Organization
- One test class per module
- Test methods should be independent
- Use fixtures for common setup
- Mock external dependencies
## Documentation Standards
### Inline Comments
```python
# Calculate position size using Kelly Criterion
# Formula: f = (bp - q) / b
fraction = (payout_ratio * win_prob - loss_prob) / payout_ratio
```
### Function Documentation
Always document:
- Purpose
- Parameters
- Return values
- Exceptions
- Examples (when helpful)
## Git Commit Messages
Follow conventional commits:
```
type(scope): subject
body
footer
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `test`: Tests
- `refactor`: Code refactoring
- `chore`: Maintenance
Example:
```
feat(trading): add trailing stop order support
Implemented trailing stop orders with configurable
trail percentage and activation price.
Closes #123
```
## Code Review Guidelines
### What to Review
- Code correctness
- Test coverage
- Documentation
- Performance
- Security
- Style compliance
### Review Checklist
- [ ] Code follows style guide
- [ ] Tests are included
- [ ] Documentation is updated
- [ ] No security issues
- [ ] Performance is acceptable
- [ ] Error handling is appropriate

115
docs/developer/contributing.md Normal file
View File

@@ -0,0 +1,115 @@
# Contributing Guidelines
Thank you for your interest in contributing to Crypto Trader!
## How to Contribute
### Reporting Bugs
1. Check if the bug has already been reported
2. Create a new issue with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- System information
- Log files (if applicable)
### Suggesting Features
1. Check if the feature has been suggested
2. Create a feature request with:
- Use case description
- Proposed solution
- Benefits
- Implementation considerations
### Code Contributions
1. **Fork the repository**
2. **Create a feature branch**:
```bash
git checkout -b feature/my-feature
```
3. **Make your changes**:
- Follow coding standards
- Write tests
- Update documentation
4. **Run tests**:
```bash
pytest
```
5. **Commit changes**:
```bash
git commit -m "feat(module): add new feature"
```
6. **Push to your fork**:
```bash
git push origin feature/my-feature
```
7. **Create a pull request**
## Pull Request Process
### Before Submitting
- [ ] Code follows style guide
- [ ] Tests are included and passing
- [ ] Documentation is updated
- [ ] No new warnings or errors
- [ ] Coverage is maintained
### Pull Request Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
How was this tested?
## Checklist
- [ ] Code follows style guide
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
```
## Code Review
All pull requests require review:
- At least one approval required
- Address review comments
- Keep PR focused and small when possible
- Respond to feedback promptly
## Development Setup
See [Development Setup](setup.md) for environment setup.
## Coding Standards
See [Coding Standards](coding_standards.md) for detailed guidelines.
## Questions?
- Open a discussion
- Check existing issues
- Review documentation
- Ask in comments
## Recognition
Contributors will be recognized in:
- CONTRIBUTORS.md
- Release notes
- Project documentation
Thank you for contributing!

233
docs/developer/creating_strategies.md Normal file
View File

@@ -0,0 +1,233 @@
# Creating Custom Strategies
This guide explains how to create custom trading strategies for Crypto Trader.
## Strategy Framework
All strategies inherit from `BaseStrategy` and implement a standardized interface. This allows the trading engine to execute any strategy uniformly.
## Basic Strategy Structure
```python
from src.strategies.base import BaseStrategy, StrategyRegistry
from src.data.indicators import get_indicators
import pandas as pd
from typing import Dict, Any
class MyCustomStrategy(BaseStrategy):
"""My custom trading strategy."""
def __init__(self, strategy_id: int, name: str, symbol: str, timeframe: str, parameters: Dict[str, Any]):
super().__init__(strategy_id, name, symbol, timeframe, parameters)
# Initialize strategy-specific parameters
self.my_param = parameters.get("my_param", 10)
async def on_data(self, new_data: pd.DataFrame):
"""Called when new data is available."""
# Update internal data
self.current_data = pd.concat([self.current_data, new_data])
# Generate signal if enough data
if len(self.current_data) >= self.my_param:
signal = await self.generate_signal()
if signal["signal"] != "hold":
# Signal generated - will be handled by trading engine
pass
async def generate_signal(self) -> Dict[str, Any]:
"""Generate trading signal."""
# Calculate indicators
indicators = get_indicators()
rsi = indicators.rsi(self.current_data['close'], period=14)
# Generate signal based on strategy logic
current_rsi = rsi.iloc[-1]
current_price = self.current_data['close'].iloc[-1]
if current_rsi < 30:
return {"signal": "buy", "price": current_price}
elif current_rsi > 70:
return {"signal": "sell", "price": current_price}
else:
return {"signal": "hold", "price": current_price}
async def calculate_position_size(self, capital: float, risk_percentage: float) -> float:
"""Calculate position size."""
return capital * risk_percentage
# Register strategy
StrategyRegistry.register_strategy("my_custom", MyCustomStrategy)
```
## Required Methods
### `on_data(new_data: pd.DataFrame)`
Called when new OHLCV data is available for the strategy's timeframe.
**Responsibilities**:
- Update internal data storage
- Calculate indicators
- Generate signals when conditions are met
### `generate_signal() -> Dict[str, Any]`
Analyzes current data and generates a trading signal.
**Returns**:
```python
{
"signal": "buy" | "sell" | "hold",
"price": float, # Optional, current price
"confidence": float, # Optional, 0.0 to 1.0
}
```
### `calculate_position_size(capital: float, risk_percentage: float) -> float`
Calculates the appropriate position size based on capital and risk.
**Parameters**:
- `capital`: Available trading capital
- `risk_percentage`: Percentage of capital to risk (0.0 to 1.0)
**Returns**: Position size in base currency
## Using Technical Indicators
Access indicators through the indicators library:
```python
from src.data.indicators import get_indicators
indicators = get_indicators()
# Calculate indicators
sma = indicators.sma(data['close'], period=20)
ema = indicators.ema(data['close'], period=20)
rsi = indicators.rsi(data['close'], period=14)
macd_result = indicators.macd(data['close'], fast=12, slow=26, signal=9)
bbands = indicators.bollinger_bands(data['close'], period=20, std_dev=2)
```
## Multi-Timeframe Strategies
Strategies can use multiple timeframes:
```python
from src.strategies.timeframe_manager import get_timeframe_manager
timeframe_manager = get_timeframe_manager()
# Get data from different timeframes
primary_data = timeframe_manager.get_data(self.symbol, self.timeframe)
higher_tf_data = timeframe_manager.get_data(self.symbol, "1d") # Daily for trend
# Use higher timeframe for trend confirmation
if higher_tf_data is not None and len(higher_tf_data) > 0:
daily_trend = higher_tf_data['close'].iloc[-1] > higher_tf_data['close'].iloc[-20]
if daily_trend:
# Only trade in direction of higher timeframe trend
pass
```
## Strategy Parameters
Define configurable parameters:
```python
def __init__(self, strategy_id: int, name: str, symbol: str, timeframe: str, parameters: Dict[str, Any]):
super().__init__(strategy_id, name, symbol, timeframe, parameters)
# Required parameters with defaults
self.rsi_period = parameters.get("rsi_period", 14)
self.overbought = parameters.get("overbought", 70)
self.oversold = parameters.get("oversold", 30)
# Validate parameters
if not (0 < self.oversold < self.overbought < 100):
raise ValueError("Invalid RSI thresholds")
```
## Strategy Registration
Register your strategy so it can be used:
```python
from src.strategies.base import StrategyRegistry
StrategyRegistry.register_strategy("my_strategy", MyCustomStrategy)
```
## Strategy Lifecycle
1. **Initialization**: Strategy is created with parameters
2. **Start**: `start()` is called when strategy is activated
3. **Data Updates**: `on_data()` is called with new candles
4. **Signal Generation**: `generate_signal()` is called when conditions are met
5. **Order Execution**: Trading engine executes signals
6. **Stop**: `stop()` is called when strategy is deactivated
## Best Practices
1. **Parameter Validation**: Validate all parameters in `__init__`
2. **Error Handling**: Handle missing data and calculation errors
3. **Logging**: Use strategy logger for important events
4. **Testing**: Write unit tests for your strategy
5. **Documentation**: Document strategy logic and parameters
6. **Backtesting**: Always backtest before live trading
## Example: Complete Strategy
See `src/strategies/technical/rsi_strategy.py` for a complete example.
## Available Strategy Examples
The codebase includes several advanced strategy implementations that serve as examples:
### Multi-Indicator Confirmation
See `src/strategies/technical/confirmed_strategy.py` for an example of combining multiple indicators.
### Divergence Detection
See `src/strategies/technical/divergence_strategy.py` for an example of divergence detection using the indicators API.
### Ensemble Methods
See `src/strategies/ensemble/consensus_strategy.py` for an example of combining multiple strategies with weighted voting.
### Trend Filtering
All strategies can use the optional trend filter method from BaseStrategy:
```python
signal = strategy.apply_trend_filter(signal, ohlcv_data, adx_period=14, min_adx=25.0)
```
## Testing Your Strategy
```python
import pytest
from src.strategies.my_strategy import MyCustomStrategy
def test_strategy_signal_generation():
"""Test strategy signal generation."""
strategy = MyCustomStrategy(
strategy_id=1,
name="Test Strategy",
symbol="BTC/USD",
timeframe="1h",
parameters={"rsi_period": 14}
)
# Create test data
test_data = pd.DataFrame({
'close': [100, 101, 102, 103, 104]
})
# Test signal generation
signal = await strategy.generate_signal()
assert signal["signal"] in ["buy", "sell", "hold"]
```

270
docs/developer/frontend_testing.md Normal file
View File

@@ -0,0 +1,270 @@
# Frontend Testing Guide
This guide explains how to test the React frontend components and pages.
## Testing Setup
The frontend uses Vitest (recommended) or Jest for testing React components. To set up testing:
```bash
cd frontend
npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event vitest @vitest/ui jsdom
```
Add to `package.json`:
```json
{
"scripts": {
"test": "vitest",
"test:ui": "vitest --ui",
"test:coverage": "vitest --coverage"
}
}
```
## Testing Strategy
### Component Testing
Test individual components in isolation:
```typescript
// frontend/src/components/__tests__/StatusIndicator.test.tsx
import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import StatusIndicator from '../StatusIndicator';
describe('StatusIndicator', () => {
it('renders connected status correctly', () => {
render(<StatusIndicator status="connected" label="WebSocket" />);
expect(screen.getByText('WebSocket')).toBeInTheDocument();
});
it('shows correct color for error status', () => {
render(<StatusIndicator status="error" label="Error" />);
const chip = screen.getByText('Error');
expect(chip).toHaveClass('MuiChip-colorError');
});
});
```
### Page Testing
Test complete page workflows:
```typescript
// frontend/src/pages/__tests__/StrategiesPage.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { describe, it, expect, vi } from 'vitest';
import StrategiesPage from '../StrategiesPage';
import * as strategiesApi from '../../api/strategies';
vi.mock('../../api/strategies');
describe('StrategiesPage', () => {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } }
});
it('displays list of strategies', async () => {
const mockStrategies = [
{
id: 1,
name: 'Test Strategy',
strategy_type: 'rsi',
enabled: false,
paper_trading: true,
// ... other fields
}
];
vi.mocked(strategiesApi.strategiesApi.listStrategies).mockResolvedValue(mockStrategies);
render(
<QueryClientProvider client={queryClient}>
<StrategiesPage />
</QueryClientProvider>
);
await waitFor(() => {
expect(screen.getByText('Test Strategy')).toBeInTheDocument();
});
});
it('shows create strategy button', () => {
render(
<QueryClientProvider client={queryClient}>
<StrategiesPage />
</QueryClientProvider>
);
expect(screen.getByText('Create Strategy')).toBeInTheDocument();
});
});
```
### API Integration Testing
Test API client functions:
```typescript
// frontend/src/api/__tests__/strategies.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { strategiesApi } from '../strategies';
import { apiClient } from '../client';
vi.mock('../client');
describe('strategiesApi', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('lists strategies', async () => {
const mockStrategies = [{ id: 1, name: 'Test' }];
vi.mocked(apiClient.get).mockResolvedValue({ data: mockStrategies });
const result = await strategiesApi.listStrategies();
expect(result).toEqual(mockStrategies);
expect(apiClient.get).toHaveBeenCalledWith('/api/strategies/');
});
it('creates strategy', async () => {
const newStrategy = { name: 'New', strategy_type: 'rsi' };
const created = { id: 1, ...newStrategy };
vi.mocked(apiClient.post).mockResolvedValue({ data: created });
const result = await strategiesApi.createStrategy(newStrategy);
expect(result).toEqual(created);
});
});
```
### Hook Testing
Test custom React hooks:
```typescript
// frontend/src/hooks/__tests__/useWebSocket.test.ts
import { renderHook, waitFor } from '@testing-library/react';
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { useWebSocket } from '../useWebSocket';
// Mock WebSocket
global.WebSocket = vi.fn(() => ({
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
send: vi.fn(),
close: vi.fn(),
readyState: WebSocket.OPEN,
})) as any;
describe('useWebSocket', () => {
it('connects to WebSocket', async () => {
const { result } = renderHook(() => useWebSocket('ws://localhost:8000/ws/'));
await waitFor(() => {
expect(result.current.isConnected).toBe(true);
});
});
it('handles messages', async () => {
const { result } = renderHook(() => useWebSocket('ws://localhost:8000/ws/'));
// Simulate message
const ws = (global.WebSocket as any).mock.results[0].value;
const messageEvent = new MessageEvent('message', {
data: JSON.stringify({ type: 'order_update', order_id: 1 })
});
ws.onmessage(messageEvent);
await waitFor(() => {
expect(result.current.lastMessage).toBeTruthy();
});
});
});
```
## Test Coverage
### Components to Test
1. **Pages**:
- `StrategiesPage` - CRUD operations, start/stop
- `TradingPage` - Order placement, position closing
- `DashboardPage` - AutoPilot controls, system health
- `PortfolioPage` - Position management, charts
- `BacktestPage` - Backtest execution, results
- `SettingsPage` - All settings tabs
2. **Components**:
- `StrategyDialog` - Form validation, parameter configuration
- `OrderForm` - Order type handling, validation
- `PositionCard` - Position display, close functionality
- `StatusIndicator` - Status display
- `SystemHealth` - Health status aggregation
- `DataFreshness` - Timestamp calculations
- `OperationsPanel` - Operation display
3. **Hooks**:
- `useWebSocket` - Connection, messages, subscriptions
- `useRealtimeData` - Query invalidation
4. **Contexts**:
- `SnackbarContext` - Notification display
- `WebSocketProvider` - WebSocket management
## Running Tests
```bash
# Run all tests
npm test
# Run tests in watch mode
npm test -- --watch
# Run tests with UI
npm run test:ui
# Generate coverage report
npm run test:coverage
```
## Best Practices
1. **Mock External Dependencies**: Mock API calls, WebSocket connections
2. **Test User Interactions**: Use `@testing-library/user-event` for clicks, typing
3. **Test Error States**: Verify error handling and display
4. **Test Loading States**: Ensure loading indicators appear
5. **Test Accessibility**: Use `@testing-library/jest-dom` matchers
6. **Keep Tests Fast**: Mock expensive operations
7. **Test Edge Cases**: Empty states, error conditions, boundary values
## Example Test Suite Structure
```
frontend/src/
├── components/
│ ├── __tests__/
│ │ ├── StatusIndicator.test.tsx
│ │ ├── StrategyDialog.test.tsx
│ │ └── ...
│ └── ...
├── pages/
│ ├── __tests__/
│ │ ├── StrategiesPage.test.tsx
│ │ ├── TradingPage.test.tsx
│ │ └── ...
│ └── ...
├── hooks/
│ ├── __tests__/
│ │ ├── useWebSocket.test.ts
│ │ └── ...
│ └── ...
└── api/
├── __tests__/
│ ├── strategies.test.ts
│ └── ...
└── ...
```

243
docs/developer/pricing_providers.md Normal file
View File

@@ -0,0 +1,243 @@
# Pricing Provider Development Guide
This guide explains how to add new pricing data providers to the Crypto Trader system.
## Overview
Pricing providers are responsible for fetching market data (prices, OHLCV candlestick data) without requiring API keys. They differ from exchange adapters, which handle trading operations and require authentication.
The system uses a multi-tier provider strategy:
- **Primary Providers**: CCXT-based providers (Kraken, Coinbase, Binance)
- **Fallback Provider**: CoinGecko API
## Provider Interface
All pricing providers must implement the `BasePricingProvider` interface, located in `src/data/providers/base_provider.py`.
### Required Methods
1. **`name` (property)**: Return the provider's display name
2. **`supports_websocket` (property)**: Return True if the provider supports WebSocket connections
3. **`connect()`**: Establish connection to the provider, return True if successful
4. **`disconnect()`**: Close connection and clean up resources
5. **`get_ticker(symbol: str) -> Dict`**: Get current ticker data for a symbol
6. **`get_ohlcv(symbol, timeframe, since, limit) -> List[List]`**: Get historical OHLCV data
7. **`subscribe_ticker(symbol, callback) -> bool`**: Subscribe to real-time ticker updates
### Ticker Data Format
The `get_ticker()` method should return a dictionary with the following keys:
```python
{
'symbol': str, # Trading pair (e.g., 'BTC/USD')
'bid': Decimal, # Best bid price
'ask': Decimal, # Best ask price
'last': Decimal, # Last traded price
'high': Decimal, # 24h high
'low': Decimal, # 24h low
'volume': Decimal, # 24h volume
'timestamp': int, # Unix timestamp in milliseconds
}
```
### OHLCV Data Format
The `get_ohlcv()` method should return a list of candles, where each candle is:
```python
[timestamp_ms, open, high, low, close, volume]
```
All values should be numeric (float or Decimal).
## Creating a New Provider
### Step 1: Create Provider Class
Create a new file in `src/data/providers/` (e.g., `my_provider.py`):
```python
"""My custom pricing provider."""
from decimal import Decimal
from typing import Dict, List, Optional, Any, Callable
from datetime import datetime
from .base_provider import BasePricingProvider
from ...core.logger import get_logger
logger = get_logger(__name__)
class MyProvider(BasePricingProvider):
"""My custom pricing provider implementation."""
@property
def name(self) -> str:
return "MyProvider"
@property
def supports_websocket(self) -> bool:
return False # Set to True if WebSocket supported
def connect(self) -> bool:
"""Connect to provider."""
try:
# Initialize connection
self._connected = True
logger.info(f"Connected to {self.name}")
return True
except Exception as e:
logger.error(f"Failed to connect: {e}")
self._connected = False
return False
def disconnect(self):
"""Disconnect from provider."""
self._connected = False
logger.info(f"Disconnected from {self.name}")
def get_ticker(self, symbol: str) -> Dict[str, Any]:
"""Get current ticker data."""
# Implementation here
pass
def get_ohlcv(
self,
symbol: str,
timeframe: str = '1h',
since: Optional[datetime] = None,
limit: int = 100
) -> List[List]:
"""Get OHLCV data."""
# Implementation here
pass
def subscribe_ticker(self, symbol: str, callback: Callable) -> bool:
"""Subscribe to ticker updates."""
# Implementation here
pass
```
### Step 2: Register Provider
Update `src/data/providers/__init__.py` to include your provider:
```python
from .my_provider import MyProvider
__all__ = [..., 'MyProvider']
```
### Step 3: Add to Pricing Service
Update `src/data/pricing_service.py` to include your provider in the initialization:
```python
# Add to _initialize_providers method
try:
my_provider = MyProvider()
if my_provider.connect():
self._providers[my_provider.name] = my_provider
self._provider_priority.append(my_provider.name)
except Exception as e:
logger.error(f"Error initializing MyProvider: {e}")
```
### Step 4: Add Configuration
Update `src/core/config.py` to include configuration options for your provider:
```python
"data_providers": {
"primary": [
# ... existing providers ...
{"name": "my_provider", "enabled": True, "priority": 4},
],
# ...
}
```
## Best Practices
### Error Handling
- Always catch exceptions in provider methods
- Return empty data structures (`{}` or `[]`) on error rather than raising
- Log errors with appropriate detail level
### Rate Limiting
- Respect API rate limits
- Implement appropriate delays between requests
- Use exponential backoff for retries
### Symbol Normalization
- Override `normalize_symbol()` if your provider uses different symbol formats
- Handle common variations (BTC/USD vs BTC-USD vs BTCUSD)
### Caching
- The pricing service handles caching automatically
- Focus on providing fresh data from the API
- Don't implement your own caching layer
### Testing
Create unit tests in `tests/unit/data/providers/test_my_provider.py`:
```python
"""Unit tests for MyProvider."""
import pytest
from unittest.mock import Mock, patch
from src.data.providers.my_provider import MyProvider
class TestMyProvider:
def test_connect(self):
provider = MyProvider()
result = provider.connect()
assert result is True
def test_get_ticker(self):
provider = MyProvider()
provider.connect()
ticker = provider.get_ticker("BTC/USD")
assert 'last' in ticker
assert ticker['last'] > 0
```
## Example: CoinGecko Provider
See `src/data/providers/coingecko_provider.py` for a complete example of a REST API-based provider.
## Example: CCXT Provider
See `src/data/providers/ccxt_provider.py` for an example of a provider that wraps an existing library (CCXT).
## Health Monitoring
The pricing service automatically monitors provider health:
- Tracks success/failure rates
- Measures response times
- Implements circuit breaker pattern
- Automatically fails over to next provider
Your provider doesn't need to implement health monitoring - it's handled by the `HealthMonitor` class.
## Subscriptions
For real-time updates, implement `subscribe_ticker()`. The service expects:
- Subscriptions to be persistent until `unsubscribe_ticker()` is called
- Callbacks to be invoked with ticker data dictionaries
- Graceful handling of connection failures
If WebSocket is not supported, use polling with appropriate intervals (typically 1-5 seconds for ticker data).
## Questions?
For more information, see:
- `src/data/providers/base_provider.py` - Base interface
- `src/data/pricing_service.py` - Service implementation
- `src/data/health_monitor.py` - Health monitoring

180
docs/developer/release_process.md Normal file
View File

@@ -0,0 +1,180 @@
# Release Process
This guide outlines the process for releasing new versions of Crypto Trader.
## Version Numbering
Follow [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)
Example: `1.2.3`
## Release Checklist
### Pre-Release
- [ ] All tests passing
- [ ] Code coverage meets threshold (95%)
- [ ] Documentation is up to date
- [ ] Changelog is updated
- [ ] Version number updated
- [ ] All issues for milestone are closed
### Release Steps
1. **Update Version**
Update version in:
- `setup.py`
- `docs/api/source/conf.py`
- `src/__init__.py` (if exists)
2. **Update Changelog**
Document all changes in `CHANGELOG.md`:
- Added features
- Changed features
- Deprecated features
- Removed features
- Fixed bugs
- Security updates
3. **Create Release Branch**
```bash
git checkout -b release/v1.2.3
git push origin release/v1.2.3
```
4. **Build and Test**
```bash
# Run all tests
pytest
# Build AppImage
./packaging/build_appimage.sh
# Test AppImage
./crypto_trader-*.AppImage --test
```
5. **Create Release Tag**
```bash
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
```
6. **Create GitHub Release**
- Create release on GitHub
- Upload AppImage
- Add release notes from changelog
- Mark as latest release
7. **Merge to Main**
```bash
git checkout main
git merge release/v1.2.3
git push origin main
```
## AppImage Release
### Building AppImage
```bash
cd packaging
./build_appimage.sh
```
### AppImage Requirements
- Must be executable
- Must include all dependencies
- Must be tested on target system
- Must include version in filename
### AppImage Distribution
- Upload to GitHub Releases
- Include checksums (SHA256)
- Provide installation instructions
- Test on clean system
## Post-Release
1. **Announce Release**
- Update website (if applicable)
- Post release notes
- Notify users
2. **Monitor**
- Watch for issues
- Monitor error reports
- Track download statistics
3. **Hotfixes**
If critical bugs are found:
- Create hotfix branch
- Fix and test
- Release patch version
- Merge to main
## Release Notes Template
```markdown
# Release v1.2.3
## Added
- New feature X
- New feature Y
## Changed
- Improved performance of Z
- Updated dependency versions
## Fixed
- Fixed bug in A
- Fixed issue with B
## Security
- Security update for C
## Installation
Download the AppImage:
- [crypto_trader-1.2.3-x86_64.AppImage](link)
SHA256: [checksum]
## Upgrade Notes
[Any upgrade instructions]
```
## Emergency Releases
For critical security or stability issues:
1. Create hotfix branch from latest release
2. Apply fix
3. Test thoroughly
4. Release immediately
5. Merge to main and develop
## Version History
Maintain version history in:
- `CHANGELOG.md`
- GitHub Releases
- Documentation

315
docs/developer/setup.md Normal file
View File

@@ -0,0 +1,315 @@
# Development Environment Setup
This guide will help you set up a development environment for Crypto Trader.
## Prerequisites
- Python 3.11 or higher
- Node.js 18 or higher
- Git
- Virtual environment tool (venv or virtualenv)
- Code editor (VS Code, PyCharm, etc.)
- PostgreSQL 14 or higher
- Redis 5.0 or higher
## Initial Setup
### 1. Clone the Repository
```bash
git clone <repository-url>
cd crypto_trader
```
### 2. Create Virtual Environment
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
### 3. Install Python Dependencies
```bash
# Install main dependencies
pip install -r requirements.txt
# Install development dependencies
pip install -r tests/requirements.txt
# Install documentation dependencies
pip install -r docs/requirements.txt
```
### 4. Install Frontend Dependencies
```bash
cd frontend
npm install
cd ..
```
### 5. Install Pre-commit Hooks (Optional)
```bash
pip install pre-commit
pre-commit install
```
## Development Tools
### Recommended IDE Setup
**VS Code**:
- Python extension
- Pylance for type checking
- Python Test Explorer
- ESLint and Prettier for frontend
- YAML extension
**PyCharm**:
- Configure Python interpreter
- Set up test runner
- Configure code style
- Enable JavaScript/TypeScript support
### Code Quality Tools
```bash
# Install linting and formatting tools
pip install black flake8 mypy pylint
# Format code
black src/ tests/
# Lint code
flake8 src/ tests/
# Type checking
mypy src/
```
## Database Setup
### PostgreSQL (Required)
You must have a PostgreSQL instance running for development.
```bash
# Install PostgreSQL
# Create development database
createdb crypto_trader_dev
# Update config.yaml or set env var
# DATABASE_URL=postgresql+asyncpg://user:password@localhost/crypto_trader_dev
```
### SQLite (Internal)
Used internally for unit tests (in-memory) only. No setup required.
## Redis Setup
Redis is required for distributed state management and Celery background tasks (e.g., ML model retraining).
```bash
# Install Redis (Ubuntu/Debian)
sudo apt-get install redis-server
```
**Starting Redis**:
```bash
# Option 1: Using system service (requires sudo)
sudo service redis-server start
# Option 2: Direct daemon mode (for containers/restricted environments)
redis-server --daemonize yes
# Verify
redis-cli ping # Should return PONG
```
> **Note**: In containerized environments (Toolbox, Distrobox, Docker, etc.) where `sudo` is not available, use the direct daemon mode option. If you see "Connection refused" errors when using features like "Retrain Model", Redis is likely not running.
### Default Configuration
Redis defaults to `localhost:6379`. Override in `config.yaml`:
```yaml
redis:
host: "127.0.0.1"
port: 6379
db: 0
```
## Running the Application
### Start All Services (Recommended)
Use the helper script to start all services:
```bash
./scripts/start_all.sh
```
### Start Services Manually
```bash
# 1. Start Redis
# Use sudo if available, otherwise direct daemon mode
sudo service redis-server start # OR: redis-server --daemonize yes
# 2. Start Celery Worker (background tasks)
celery -A src.worker.app worker --loglevel=info &
# 3. Start Backend API
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 &
# 4. Start Frontend
cd frontend && npm run dev
```
### Access Points
- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs
### Verify Redis/Celery Integration
```bash
python scripts/verify_redis.py
```
## Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Run specific test file
pytest tests/unit/core/test_redis.py
# Run Redis/Celery tests
pytest tests/unit/core/test_redis.py tests/unit/worker/test_tasks.py -v
# Run with verbose output
pytest -v
```
## Project Structure
```
crypto_trader/
├── src/ # Backend source code
│ ├── autopilot/ # Intelligent autopilot
│ ├── core/ # Core utilities (config, redis, logging)
│ ├── strategies/ # Trading strategies
│ ├── trading/ # Trading engine
│ └── worker/ # Celery tasks
├── backend/ # FastAPI application
│ ├── api/ # API endpoints
│ └── main.py # Application entry point
├── frontend/ # React frontend
│ ├── src/ # React source
│ └── package.json # Frontend dependencies
├── tests/ # Test suite
├── scripts/ # Utility scripts
│ ├── start_all.sh # Start all services
│ └── verify_redis.py # Verify Redis/Celery
├── docs/ # Documentation
└── requirements.txt # Python dependencies
```
## Common Development Tasks
### Adding a New Celery Task
1. Add task function in `src/worker/tasks.py`
2. Configure task routing in `src/worker/app.py` (optional)
3. Create API endpoint in `backend/api/`
4. Write unit tests in `tests/unit/worker/`
### Adding a New API Endpoint
1. Create/update router in `backend/api/`
2. Register router in `backend/main.py`
3. Add frontend API client in `frontend/src/api/`
4. Write tests
### Running Documentation
```bash
cd docs/api
make html
# Open build/html/index.html
```
### Building AppImage
```bash
./packaging/build_appimage.sh
```
## Debugging
### Enable Debug Logging
Set in `config.yaml`:
```yaml
logging:
level: DEBUG
```
### Using Debugger
```bash
# VS Code: Set breakpoints and use debugger
# PyCharm: Configure debug configuration
# Command line: Use pdb
python -m pdb -c continue backend/main.py
```
### Checking Celery Tasks
```bash
# Monitor tasks
celery -A src.worker.app events
# Inspect active tasks
celery -A src.worker.app inspect active
```
## Troubleshooting
**Import errors?**
- Verify virtual environment is activated
- Check PYTHONPATH
- Reinstall dependencies
**Redis connection failed / "Connection refused" error?**
- Ensure Redis is running: `redis-cli ping` (should return `PONG`)
- Start Redis if not running:
- With sudo: `sudo service redis-server start`
- Without sudo: `redis-server --daemonize yes`
- Check host/port configuration in `config.yaml`
- Verify firewall rules
**Celery tasks not executing?**
- Ensure worker is running: `ps aux | grep celery`
- Check worker logs: `tail -f celery.log`
- Verify Redis is accessible
**Tests failing?**
- Check test database setup
- Verify test fixtures
- Review test logs
**Frontend not connecting?**
- Check API is running on port 8000
- Verify CORS settings in backend
- Check browser console for errors

421
docs/developer/testing.md Normal file
View File

@@ -0,0 +1,421 @@
# Testing Guide
This guide covers testing practices for Crypto Trader, including backend API testing, integration testing, and end-to-end testing.
## Test Structure
Tests are organized to mirror the source code structure:
```
tests/
├── unit/ # Unit tests
│ ├── backend/ # Backend API tests
│ ├── core/ # Core module tests
│ └── ...
├── integration/ # Integration tests
├── e2e/ # End-to-end tests
├── fixtures/ # Test fixtures
├── utils/ # Test utilities
└── performance/ # Performance benchmarks
```
## Running Tests
### All Tests
```bash
pytest
```
### With Coverage
```bash
pytest --cov=src --cov-report=html
```
### Specific Test File
```bash
pytest tests/unit/core/test_config.py
```
### Specific Test
```bash
pytest tests/unit/core/test_config.py::test_config_loading
```
### Verbose Output
```bash
pytest -v
```
### Test Categories
```bash
# Unit tests only
pytest -m unit
# Integration tests only
pytest -m integration
# End-to-end tests only
pytest -m e2e
```
## Writing Tests
### Unit Tests
Test individual functions and classes in isolation:
```python
import pytest
from unittest.mock import Mock, patch
from src.core.config import get_config
class TestConfig:
"""Tests for configuration system."""
def test_config_loading(self):
"""Test configuration loading."""
config = get_config()
assert config is not None
assert config.config_dir is not None
```
### Backend API Tests
Test FastAPI endpoints using TestClient:
```python
from fastapi.testclient import TestClient
from backend.main import app
client = TestClient(app)
def test_get_orders():
"""Test getting orders endpoint."""
response = client.get("/api/trading/orders")
assert response.status_code == 200
data = response.json()
assert isinstance(data, list)
def test_place_order():
"""Test placing an order."""
order_data = {
"exchange_id": 1,
"symbol": "BTC/USD",
"side": "buy",
"type": "market",
"quantity": 0.1,
"paper_trading": True
}
response = client.post("/api/trading/orders", json=order_data)
assert response.status_code == 201
data = response.json()
assert data["symbol"] == "BTC/USD"
```
### Integration Tests
Test component interactions:
```python
import pytest
from fastapi.testclient import TestClient
from backend.main import app
@pytest.mark.integration
def test_trading_workflow(client: TestClient):
"""Test complete trading workflow."""
# Place order
order_response = client.post("/api/trading/orders", json={...})
assert order_response.status_code == 201
order_id = order_response.json()["id"]
# Check order status
status_response = client.get(f"/api/trading/orders/{order_id}")
assert status_response.status_code == 200
# Check portfolio update
portfolio_response = client.get("/api/portfolio/current")
assert portfolio_response.status_code == 200
```
### End-to-End Tests
Test complete user workflows:
```python
@pytest.mark.e2e
async def test_paper_trading_scenario():
"""Test complete paper trading scenario."""
# Test full application flow through API
pass
```
## Test Fixtures
Use fixtures for common setup:
```python
import pytest
from fastapi.testclient import TestClient
from backend.main import app
from src.core.database import get_database
@pytest.fixture
def client():
"""Test client fixture."""
return TestClient(app)
@pytest.fixture
def mock_exchange():
"""Mock exchange adapter."""
exchange = Mock()
exchange.fetch_balance.return_value = {'USD': {'free': 1000}}
return exchange
@pytest.fixture
def test_db():
"""Test database fixture."""
# Use in-memory SQLite for unit tests (fast, isolated)
# Note: Requires aiosqlite installed as test dependency
db = get_database()
# Setup test data
yield db
# Cleanup
```
## Mocking
### Mocking External APIs
```python
from unittest.mock import patch, AsyncMock
@patch('src.exchanges.coinbase.ccxt')
async def test_coinbase_connection(mock_ccxt):
"""Test Coinbase connection."""
mock_exchange = AsyncMock()
mock_ccxt.coinbaseadvanced.return_value = mock_exchange
mock_exchange.load_markets = AsyncMock()
adapter = CoinbaseExchange(...)
await adapter.connect()
assert adapter.is_connected
```
### Mocking Database
```python
@pytest.fixture
def test_db():
"""Create test database."""
# Use in-memory SQLite for unit tests (internal use only)
from src.core.database import Database
db = Database("sqlite:///:memory:")
db.create_tables()
return db
```
### Mocking Services
```python
@pytest.fixture
def mock_trading_engine():
"""Mock trading engine."""
engine = Mock()
engine.execute_order.return_value = MockOrder(id=1, status="filled")
return engine
def test_place_order_endpoint(mock_trading_engine):
"""Test order placement with mocked engine."""
with patch('backend.api.trading.get_trading_engine', return_value=mock_trading_engine):
response = client.post("/api/trading/orders", json={...})
assert response.status_code == 201
```
## Async Testing
Use `pytest-asyncio` for async tests:
```python
import pytest
@pytest.mark.asyncio
async def test_async_function():
"""Test async function."""
result = await my_async_function()
assert result is not None
```
## WebSocket Testing
Test WebSocket endpoints:
```python
from fastapi.testclient import TestClient
def test_websocket_connection(client: TestClient):
"""Test WebSocket connection."""
with client.websocket_connect("/ws/") as websocket:
# Send message
websocket.send_json({"type": "subscribe", "channel": "prices"})
# Receive message
data = websocket.receive_json()
assert data["type"] == "price_update"
```
## Test Coverage
Target 95% code coverage:
```bash
# Generate coverage report
pytest --cov=src --cov-report=html
# View in browser
open htmlcov/index.html
```
### Coverage Configuration
Configure in `pytest.ini`:
```ini
[pytest]
cov = src
cov-report = term-missing
cov-report = html
cov-fail-under = 95
```
## Frontend Testing
The frontend uses React Testing Library and Vitest for testing. See [Frontend Testing Guide](./frontend_testing.md) for detailed information.
### Quick Start
```bash
cd frontend
npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event vitest jsdom
npm test
```
### Component Testing
```typescript
import { render, screen, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { describe, it, expect, vi } from 'vitest';
import StrategiesPage from '../pages/StrategiesPage';
import * as strategiesApi from '../api/strategies';
vi.mock('../api/strategies');
describe('StrategiesPage', () => {
it('renders and displays strategies', async () => {
const mockStrategies = [{ id: 1, name: 'Test Strategy', ... }];
vi.mocked(strategiesApi.strategiesApi.listStrategies).mockResolvedValue(mockStrategies);
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
render(
<QueryClientProvider client={queryClient}>
<StrategiesPage />
</QueryClientProvider>
);
await waitFor(() => {
expect(screen.getByText('Test Strategy')).toBeInTheDocument();
});
});
});
```
### Testing New Components
All new components should have corresponding test files:
- `StrategiesPage` → `StrategiesPage.test.tsx`
- `TradingPage` → `TradingPage.test.tsx`
- `StrategyDialog` → `StrategyDialog.test.tsx`
- `OrderForm` → `OrderForm.test.tsx`
- And all other new components
See [Frontend Testing Guide](./frontend_testing.md) for comprehensive testing patterns.
## Best Practices
1. **Test Independence**: Tests should not depend on each other
2. **Fast Tests**: Unit tests should run quickly (< 1 second each)
3. **Clear Names**: Test names should describe what they test
4. **One Assertion**: Prefer one assertion per test when possible
5. **Mock External**: Mock external dependencies (APIs, databases)
6. **Test Edge Cases**: Test boundary conditions and errors
7. **Documentation**: Document complex test scenarios
8. **Arrange-Act-Assert**: Structure tests clearly
9. **Use Fixtures**: Reuse common setup code
10. **Isolation**: Each test should be able to run independently
## Test Organization
### Unit Tests
- Test single function/class
- Mock external dependencies
- Fast execution
- High coverage
### Integration Tests
- Test component interactions
- Use test database
- Test real workflows
- Moderate speed
### E2E Tests
- Test complete user flows
- Use test environment
- Slow execution
- Critical paths only
## Continuous Integration
Tests run automatically in CI/CD:
- All tests must pass
- Coverage must meet threshold (95%)
- Code style must pass
- Type checking must pass (if using mypy)
## Debugging Tests
### Verbose Output
```bash
pytest -vv # Very verbose
pytest -s # Show print statements
```
### Debugging Failed Tests
```bash
# Drop into debugger on failure
pytest --pdb
# Drop into debugger on first failure
pytest -x --pdb
```
### Running Last Failed Tests
```bash
pytest --lf # Last failed
pytest --ff # Failed first
```

346
docs/developer/ui_development.md Normal file
View File

@@ -0,0 +1,346 @@
# Frontend Development Guide
This guide explains how to develop and extend frontend components in Crypto Trader.
## Tech Stack
- **React 18** - UI framework
- **TypeScript** - Type safety
- **Material-UI (MUI)** - Component library
- **React Query** - Data fetching and caching
- **React Router** - Routing
- **Vite** - Build tool
## Project Structure
```
frontend/
├── src/
│ ├── pages/ # Page components
│ ├── components/ # Reusable components
│ ├── api/ # API client functions
│ ├── hooks/ # Custom React hooks
│ ├── types/ # TypeScript types
│ └── App.tsx # Main app component
├── public/ # Static assets
└── package.json # Dependencies
```
## Development Setup
```bash
cd frontend
npm install
npm run dev
```
Access at: http://localhost:3000
## Creating a New Page
1. Create page component in `src/pages/`:
```typescript
// src/pages/MyPage.tsx
import { Box, Typography } from '@mui/material';
export function MyPage() {
return (
<Box>
<Typography variant="h4">My Page</Typography>
</Box>
);
}
```
2. Add route in `src/App.tsx`:
```typescript
import { MyPage } from './pages/MyPage';
<Route path="/my-page" element={<MyPage />} />
```
## API Integration
### Creating API Functions
```typescript
// src/api/myService.ts
import { apiClient } from './client';
export const myServiceApi = {
async getData() {
const response = await apiClient.get('/api/my-service/data');
return response.data;
},
async createItem(data: CreateItemDto) {
const response = await apiClient.post('/api/my-service/items', data);
return response.data;
}
};
```
### Using React Query
```typescript
import { useQuery, useMutation } from '@tanstack/react-query';
import { myServiceApi } from '@/api/myService';
function MyComponent() {
// Fetch data
const { data, isLoading, error } = useQuery({
queryKey: ['myData'],
queryFn: myServiceApi.getData
});
// Mutate data
const mutation = useMutation({
mutationFn: myServiceApi.createItem,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['myData'] });
}
});
return (
<div>
{isLoading && <Loading />}
{data && <DataDisplay data={data} />}
<button onClick={() => mutation.mutate(formData)}>Create</button>
</div>
);
}
```
## Creating Reusable Components
```typescript
// src/components/DataTable.tsx
import { Table, TableBody, TableCell, TableHead, TableRow } from '@mui/material';
interface DataTableProps<T> {
data: T[];
columns: Column<T>[];
}
export function DataTable<T>({ data, columns }: DataTableProps<T>) {
return (
<Table>
<TableHead>
<TableRow>
{columns.map(col => (
<TableCell key={col.key}>{col.header}</TableCell>
))}
</TableRow>
</TableHead>
<TableBody>
{data.map((row, idx) => (
<TableRow key={idx}>
{columns.map(col => (
<TableCell key={col.key}>{col.render(row)}</TableCell>
))}
</TableRow>
))}
</TableBody>
</Table>
);
}
```
## Custom Hooks
```typescript
// src/hooks/useOrders.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { tradingApi } from '@/api/trading';
export function useOrders() {
const { data: orders, isLoading, error } = useQuery({
queryKey: ['orders'],
queryFn: () => tradingApi.getOrders()
});
const placeOrder = useMutation({
mutationFn: tradingApi.placeOrder,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['orders'] });
}
});
return {
orders: orders ?? [],
isLoading,
error,
placeOrder: placeOrder.mutate
};
}
```
## WebSocket Integration
The application uses an enhanced WebSocket system with message type handling:
```typescript
// Using the WebSocket context
import { useWebSocketContext } from '@/components/WebSocketProvider';
import { useRealtimeData } from '@/hooks/useRealtimeData';
function MyComponent() {
const { isConnected, lastMessage, subscribe } = useWebSocketContext();
// Subscribe to specific message types
useEffect(() => {
const unsubscribe = subscribe('order_update', (message) => {
// Handle order update
console.log('Order updated:', message);
});
return unsubscribe;
}, [subscribe]);
// Or use the real-time data hook for automatic query invalidation
useRealtimeData(); // Automatically handles common message types
}
```
### Message Types
The WebSocket supports these message types:
- `order_update`: Order status changes
- `position_update`: Position changes
- `price_update`: Price updates
- `alert_triggered`: Alert notifications
- `strategy_signal`: Strategy signal notifications
- `system_event`: System events and errors
## Form Handling
```typescript
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
const schema = yup.object({
symbol: yup.string().required(),
quantity: yup.number().positive().required()
});
function OrderForm() {
const { register, handleSubmit, formState: { errors } } = useForm({
resolver: yupResolver(schema)
});
const onSubmit = async (data) => {
await tradingApi.placeOrder(data);
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<TextField
{...register('symbol')}
error={!!errors.symbol}
helperText={errors.symbol?.message}
/>
<Button type="submit">Place Order</Button>
</form>
);
}
```
## Error Handling
The application uses a centralized Snackbar context for error handling:
```typescript
import { useSnackbar } from '@/contexts/SnackbarContext';
import ErrorDisplay from '@/components/ErrorDisplay';
function MyComponent() {
const { showError, showSuccess, showWarning, showInfo } = useSnackbar();
const handleAction = async () => {
try {
await apiCall();
showSuccess('Action completed successfully');
} catch (err) {
showError(err instanceof Error ? err.message : 'An error occurred');
}
};
// For complex error display with retry
return (
<>
{error && (
<ErrorDisplay
error={error}
title="Operation Failed"
onRetry={handleAction}
/>
)}
</>
);
}
```
### Available Components
- `ErrorDisplay`: Enhanced error display with retry functionality
- `LoadingSkeleton`: Loading placeholders for tables, cards, lists
- `ProgressOverlay`: Overlay with progress indicator
- `StatusIndicator`: Connection status indicators
- `DataFreshness`: Data freshness timestamps
- `HelpTooltip`: Contextual help tooltips
- `InfoCard`: Collapsible information cards
- `OperationsPanel`: Panel showing running operations
## Styling
### Material-UI Theming
```typescript
// src/theme.ts
import { createTheme } from '@mui/material/styles';
export const theme = createTheme({
palette: {
mode: 'dark',
primary: {
main: '#1976d2'
}
}
});
```
### Component Styling
Use Material-UI's `sx` prop for inline styles:
```typescript
<Box
sx={{
padding: 2,
backgroundColor: 'background.paper',
borderRadius: 1
}}
>
Content
</Box>
```
## Testing
See [Testing Guide](./testing.md) for frontend testing strategies.
## Best Practices
1. **Type Safety**: Always use TypeScript types
2. **Component Composition**: Prefer composition over inheritance
3. **Custom Hooks**: Extract reusable logic into hooks
4. **Error Handling**: Handle errors gracefully with user feedback
5. **Loading States**: Always show loading indicators
6. **Accessibility**: Use semantic HTML and ARIA labels
7. **Performance**: Use React.memo, useMemo, useCallback appropriately
8. **Code Splitting**: Use lazy loading for large components
9. **Form Validation**: Validate on both client and server
10. **Consistent Patterns**: Follow established patterns in the codebase

156
docs/frontend_changes_summary.md Normal file
View File

@@ -0,0 +1,156 @@
# Frontend UI Enhancement Summary
This document summarizes the comprehensive frontend enhancements completed to ensure all documented features are accessible in the UI and improve UX transparency.
## New Pages Added
### 1. Strategy Management Page (`/strategies`)
- Full CRUD operations for strategies
- Create, edit, delete strategies
- Start/stop strategy controls
- Parameter configuration UI for all strategy types (RSI, MACD, Moving Average, Confirmed, Divergence, Bollinger, Consensus, DCA, Grid, Momentum)
- Strategy status indicators
- Performance metrics display
### 2. Manual Trading Page (`/trading`)
- Order placement form with all order types (Market, Limit, Stop Loss, Take Profit, Trailing Stop, OCO, Iceberg)
- Active orders table with cancel functionality
- Order history with filters
- Position management with close position functionality
- Real-time order and position updates
## Enhanced Existing Pages
### Dashboard
- System health indicators (WebSocket, Database, Exchange connections)
- Operations panel showing running operations
- Data freshness indicators
- Enhanced error handling with retry options
- Loading states for all async operations
- Real-time status updates
### Portfolio
- Position closing interface
- Portfolio allocation pie charts
- Data freshness indicators
- Enhanced export functionality with success/error feedback
- Card-based position view with detailed P&L
### Backtesting
- Progress overlay for long-running backtests
- Operations panel integration
- Enhanced error messages
- Info card about parameter optimization (requires backend API)
### Settings
- Alert history view showing triggered alerts
- Enhanced exchange management with status indicators
- Better connection testing with detailed feedback
- Improved error handling throughout
## New Components Created
### UX Components
- `LoadingSkeleton` - Loading placeholders for tables, cards, lists
- `ProgressOverlay` - Overlay with progress indicator for long operations
- `ErrorDisplay` - Enhanced error display with retry functionality
- `StatusIndicator` - Connection status indicators
- `SystemHealth` - System health dashboard widget
- `DataFreshness` - Timestamp indicators showing data age
- `HelpTooltip` - Contextual help tooltips
- `InfoCard` - Collapsible information cards
- `OperationsPanel` - Panel showing running operations and progress
### Feature Components
- `StrategyDialog` - Create/edit strategy dialog with tabs
- `StrategyParameterForm` - Dynamic parameter forms for each strategy type
- `OrderForm` - Order placement form with all order types
- `PositionCard` - Position display card with close functionality
- `AlertHistory` - Alert history table component
## Infrastructure Improvements
### Error Handling
- Replaced all `alert()` calls with Snackbar notifications
- Created `SnackbarContext` for global error/success messaging
- Added error boundaries with recovery options
- Inline validation errors in forms
### Real-time Updates
- Enhanced WebSocket hook with message type handling
- Created `useRealtimeData` hook for automatic query invalidation
- Message subscription system for different event types
- Real-time updates for orders, positions, prices, alerts, strategy signals
### State Management
- Better loading states throughout
- Progress indicators for long operations
- Data freshness tracking
- Operation visibility
## Navigation Updates
- Added "Strategies" menu item
- Added "Trading" menu item
- Improved navigation organization
## Testing Notes
The following areas should be tested:
1. **Strategy Management**
- Create/edit/delete strategies
- Start/stop strategies
- Parameter validation
- Strategy type switching
2. **Trading**
- Order placement (all order types)
- Order cancellation
- Position closing
- Real-time updates
3. **Real-time Features**
- WebSocket connection/reconnection
- Message handling
- Query invalidation on updates
4. **Error Handling**
- Network errors
- Validation errors
- Backend errors
- Retry functionality
5. **Loading States**
- Skeleton loaders
- Progress overlays
- Button disabled states
## Documentation Updates Needed
1. **User Manual Updates**
- Add Strategy Management section
- Add Manual Trading section
- Update Dashboard documentation
- Update Portfolio documentation with new features
- Update Settings documentation with alert history
2. **API Documentation**
- Document WebSocket message types
- Document new endpoints if any
- Update response schemas
3. **Developer Documentation**
- Component architecture
- State management patterns
- WebSocket integration guide
- Error handling patterns
## Known Limitations
1. **Parameter Optimization**: UI structure is in place, but requires backend API endpoints for optimization methods (Grid Search, Genetic Algorithm, Bayesian Optimization)
2. **Advanced Order Types**: OCO and Iceberg orders have UI support but may need backend implementation verification
3. **Exchange Status**: Exchange connection status is displayed but may need backend health check endpoints for accurate status

192
docs/guides/pairs_trading_setup.md Normal file
View File

@@ -0,0 +1,192 @@
# Pairs Trading Strategy - Configuration Guide
This guide walks you through configuring and enabling the Statistical Arbitrage (Pairs Trading) strategy in your crypto trading application.
## Overview
Pairs Trading is a market-neutral strategy that profits from the relative price movements between two correlated assets. When the spread between two assets diverges beyond a statistical threshold (Z-Score), the strategy generates signals to trade the reversion.
---
## Step 1: Navigate to Strategy Management
1. Open your application in the browser (typically `http://localhost:5173`)
2. Click on **"Strategies"** in the navigation menu
3. You'll see the Strategy Management page
---
## Step 2: Create a New Strategy
1. Click the **"Create Strategy"** button in the top-right corner
2. The Strategy Dialog will open
---
## Step 3: Configure Basic Settings
Fill in the following fields:
| Field | Description | Example |
|-------|-------------|---------|
| **Strategy Name** | A descriptive name for your strategy | `SOL-AVAX Pairs Trade` |
| **Strategy Type** | Select from dropdown | `Statistical Arbitrage (Pairs)` |
| **Primary Symbol** | The main asset to trade | `SOL/USD` |
| **Exchange** | Your configured exchange | `Coinbase` or `Binance` |
| **Timeframe** | Candlestick interval | `1h` (recommended) |
---
## Step 4: Configure Pairs Trading Parameters
After selecting "Statistical Arbitrage (Pairs)" as the strategy type, you'll see the parameters section:
### Required Parameters:
| Parameter | Description | Default | Recommended Range |
|-----------|-------------|---------|-------------------|
| **Second Symbol** | The correlated asset to pair with | - | `AVAX/USD`, `ETH/USD`, etc. |
| **Lookback Period** | Rolling window for statistics | `20` | 15-50 |
| **Z-Score Threshold** | Trigger level for signals | `2.0` | 1.5-3.0 |
### Parameter Explanations:
- **Second Symbol**: Choose an asset that moves similarly to your primary symbol. Common pairs include:
- `BTC/USD` ↔ `ETH/USD` (highly correlated)
- `SOL/USD` ↔ `AVAX/USD` (Layer 1s)
- `DOGE/USD` ↔ `SHIB/USD` (meme coins)
- **Lookback Period**: Number of candles used to calculate rolling mean and standard deviation. Higher values = smoother but slower to react.
- **Z-Score Threshold**: How many standard deviations from the mean before triggering:
- `1.5` = More frequent signals, smaller moves
- `2.0` = Balanced (default)
- `2.5-3.0` = Fewer signals, larger moves
---
## Step 5: Additional Settings
| Setting | Description | Recommendation |
|---------|-------------|----------------|
| **Paper Trading** | Enable for testing | ✅ Start with Paper Trading ON |
| **Auto Execute** | Automatically place trades | ❌ Keep OFF initially to observe signals |
---
## Step 6: Save and Enable
1. Click **"Create"** to save the strategy
2. The strategy will appear in your strategy list with status "Disabled"
3. Click the **▶️ Play** button to enable the strategy
---
## Step 7: Monitor the Spread
Once enabled, scroll down on the Strategies page to see the **Pairs Trading Analysis** section:
- **Current Spread**: The ratio of Primary Symbol / Secondary Symbol prices
- **Z-Score**: How many standard deviations the current spread is from its mean
- **Signal State**: Shows if a signal is active (Long Spread, Short Spread, or Neutral)
### Understanding the Charts:
1. **Spread History Chart**: Shows the ratio over time
2. **Z-Score Chart**: Shows statistical deviation with threshold lines
- Green dashed line: Buy threshold (-2.0)
- Red dashed line: Sell threshold (+2.0)
---
## Signal Logic
| Condition | Signal | Action |
|-----------|--------|--------|
| Z-Score > +Threshold | **SELL** | Sell Primary, Buy Secondary |
| Z-Score < -Threshold | **BUY** | Buy Primary, Sell Secondary |
| Z-Score between thresholds | **HOLD** | No action (neutral) |
### Example:
If you're trading `SOL/USD` vs `AVAX/USD`:
- **Z-Score = +2.5**: SOL is overvalued relative to AVAX → Sell SOL, Buy AVAX
- **Z-Score = -2.5**: SOL is undervalued relative to AVAX → Buy SOL, Sell AVAX
---
## Tips for Success
1. **Choose Correlated Pairs**: The strategy works best with assets that historically move together. Check correlation before pairing.
2. **Start with Paper Trading**: Always test with paper trading first to understand signal frequency and behavior.
3. **Consider Timeframe**:
- `1h` is good for daily monitoring
- `4h` for longer-term positions
- `15m` for more active trading (higher risk)
4. **Monitor Volatility**: The strategy performs best in ranging/mean-reverting markets. Trending markets can cause losses.
5. **Adjust Threshold**: If you get too many signals, increase the threshold. Too few? Lower it.
---
## Troubleshooting
| Issue | Solution |
|-------|----------|
| No data appearing | Ensure both symbols are available on your selected exchange |
| Z-Score always near 0 | Try increasing lookback period or verify price data is flowing |
| Too many signals | Increase Z-Score threshold (e.g., 2.5 or 3.0) |
| Strategy not executing | Check if Auto Execute is enabled in Settings |
---
## Example Configuration
```
Name: ETH-SOL Mean Reversion
Type: Statistical Arbitrage (Pairs)
Primary Symbol: ETH/USD
Second Symbol: SOL/USD
Lookback Period: 20
Z-Score Threshold: 2.0
Timeframe: 1h
Paper Trading: ON
```
This configuration would:
1. Monitor the ETH/SOL price ratio
2. Generate a BUY signal when ETH is historically cheap vs SOL (Z-Score < -2)
3. Generate a SELL signal when ETH is historically expensive vs SOL (Z-Score > +2)
---
## How Execution Works
When you click **Start** on a Pairs Trading strategy:
1. **Strategy Scheduler starts** - Runs the strategy on a 60-second interval (configurable)
2. **Each tick**:
- Fetches current prices for both symbols
- Calculates spread ratio and Z-Score
- If Z-Score exceeds threshold → generates signal
3. **Signal execution** (if enabled):
- Executes both legs simultaneously
- Primary symbol: BUY or SELL based on signal
- Secondary symbol: Opposite action
4. **Status updates** visible on Strategies page
---
## Real-Time Status Panel
When strategies are running, you'll see a **green status panel** on the Strategies page showing:
- Strategy name and symbol
- Start time
- Number of signals generated
- Last signal type and price
- Last execution tick time
This updates every 5 seconds automatically.

222
docs/migration_guide.md Normal file
View File

@@ -0,0 +1,222 @@
# Migration Guide: PyQt6 to Web Architecture
This guide explains the migration from PyQt6 desktop application to web-based architecture.
## Overview
The application has been migrated from a PyQt6 desktop app to a modern web-based architecture while preserving 90% of the existing Python backend code.
## What Changed
### Architecture
**Before (PyQt6)**:
```
PyQt6 UI → Direct Python calls → Services → Database
```
**After (Web)**:
```
React UI → HTTP/WebSocket → FastAPI → Services → Database
```
### Code Structure
**Before**:
```
crypto_trader/
├── src/
│ ├── ui/ # PyQt6 widgets
│ ├── trading/ # Trading engine
│ ├── strategies/ # Strategy framework
│ └── ...
└── packaging/ # AppImage build
```
**After**:
```
crypto_trader/
├── backend/ # FastAPI application
│ ├── api/ # API endpoints
│ └── core/ # Dependencies, schemas
├── frontend/ # React application
│ └── src/
│ ├── pages/ # Page components
│ ├── api/ # API client
│ └── ...
├── src/ # Existing Python code (unchanged)
└── docker-compose.yml
```
## What Was Preserved
### 100% Preserved (No Changes)
- `src/trading/engine.py` - Trading engine
- `src/strategies/` - Strategy framework
- `src/portfolio/` - Portfolio tracker
- `src/backtesting/` - Backtesting engine
- `src/risk/` - Risk management
- `src/data/` - Data collection
- `src/exchanges/` - Exchange integrations
- `src/core/database.py` - Database models
- All business logic
### What Was Replaced
- **UI Layer**: PyQt6 widgets → React components
- **Communication**: Direct function calls → HTTP API
- **Real-time Updates**: Signal/slot → WebSocket
- **Deployment**: AppImage → Docker
## Migration Steps
### 1. API Layer Creation
Created FastAPI application that wraps existing services:
```python
# backend/api/trading.py
@router.post("/orders")
async def create_order(order_data: OrderCreate):
# Uses existing trading_engine.execute_order()
order = trading_engine.execute_order(...)
return OrderResponse.from_orm(order)
```
### 2. Frontend Development
Created React frontend with:
- Material-UI for modern components
- React Query for data fetching
- TypeScript for type safety
- WebSocket for real-time updates
### 3. Docker Deployment
Created Docker setup for easy deployment:
- Multi-stage build (frontend + backend)
- Single container deployment
- Volume mounts for data persistence
## Running the New Architecture
### Development
1. **Backend**:
```bash
cd backend
python -m uvicorn main:app --reload
```
2. **Frontend**:
```bash
cd frontend
npm install
npm run dev
```
### Production
```bash
docker-compose up --build
```
Access at: http://localhost:8000
## API Endpoints
All functionality is now available via REST API:
- **Trading**: `/api/trading/*`
- **Portfolio**: `/api/portfolio/*`
- **Strategies**: `/api/strategies/*`
- **Backtesting**: `/api/backtesting/*`
- **WebSocket**: `/ws/` for real-time updates
See API documentation at: http://localhost:8000/docs
## Key Differences
### UI Development
**Before (PyQt6)**:
```python
# Complex QSS styling
self.setStyleSheet("""
QPushButton {
background-color: #1E1E1E;
...
}
""")
```
**After (React)**:
```tsx
// Modern CSS-in-JS
<Button variant="contained" color="primary">
Place Order
</Button>
```
### Data Fetching
**Before (PyQt6)**:
```python
# Direct function calls
order = trading_engine.execute_order(...)
```
**After (React)**:
```tsx
// API calls with React Query
const { data } = useQuery({
queryKey: ['orders'],
queryFn: () => tradingApi.getOrders()
})
```
### Real-time Updates
**Before (PyQt6)**:
```python
# Signal/slot connections
collector.signals.price_updated.connect(self._on_price_update)
```
**After (React)**:
```tsx
// WebSocket hook
const { lastMessage } = useWebSocket('ws://localhost:8000/ws/')
```
## Benefits
1. **Modern UI**: Access to entire web ecosystem
2. **Cross-platform**: Works on any device
3. **Easier deployment**: Docker vs AppImage
4. **Better development**: Hot-reload, better tooling
5. **Maintainability**: Easier to update
6. **Accessibility**: Access from anywhere
## Backward Compatibility
The existing Python code remains unchanged. You can still:
- Import and use services directly
- Run existing tests
- Use the code in other projects
## Next Steps
1. Add authentication (JWT)
2. Enhance WebSocket integration
3. Add more charting features
4. Improve mobile responsiveness
5. Add more strategy management features
## Support
For issues or questions:
- Check API docs: http://localhost:8000/docs
- Review deployment guide: `docs/deployment/web_architecture.md`
- Check backend logs: `docker-compose logs`

5
docs/requirements.txt Normal file
View File

@@ -0,0 +1,5 @@
sphinx>=7.0.0
sphinx-rtd-theme>=1.3.0
sphinx-autodoc-typehints>=1.24.0
sphinxcontrib-napoleon>=0.7

182
docs/user_manual/ALGORITHM_IMPROVEMENTS.md Normal file
View File

@@ -0,0 +1,182 @@
# Algorithm Improvements and New Features
This document describes the recent algorithm improvements implemented to improve trading success rates.
## Overview
Several advanced algorithms and strategies have been added to improve trade success rates and reduce false signals. These improvements leverage multi-indicator confirmation, divergence detection, ensemble methods, and advanced risk management.
## New Strategies
### 1. Confirmed Strategy (Multi-Indicator Confirmation)
**Purpose**: Reduce false signals by requiring multiple indicators to agree before generating a trade signal.
**How It Works**:
- Combines signals from RSI, MACD, and Moving Average indicators
- Only generates signals when a configurable number of indicators agree (default: 2)
- Calculates signal strength based on the level of agreement
**Benefits**:
- 20-30% reduction in false signals
- Higher confidence trades
- Better win rate through confirmation
**When to Use**:
- When you want to reduce false signals
- For more conservative trading approach
- In markets where single indicators are unreliable
### 2. Divergence Strategy
**Purpose**: Identify potential trend reversals by detecting divergences between price and indicators.
**How It Works**:
- Detects bullish divergence: Price makes lower low, indicator makes higher low → BUY signal
- Detects bearish divergence: Price makes higher high, indicator makes lower high → SELL signal
- Works with RSI or MACD indicators
**Benefits**:
- 15-25% improvement in entry timing
- Excellent for ranging markets
- Identifies reversal points before they happen
**When to Use**:
- In ranging/consolidating markets
- For identifying trend reversals
- When looking for contrarian signals
### 3. Bollinger Bands Mean Reversion
**Purpose**: Trade mean reversion in ranging markets using Bollinger Bands.
**How It Works**:
- Buys when price touches lower band in uptrend
- Sells at middle band for profit-taking
- Includes trend filter to avoid counter-trend trades
**Benefits**:
- Works well in ranging markets
- Clear entry and exit signals
- Risk-controlled through trend filter
**When to Use**:
- In ranging/consolidating markets
- For mean reversion trading
- When volatility is moderate
### 4. Consensus Strategy (Ensemble)
**Purpose**: Combine signals from multiple strategies using weighted voting to improve overall performance.
**How It Works**:
- Aggregates signals from multiple registered strategies
- Uses performance-based weighting (better performing strategies have more weight)
- Only executes when minimum number of strategies agree
**Benefits**:
- 15-20% overall improvement through consensus
- Dynamic weighting based on recent performance
- Reduces reliance on single strategy
**When to Use**:
- When you want to combine multiple strategies
- For more robust signal generation
- When trading with multiple indicators/approaches
## Enhanced Risk Management
### ATR-Based Dynamic Stop Loss
**Purpose**: Improve stop loss placement by adapting to market volatility.
**How It Works**:
- Calculates stop distance based on Average True Range (ATR)
- Stops automatically adjust to market volatility
- Tighter stops in low volatility, wider in high volatility
- Works with both fixed and trailing stops
**Benefits**:
- 10-15% better risk-adjusted returns
- Fewer stop-outs during normal market noise
- Better adaptation to market conditions
**Usage**:
```python
# Set ATR-based stop loss
risk_manager.update_stop_loss(
position_id=1,
stop_price=entry_price,
use_atr=True,
atr_multiplier=Decimal('2.0'), # Stop distance = 2 × ATR
atr_period=14,
ohlcv_data=market_data,
trailing=True # Enable trailing stop
)
```
## Advanced Features
### Trend Filtering
All strategies can now use optional ADX-based trend filtering:
- Filters out signals when ADX < threshold (weak trend/chop)
- Only allows BUY signals in uptrends, SELL in downtrends
- Reduces trades in choppy/ranging markets
**Enable in Strategy Parameters**:
- Set `use_trend_filter: true` in strategy parameters
- Configure `min_adx` threshold (default: 25.0)
## Expected Improvements
When all improvements are implemented and properly configured:
- **Overall Win Rate**: 30-40% improvement
- **False Signals**: 20-30% reduction
- **Risk-Adjusted Returns**: 10-15% improvement
- **Entry Timing**: 15-25% improvement
## Best Practices
1. **Start with Paper Trading**: Always test new strategies in paper trading mode first
2. **Combine Strategies**: Use Consensus Strategy to combine multiple approaches
3. **Use ATR Stops**: Enable ATR-based stops for better risk management
4. **Enable Trend Filters**: Use trend filtering in choppy markets
5. **Backtest Thoroughly**: Backtest all strategies before live trading
6. **Monitor Performance**: Regularly review strategy performance and adjust parameters
7. **Gradual Implementation**: Add new strategies gradually and monitor their impact
## Migration Guide
### Updating Existing Strategies
Existing strategies can benefit from new features:
1. **Add Trend Filtering**:
- Add `use_trend_filter: true` to strategy parameters
- Signals will be automatically filtered
2. **Upgrade to ATR Stops**:
- Update stop loss settings to use `use_atr: true`
- Provide OHLCV data for ATR calculation
3. **Combine with Consensus**:
- Create a Consensus Strategy
- Include your existing strategies
- Benefit from ensemble methods
## Technical Details
For technical implementation details, see:
- [Strategy Framework Architecture](../architecture/strategy_framework.md)
- [Risk Management Architecture](../architecture/risk_management.md)
- [Creating Custom Strategies](../developer/creating_strategies.md)

23
docs/user_manual/README.md Normal file
View File

@@ -0,0 +1,23 @@
# Crypto Trader User Manual
Welcome to the Crypto Trader user manual. This guide will help you get started with the application and use all its features effectively.
## Table of Contents
1. [Getting Started](getting_started.md) - Installation and first steps
2. [Configuration](configuration.md) - Setting up the application
3. [Trading](trading.md) - How to trade cryptocurrencies
4. [Strategies](strategies.md) - Creating and managing trading strategies
5. [Backtesting](backtesting.md) - Testing strategies on historical data
6. [Portfolio](portfolio.md) - Managing your portfolio
7. [Alerts](alerts.md) - Setting up price and indicator alerts
8. [Reporting](reporting.md) - Exporting data and generating reports
9. [Troubleshooting](troubleshooting.md) - Common issues and solutions
10. [FAQ](faq.md) - Frequently asked questions
## Quick Links
- [Installation Guide](getting_started.md#installation)
- [First Trade](trading.md#placing-your-first-trade)
- [Creating a Strategy](strategies.md#creating-a-strategy)
- [Running a Backtest](backtesting.md#running-a-backtest)

141
docs/user_manual/alerts.md Normal file
View File

@@ -0,0 +1,141 @@
# Alerts Guide
Set up alerts for price movements, indicators, and system events.
## Alert Types
### Price Alerts
Get notified when prices reach specific levels:
- **Price Above**: Alert when price exceeds threshold
- **Price Below**: Alert when price drops below threshold
- **Price Change**: Alert on percentage change
### Indicator Alerts
Alert on technical indicator conditions:
- **RSI**: Overbought/oversold conditions
- **MACD**: Crossover signals
- **Moving Average**: Price crosses moving average
- **Bollinger Bands**: Price touches bands
### Risk Alerts
Get notified about risk conditions:
- **Drawdown**: Portfolio drawdown exceeds limit
- **Daily Loss**: Daily loss exceeds threshold
- **Position Size**: Position exceeds limit
- **Margin**: Margin level warnings
### System Alerts
System and application alerts:
- **Connection Lost**: Exchange connection issues
- **Order Filled**: Trade execution notifications
- **Error**: Application errors
- **Update Available**: New version available
## Creating Alerts
1. Navigate to Alerts view
2. Click "Create Alert"
3. Select alert type
4. Configure conditions:
- **Symbol**: Trading pair
- **Condition**: Alert trigger condition
- **Value**: Threshold value
5. Choose notification method:
- **Desktop**: System notification
- **Sound**: Audio alert
- **Email**: Email notification (if configured)
6. Set alert name
7. Click "Save"
## Alert Examples
### Price Alert Example
**Alert**: BTC Price Above $50,000
- **Type**: Price Alert
- **Symbol**: BTC/USD
- **Condition**: Price Above
- **Value**: 50000
- **Notification**: Desktop + Sound
### RSI Alert Example
**Alert**: BTC RSI Oversold
- **Type**: Indicator Alert
- **Symbol**: BTC/USD
- **Indicator**: RSI
- **Condition**: RSI Below
- **Value**: 30
- **Timeframe**: 1h
### Risk Alert Example
**Alert**: Portfolio Drawdown Warning
- **Type**: Risk Alert
- **Condition**: Drawdown Exceeds
- **Value**: 10%
- **Notification**: Desktop + Email
## Managing Alerts
### Enabling/Disabling
- Toggle alerts on/off without deleting
- Disabled alerts don't trigger
- Useful for temporary disabling
### Editing Alerts
1. Select the alert
2. Click "Edit"
3. Modify conditions
4. Save changes
### Deleting Alerts
1. Select the alert
2. Click "Delete"
3. Confirm deletion
## Alert History
View all triggered alerts in the Alert History tab:
1. Navigate to **Settings** page
2. Click on **Alert History** tab
3. View the table showing:
- **Alert Name**: Name of the alert
- **Type**: Alert type (price, indicator, risk, system)
- **Condition**: The condition that triggered (e.g., "BTC/USD @ $50000")
- **Triggered At**: Timestamp when the alert fired
- **Status**: Whether the alert is currently enabled or disabled
The alert history automatically refreshes every 5 seconds to show newly triggered alerts. Only alerts that have been triggered at least once appear in this view.
## Notification Settings
Configure notification preferences:
1. Navigate to Settings > Notifications
2. Configure:
- **Desktop Notifications**: Enable/disable
- **Sound Alerts**: Enable/disable
- **Email Notifications**: Configure email settings
3. Test notifications
## Best Practices
1. **Set Meaningful Thresholds**: Avoid too many alerts
2. **Use Multiple Channels**: Desktop + sound for important alerts
3. **Review Regularly**: Clean up unused alerts
4. **Test Alerts**: Verify alerts work correctly
5. **Monitor Alert History**: Track what triggered

217
docs/user_manual/backtesting.md Normal file
View File

@@ -0,0 +1,217 @@
# Backtesting Guide
This guide explains how to use the backtesting feature to evaluate trading strategies on historical data.
## Running a Backtest
1. Navigate to the **Backtesting** page
2. Configure your backtest in the form:
- **Strategy**: Select a strategy from the dropdown (required)
- **Symbol**: Trading pair to test (e.g., BTC/USD)
- **Exchange**: Data source exchange (e.g., coinbase)
- **Timeframe**: Data timeframe (1m, 5m, 15m, 1h, 4h, 1d) - 1h recommended for most strategies
- **Start Date**: Beginning of test period (required)
- **End Date**: End of test period (required)
- **Initial Capital**: Starting capital in USD (default: $100)
- **Slippage (%)**: Expected slippage percentage (default: 0.1%)
- **Fee Rate (%)**: Trading fee percentage (default: 0.1%)
3. Click **Run Backtest**
4. A progress overlay will appear showing the backtest is running
5. An operations panel will show the running backtest with status
6. Wait for completion (you'll receive a success notification)
7. Review results in the **Backtest Results** section below
## Understanding Results
The backtest results include:
- **Total Return**: Overall percentage return
- **Sharpe Ratio**: Risk-adjusted return metric (higher is better)
- **Sortino Ratio**: Downside risk-adjusted return (higher is better)
- **Max Drawdown**: Largest peak-to-trough decline
- **Win Rate**: Percentage of profitable trades
- **Total Trades**: Number of trades executed
- **Final Value**: Portfolio value at end of backtest
## Exporting Results
After a backtest completes, you can export the results:
1. In the backtest results section, find the export buttons
2. **Export CSV**:
- Click **Export CSV** button
- Downloads a CSV file with all trades from the backtest
- File includes: timestamp, side, price, quantity, value
3. **Export PDF**:
- Click **Export PDF** button
- Generates a comprehensive PDF report
- Includes charts, metrics, and trade analysis
Both exports are automatically named with the current date for easy organization.
## Parameter Optimization
Parameter optimization allows you to automatically find the best strategy parameters. This feature requires backend API support and will be available once the optimization endpoints are implemented.
The UI includes an information card explaining this feature. When available, you'll be able to:
- Select parameters to optimize
- Set parameter ranges
- Choose optimization method (Grid Search, Genetic Algorithm, Bayesian Optimization)
- View optimization progress
- Compare optimization results
## Interpreting Metrics
- **Sharpe Ratio > 1**: Good risk-adjusted returns
- **Max Drawdown < 20%**: Acceptable risk level
- **Win Rate > 50%**: More winning than losing trades
# Backtesting Guide
Learn how to test your trading strategies on historical data.
## What is Backtesting?
Backtesting is the process of testing a trading strategy on historical data to evaluate its performance before risking real money.
## Running a Backtest
1. Navigate to Backtest view
2. Select a strategy
3. Configure backtest parameters:
- **Start Date**: Beginning of test period
- **End Date**: End of test period
- **Initial Capital**: Starting capital
- **Symbol**: Trading pair to test
- **Timeframe**: Data timeframe
4. Click "Run Backtest"
5. Wait for completion
6. Review results
## Backtest Parameters
### Time Period
- **Start Date**: When to begin the backtest
- **End Date**: When to end the backtest
- **Duration**: Length of test period
- Longer periods provide more reliable results
### Capital Settings
- **Initial Capital**: Starting amount (e.g., $10,000)
- **Currency**: Base currency (USD, EUR, etc.)
### Market Settings
- **Symbol**: Trading pair (BTC/USD, ETH/USD, etc.)
- **Timeframe**: Data granularity (1m, 5m, 1h, 1d)
- **Exchange**: Historical data source
## Understanding Results
### Performance Metrics
- **Total Return**: Overall profit/loss percentage
- **Final Capital**: Ending portfolio value
- **Sharpe Ratio**: Risk-adjusted return measure
- **Sortino Ratio**: Downside risk-adjusted return
- **Max Drawdown**: Largest peak-to-trough decline
- **Win Rate**: Percentage of profitable trades
### Trade Analysis
- **Total Trades**: Number of trades executed
- **Winning Trades**: Number of profitable trades
- **Losing Trades**: Number of unprofitable trades
- **Average Win**: Average profit per winning trade
- **Average Loss**: Average loss per losing trade
- **Profit Factor**: Ratio of gross profit to gross loss
### Charts
- **Equity Curve**: Portfolio value over time
- **Drawdown Chart**: Drawdown periods
- **Trade Distribution**: Win/loss distribution
- **Monthly Returns**: Performance by month
## Realistic Backtesting
Crypto Trader includes realistic backtesting features:
### Slippage
Slippage simulates the difference between expected and actual execution prices.
- **Default**: 0.1% for market orders
- **Configurable**: Adjust based on market conditions
- **Market Impact**: Larger orders have more slippage
### Fees
Trading fees are automatically included:
- **Maker Fees**: For limit orders (typically 0.1%)
- **Taker Fees**: For market orders (typically 0.2%)
- **Exchange-Specific**: Fees vary by exchange
### Order Execution
- **Market Orders**: Execute at current price + slippage
- **Limit Orders**: Execute only if price reaches limit
- **Partial Fills**: Large orders may fill partially
## Parameter Optimization
Optimize strategy parameters for better performance:
1. Select strategy
2. Choose parameters to optimize
3. Set parameter ranges
4. Select optimization method:
- **Grid Search**: Test all combinations
- **Genetic Algorithm**: Evolutionary optimization
- **Bayesian Optimization**: Efficient parameter search
5. Run optimization
6. Review results and select best parameters
## Best Practices
1. **Use Sufficient Data**: Test on at least 6-12 months of data
2. **Avoid Overfitting**: Don't optimize too aggressively
3. **Test Multiple Periods**: Verify performance across different market conditions
4. **Consider Fees**: Always include realistic fees
5. **Check Slippage**: Account for execution costs
6. **Validate Results**: Compare with paper trading
## Limitations
Backtesting has limitations:
- **Past Performance**: Doesn't guarantee future results
- **Market Conditions**: Markets change over time
- **Data Quality**: Results depend on data accuracy
- **Execution**: Real trading may differ from simulation
## Exporting Results
Export backtest results for analysis:
1. Click "Export Results"
2. Choose format:
- **CSV**: For spreadsheet analysis
- **PDF**: For reports
3. Save file
## Troubleshooting
**No results?**
- Check date range has data
- Verify symbol is correct
- Check strategy parameters
**Unrealistic results?**
- Verify fees are enabled
- Check slippage settings
- Review data quality

359
docs/user_manual/configuration.md Normal file
View File

@@ -0,0 +1,359 @@
# Configuration Guide
This guide explains how to configure Crypto Trader to suit your needs.
## Configuration Files
Configuration files are stored in `~/.config/crypto_trader/` following the XDG Base Directory Specification.
### Main Configuration
The main configuration file is `config.yaml`. It contains:
- Database settings
- Logging configuration
- Paper trading settings
- Update preferences
- Notification settings
- Backtesting defaults
### Logging Configuration
Logging settings are in `logging.yaml`. You can configure:
- Log levels (DEBUG, INFO, WARNING, ERROR)
- Log file location
- Log rotation settings
- Retention policies
## Exchange Configuration
### Adding Exchange API Keys via UI
1. Open the application
2. Navigate to the **Settings** tab
3. In the **Exchanges** section, click **Add Exchange**
4. Enter exchange details:
- **Exchange Name**: Name of the exchange (e.g., Coinbase)
- **API Key**: Your exchange API key
- **API Secret**: Your exchange API secret
- **Use Sandbox/Testnet**: Enable for testing
- **Read-Only Mode**: Recommended for safety (prevents trading)
- **Enabled**: Enable the exchange connection
5. Click **Save**
6. Test the connection using **Test Connection** button
### Editing Exchange Settings
1. Select an exchange from the exchanges table
2. Click **Edit Exchange**
3. Update API keys or settings as needed
4. Click **Save**
### Managing Exchanges
The Settings page provides comprehensive exchange management:
- **Status Indicators**: Each exchange shows a color-coded status indicator:
- Green: Enabled and connected
- Gray: Disabled
- Red: Error state
- **Test Connection**: Click the checkmark icon to test the connection
- You'll receive a notification with detailed connection status
- Success: Green notification
- Warning: Yellow notification with details
- Error: Red notification with error message
- **Edit Exchange**: Click the pencil icon to edit exchange settings
- **Delete Exchange**: Click the trash icon to delete (removes API keys)
- Confirmation dialog will appear
- You'll receive a success notification when deleted
### API Key Security
- API keys are encrypted before storage
- Use read-only keys when possible
- Enable IP whitelisting on your exchange account
- Never share your API keys
## Paper Trading Configuration
Paper trading settings can be configured in the Settings page:
1. Navigate to **Settings** page
2. Click on **Paper Trading** tab
3. Configure:
- **Initial Capital ($)**: Starting capital in USD (default: $100)
- **Fee Model (Exchange)**: Select which exchange's fee structure to simulate
4. Click **Save Settings**
5. You'll receive a success notification when settings are saved
### Fee Exchange Models
Choose from available exchange fee models:
| Exchange | Maker Fee | Taker Fee | Best For |
|----------|-----------|-----------|----------|
| **Default** | 0.10% | 0.10% | General testing |
| **Coinbase** | 0.40% | 0.60% | Conservative estimates |
| **Kraken** | 0.16% | 0.26% | Moderate fee simulation |
| **Binance** | 0.10% | 0.10% | Low-fee simulation |
The fee rates display shows your current maker fee, taker fee, and estimated round-trip cost.
### Resetting Paper Account
To reset your paper trading account (closes all positions and resets balance):
1. Navigate to **Settings** > **Paper Trading** tab
2. Click **Reset Paper Account** button
3. Confirm the reset in the dialog
4. All positions will be closed and balance reset to initial capital
5. You'll receive a success notification when complete
**Warning**: This action cannot be undone. All paper trading history will be preserved, but positions and balance will be reset.
## Data Provider Configuration
Data providers are used to fetch real-time pricing data for paper trading, backtesting, and ML training. They work independently of exchange integrations and don't require API keys.
### Configuring Providers
1. Navigate to **Settings** page
2. Click on **Data Providers** tab
3. Configure provider settings:
#### Primary Providers (CCXT)
Primary providers use CCXT to connect to cryptocurrency exchanges:
- **Kraken**: Default priority 1 (tried first)
- **Coinbase**: Default priority 2
- **Binance**: Default priority 3
Each provider can be:
- **Enabled/Disabled**: Toggle using the switch
- **Reordered**: Use up/down arrows to change priority order
- **Monitored**: View health status, response times, and success rates
#### Fallback Provider
**CoinGecko** is used as a fallback when primary providers are unavailable:
- Free tier API (no authentication required)
- Lower rate limits than primary providers
- Provides basic price data
#### Cache Settings
Configure caching behavior:
- **Ticker TTL (seconds)**: How long to cache ticker data (default: 2 seconds)
- **OHLCV TTL (seconds)**: How long to cache candlestick data (default: 60 seconds)
### Provider Status
The Data Providers tab shows:
- **Active Provider**: Currently used provider
- **Health Status**: Color-coded status for each provider:
- Green: Healthy and working
- Yellow: Degraded performance
- Red: Unhealthy or unavailable
- **Response Times**: Average response time for each provider
- **Success/Failure Counts**: Historical performance metrics
### Automatic Failover
The system automatically:
- Monitors provider health
- Switches to the next available provider if current one fails
- Opens circuit breakers for repeatedly failing providers
- Retries failed providers after a timeout period
### Troubleshooting Providers
If all providers fail:
1. Check your internet connection
2. Verify firewall isn't blocking connections
3. Check provider status in the Settings tab
4. Try enabling/disabling specific providers
5. Reset provider metrics if needed
## Risk Management Settings
Configure risk limits in the Settings page:
1. Navigate to **Settings** page
2. Click on **Risk Management** tab
3. Configure the following settings:
- **Max Drawdown Limit (%)**: Maximum portfolio drawdown before trading stops
- **Daily Loss Limit (%)**: Maximum daily loss percentage
- **Default Position Size (%)**: Default percentage of capital to use per trade
4. Click **Save Risk Settings**
5. You'll receive a success notification when settings are saved
Settings are validated before saving and you'll see error messages if values are invalid.
## Data Storage
Data is stored in `~/.local/share/crypto_trader/`:
- `trading.db` - Legacy file (removed)
- `historical/` - Historical market data
- `logs/` - Application logs
### Database Options
### Database Options
**PostgreSQL (Required)**:
- All production data is stored in PostgreSQL.
- Requires a running PostgreSQL instance.
- Configure connection in `config.yaml`.
**SQLite (Internal)**:
- Used internally for unit testing only.
- No configuration required for users.
## Redis Configuration
Redis is used for distributed state management, ensuring autopilot state persists across restarts and preventing duplicate instances.
### Default Settings
Redis settings are configured in `config.yaml`:
```yaml
redis:
host: "127.0.0.1"
port: 6379
db: 0
password: null # Set if Redis requires authentication
socket_connect_timeout: 5
```
### Environment Variables
You can also configure Redis via environment variables:
- `REDIS_HOST` - Redis server hostname
- `REDIS_PORT` - Redis server port
- `REDIS_PASSWORD` - Redis password (if required)
### Verifying Redis Connection
Run the verification script:
```bash
python scripts/verify_redis.py
```
## Celery Configuration (Background Tasks)
Celery handles long-running tasks like ML model training in the background.
### Starting the Worker
```bash
# From project root (with virtualenv activated)
celery -A src.worker.app worker --loglevel=info
```
Or use the helper script:
```bash
./scripts/start_all.sh
```
### Task Queues
Tasks are routed to specific queues:
- `ml_training` - Model training and data bootstrapping
- `reporting` - Report generation
- `celery` - Default queue
## ML Model Training Configuration
Configure how the autopilot ML model is trained via the Settings page.
### Training Data Configuration
Navigate to **Settings** > **Autopilot** tab to access these settings:
| Setting | Description | Recommended |
|---------|-------------|-------------|
| **Historical Data (days)** | Amount of historical data to fetch for training | 90-365 days |
| **Timeframe** | OHLCV candle timeframe for training data | 1h (balanced) |
| **Min Samples per Strategy** | Minimum samples required per strategy | 30+ |
| **Training Symbols** | Cryptocurrencies to include in training | 5-10 major coins |
### Setting Training Symbols
1. Navigate to **Settings** > **Autopilot** tab
2. In the **Training Data Configuration** section, find **Training Symbols**
3. Click to add/remove symbols from the multi-select dropdown
4. Common symbols: BTC/USD, ETH/USD, SOL/USD, XRP/USD, ADA/USD
5. Click **Save Bootstrap Config** to persist your changes
### Triggering Model Training
1. Click **Retrain Model** button in the Model Management section
2. A progress bar will appear showing:
- Data fetching progress (20-60%)
- Training progress (70-100%)
3. Training typically takes 30-60 seconds depending on data volume
4. Upon completion, the model card updates to show:
- "Global Model Trained" badge
- Number of strategies and features
- Training accuracy
- Which symbols the model was trained on
### Training Progress Persistence
Training progress persists across page navigation:
- If you navigate away during training, progress resumes on return
- The training task ID is stored in browser localStorage
- On task completion or failure, the task ID is cleared
### Model Management
- **Retrain Model**: Triggers retraining with current configuration
- **Reset Model**: Deletes all saved model files (confirmation required)
### Troubleshooting Training
If training fails:
1. Check that Redis and Celery are running
2. Review Celery worker logs: `tail -f celery.log`
3. Ensure sufficient historical data is available
4. Try reducing the number of training symbols
5. Check backend logs for error details
### Monitoring Tasks
The API provides endpoints to monitor background tasks:
- `POST /api/autopilot/intelligent/retrain` - Starts training, returns task ID
- `GET /api/autopilot/tasks/{task_id}` - Check task status
## Environment Variables
You can override configuration using environment variables:
- `CRYPTO_TRADER_CONFIG_DIR` - Custom config directory
- `CRYPTO_TRADER_DATA_DIR` - Custom data directory
- `CRYPTO_TRADER_LOG_DIR` - Custom log directory
- `DB_PASSWORD` - Database password (for PostgreSQL)
- `REDIS_HOST` - Redis server hostname
- `REDIS_PORT` - Redis server port
- `REDIS_PASSWORD` - Redis password
## Backup and Restore
### Backup
1. Stop the application and Celery workers
2. Backup PostgreSQL database
3. Copy the entire `~/.local/share/crypto_trader/` directory
4. Copy `~/.config/crypto_trader/` directory
5. (Optional) Export Redis data with `redis-cli SAVE`
### Restore
1. Stop the application
2. Restore PostgreSQL database
3. Replace the directories with your backup
4. Restart Redis, Celery worker, and application

235
docs/user_manual/faq.md Normal file
View File

@@ -0,0 +1,235 @@
# Frequently Asked Questions
Common questions about Crypto Trader.
## General Questions
### What is Crypto Trader?
Crypto Trader is a comprehensive web-based cryptocurrency trading platform for trading, backtesting, and portfolio management. It features a modern React frontend with a FastAPI backend, supporting multiple exchanges, real-time trading, paper trading, and advanced analytics.
### Is Crypto Trader free?
[Answer depends on your licensing - update as needed]
### What operating systems are supported?
The web interface works on any operating system with a modern browser:
- **Backend**: Linux, macOS, Windows (Python 3.11+)
- **Frontend**: Any OS with Chrome, Firefox, Safari, or Edge
- **Recommended**: Linux (Bluefin Linux) or macOS for development
### What Python version is required?
Python 3.11 or higher is required.
## Installation Questions
### How do I install Crypto Trader?
See the [Getting Started](getting_started.md) guide for installation instructions.
### Can I run from source?
Yes, see the [Getting Started](getting_started.md) guide. You'll need to run both the backend (FastAPI) and frontend (React) servers.
### Do I need to install TA-Lib separately?
TA-Lib is bundled in the AppImage. For source installation, you may need to install the TA-Lib C library separately.
## Trading Questions
### Is paper trading safe?
Yes, paper trading uses virtual funds and doesn't risk real money. It's perfect for testing strategies.
### How do I switch from paper trading to live trading?
1. Configure exchange API keys with trading permissions
2. Disable paper trading mode in settings
3. Start with small position sizes
4. Monitor closely
### What exchanges are supported?
Currently Coinbase is supported. The framework supports adding additional exchanges.
### Can I trade futures?
Yes, futures and leverage trading are supported. See the trading guide for details.
## Strategy Questions
### How do I create a strategy?
See the [Strategy Guide](strategies.md) for detailed instructions.
### Can I use multiple strategies at once?
Yes, you can run multiple strategies simultaneously on different symbols or timeframes.
### How do I optimize strategy parameters?
Use the backtesting optimization features. See the [Backtesting Guide](backtesting.md#parameter-optimization).
### Can I create custom strategies?
Yes, see the [Developer Guide](../developer/creating_strategies.md) for instructions.
## Backtesting Questions
### How accurate is backtesting?
Backtesting includes realistic features like slippage and fees, but past performance doesn't guarantee future results.
### How much historical data do I need?
At least 6-12 months of data is recommended for reliable backtesting.
### Can I backtest multiple strategies?
Yes, you can backtest multiple strategies and compare results.
## Autopilot Questions
### What's the difference between Pattern-Based and ML-Based Autopilot?
**Pattern-Based Autopilot** uses technical chart pattern recognition combined with sentiment analysis. It's transparent, explainable, and works immediately without training data. **ML-Based Autopilot** uses machine learning to select the best strategy based on market conditions. It's adaptive and learns from historical performance but requires training data.
See the [Trading Guide](trading.md#autopilot-modes) for detailed comparison.
### Which autopilot mode should I use?
- **Use Pattern-Based** if you want transparency, understand technical analysis, prefer explainable decisions, or want immediate setup.
- **Use ML-Based** if you want adaptive decisions, have historical trading data, don't need to understand every decision, or want maximum optimization.
See the [decision guide](trading.md#choosing-the-right-autopilot-mode) for more details.
### Can I switch between modes?
Yes, you can switch between modes at any time. Simply stop the current autopilot, select the desired mode, and start it again. You cannot run both modes simultaneously for the same symbol.
### What is auto-execution and should I enable it?
Auto-execution automatically executes trades based on autopilot signals. It's available for both modes and can be enabled/disabled independently.
**Enable auto-execution if**:
- You've tested the autopilot in paper trading mode
- You trust the autopilot's signals
- You've set appropriate risk limits
- You can monitor trades regularly
**Don't enable auto-execution if**:
- You're new to the autopilot
- You haven't tested it thoroughly
- You want to review signals before executing
- You're trading with real money and want manual control
### How do I know which mode is running?
The Dashboard shows the active mode in the status chip (e.g., "AutoPilot Active (pattern)"). You can also check the Autopilot Configuration section to see the selected mode.
### Can I use both modes simultaneously?
No, you can only run one autopilot mode at a time per symbol. However, you can run different modes on different symbols.
### What happens if I switch modes while autopilot is running?
You must stop the current autopilot before switching modes. The system will prevent starting a new mode while another is running for the same symbol.
### Does Pattern-Based Autopilot require training data?
No, Pattern-Based Autopilot works immediately without any training data. It uses predefined pattern recognition rules and sentiment analysis.
### Does ML-Based Autopilot always need training data?
Yes, ML-Based Autopilot requires training data to build its model. However, the system can bootstrap training data from historical backtests if available. You can also manually trigger model training from the Dashboard.
### How accurate are autopilot signals?
Signal accuracy depends on market conditions and the selected mode:
- **Pattern-Based**: Accuracy depends on pattern clarity and sentiment alignment
- **ML-Based**: Accuracy depends on model training quality and market regime match
Past performance doesn't guarantee future results. Always use risk management and test thoroughly in paper trading mode.
## Data Questions
### Where is data stored?
Data is stored in `~/.local/share/crypto_trader/`:
- Database: `trading.db`
- Historical data: `historical/`
- Logs: `logs/`
### How much storage do I need?
Storage depends on:
- Historical data retention
- Number of symbols tracked
- Log retention settings
Typically 1-5GB is sufficient.
### Can I use PostgreSQL instead of SQLite?
Yes, PostgreSQL is supported for advanced users. See the [Configuration Guide](configuration.md#database-options).
## Security Questions
### Are my API keys secure?
Yes, API keys are encrypted before storage using industry-standard encryption.
### Can I use read-only API keys?
Yes, read-only keys are recommended for backtesting and data collection.
### Where are API keys stored?
API keys are stored encrypted in the SQLite database.
## Performance Questions
### Why is the application slow?
Possible causes:
- Large historical datasets
- Many active strategies
- Insufficient system resources
- Database optimization needed
See [Troubleshooting](troubleshooting.md#performance-issues) for solutions.
### How can I improve performance?
- Reduce data retention
- Limit active strategies
- Optimize database
- Increase system resources
## Technical Questions
### Can I contribute to the project?
Yes! See the [Developer Guide](../developer/contributing.md) for contribution guidelines.
### How do I report bugs?
Create an issue with:
- Error description
- Steps to reproduce
- System information
- Log files
### Is there an API?
Yes, see the [API Documentation](../api/index.html) for details.
## Still Have Questions?
- Check the [User Manual](README.md)
- Review [Troubleshooting](troubleshooting.md)
- Consult [API Documentation](../api/index.html)
- See [Developer Guide](../developer/README.md)

157
docs/user_manual/getting_started.md Normal file
View File

@@ -0,0 +1,157 @@
# Getting Started
This guide will help you install and set up Crypto Trader for the first time.
## Installation
### From AppImage (Recommended for Bluefin Linux)
1. Download the latest AppImage release from the releases page
2. Make it executable:
```bash
chmod +x crypto_trader-*.AppImage
```
3. Run the application:
```bash
./crypto_trader-*.AppImage
```
### From Source
1. Clone the repository:
```bash
git clone <repository-url>
cd crypto_trader
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Install backend dependencies:
```bash
pip install -r requirements.txt
pip install -r backend/requirements.txt
```
5. Install frontend dependencies:
```bash
cd frontend
npm install
```
6. Run the application:
**Backend** (in one terminal):
```bash
python -m uvicorn backend.main:app --reload --port 8000
```
**Frontend** (in another terminal):
```bash
cd frontend
npm run dev
```
Access the application at: http://localhost:3000
API documentation at: http://localhost:8000/docs
## First Launch
When you first launch Crypto Trader:
1. **Configuration Setup**: The application will create configuration directories:
- `~/.config/crypto_trader/` - Configuration files
- `~/.local/share/crypto_trader/` - Data and database
- `~/.local/share/crypto_trader/logs/` - Application logs
2. **Database Initialization**:
- Ensure PostgreSQL is running and credentials are configured in `config.yaml` or via environment variables.
- Tables will be created automatically on first run.
3. **Paper Trading**: By default, the application starts in paper trading mode with $100 virtual capital.
4. **UI Overview**: The web interface contains six main pages accessible via the navigation menu:
- **Dashboard**: Overview with AutoPilot controls, system health, and real-time market data
- **Strategies**: Create, edit, delete, and manage trading strategies with full parameter configuration
- **Trading**: Manual order placement, order management, and position closing
- **Portfolio**: View portfolio performance, holdings, allocation charts, and risk metrics
- **Backtesting**: Configure and run backtests on historical data with progress tracking
- **Settings**: Manage exchanges, risk settings, alerts, alert history, and application configuration
## Adding Your First Exchange
1. Click on the **Settings** tab
2. In the **Exchanges** section, click **Add Exchange**
3. Enter your exchange name (e.g., "Coinbase")
4. Enter your API key and secret
5. Choose **Read-Only Mode** for safety (recommended for first-time setup)
6. Click **Save**
7. Test the connection using the **Test Connection** button
## Placing Your First Trade
1. Go to the **Trading** tab
2. Select an exchange and symbol from the dropdowns
3. Choose order type (Market, Limit, or Stop)
4. Select Buy or Sell
5. Enter quantity
6. For limit orders, enter your desired price
7. Click **Place Order**
The order will execute in paper trading mode by default. You can view your positions in the **Open Positions** table and order history in the **Order History** section.
## Using Autopilot
The Autopilot feature provides autonomous trading signal generation with two modes:
1. **Pattern-Based Autopilot**: Uses technical pattern recognition and sentiment analysis
- Transparent and explainable
- Works immediately without training data
- Best for users who want to understand every decision
2. **ML-Based Autopilot**: Uses machine learning to select optimal strategies
- Adaptive and learns from performance
- Requires training data
- Best for users who want data-driven optimization
**Quick Start**:
1. Go to the **Dashboard** page
2. In the **Autopilot Configuration** section, select your preferred mode
3. Choose a symbol (e.g., BTC/USD)
4. Optionally enable **Auto-Execute** (start with paper trading first!)
5. Click **Start AutoPilot**
See the [Trading Guide](trading.md#autopilot-modes) for detailed information about both modes and when to use each.
## Next Steps
1. [Configure your exchanges](configuration.md#exchanges)
2. [Set up your first strategy](strategies.md#creating-a-strategy)
3. [Try paper trading](trading.md#paper-trading)
4. [Try autopilot](trading.md#autopilot-modes)
5. [Run a backtest](backtesting.md#running-a-backtest)
## System Requirements
- **Python**: 3.11 or higher
- **Operating System**: Linux (Bluefin Linux recommended), macOS, Windows
- **Memory**: 2GB RAM minimum, 4GB recommended
- **Storage**: 500MB for application, additional space for historical data
- **Network**: Internet connection for real-time data and trading
- **Database**: PostgreSQL 12 or higher (required)
## Getting Help
- Check the [FAQ](faq.md) for common questions
- Review the [Troubleshooting](troubleshooting.md) guide
- Consult the [API Documentation](../api/index.html) for advanced usage

134
docs/user_manual/portfolio.md Normal file
View File

@@ -0,0 +1,134 @@
# Portfolio Management
This guide explains the Portfolio view and how to interpret portfolio metrics.
## Portfolio View Features
The Portfolio page provides a comprehensive view of your trading portfolio with three main tabs:
### Overview Tab
#### Summary Cards
At the top of the page, you'll see four summary cards:
- **Current Value**: Current portfolio value (cash + positions)
- **Unrealized P&L**: Profit/loss on open positions (color-coded: green for profit, red for loss)
- **Realized P&L**: Profit/loss from closed trades
- **Daily Change**: Percentage change in portfolio value today
#### Portfolio Value History Chart
An equity curve chart showing:
- Portfolio value over time (last 30 days by default)
- P&L line showing profit/loss progression
- Interactive tooltips showing exact values on hover
#### Risk Metrics
A grid of risk metrics cards showing:
- **Sharpe Ratio**: Risk-adjusted return measure
- **Sortino Ratio**: Downside risk-adjusted return
- **Max Drawdown**: Largest historical decline (percentage)
- **Win Rate**: Percentage of profitable trades
- **Total Return**: Overall return percentage
#### Holdings
All open positions displayed as cards showing:
- **Symbol**: Trading pair
- **Quantity**: Amount held (8 decimal precision)
- **Entry Price**: Average entry price
- **Current Price**: Latest market price
- **Value**: Current position value
- **Unrealized P&L**: Profit/loss with percentage change
- **Realized P&L**: Profit/loss from closed portions
- **Close Position Button**: Close the position directly from the card
Each position card is color-coded with a chip showing the P&L percentage.
### Allocations Tab
A pie chart visualization showing:
- Portfolio allocation by asset
- Percentage breakdown for each holding
- Interactive tooltips with exact dollar values
- Color-coded segments for easy identification
This helps you visualize your portfolio distribution and identify over-concentration in specific assets.
### Reports & Export Tab
Export functionality for:
- **Export Trades**: Download all trading history as CSV
- **Export Portfolio**: Download current portfolio holdings as CSV
- **Tax Reporting**: Generate tax reports using FIFO or LIFO methods
### Risk Metrics
- **Current Drawdown**: Current decline from peak value
- **Max Drawdown**: Largest historical decline
- **Sharpe Ratio**: Risk-adjusted return measure
- **Sortino Ratio**: Downside risk-adjusted return
- **Win Rate**: Percentage of profitable trades
### Performance Chart
The equity curve chart shows portfolio value over time, helping you visualize performance trends.
## Understanding Metrics
### Sharpe Ratio
Measures risk-adjusted returns. Higher values indicate better risk-adjusted performance:
- **> 1**: Good
- **> 2**: Very good
- **> 3**: Excellent
### Sortino Ratio
Similar to Sharpe but only considers downside volatility. Better for asymmetric return distributions.
### Drawdown
Maximum peak-to-trough decline. Lower is better:
- **< 10%**: Low risk
- **10-20%**: Moderate risk
- **> 20%**: High risk
## Closing Positions from Portfolio
You can close positions directly from the Portfolio page:
1. Navigate to the **Portfolio** page
2. In the **Overview** tab, find the position card you want to close
3. Click **Close Position** button on the card
4. In the dialog:
- Choose order type (Market or Limit)
- For limit orders, enter the limit price
5. Click **Close Position** to confirm
The position will be closed and removed from your holdings. You'll receive a notification when the order is filled.
## Data Freshness
The Portfolio page shows a data freshness indicator in the header showing when the data was last updated. The page automatically refreshes every 5 seconds to show the latest data.
## Exporting Data
### Export Trades
1. Navigate to **Portfolio** > **Reports & Export** tab
2. Click **Export Trades CSV** button
3. The file will download with all your trading history
### Export Portfolio
1. Navigate to **Portfolio** > **Reports & Export** tab
2. Click **Export Portfolio CSV** button
3. The file will download with current holdings
### Tax Reports
1. Navigate to **Portfolio** > **Reports & Export** tab
2. Select tax method (FIFO or LIFO)
3. Enter tax year
4. Optionally filter by symbol
5. Click **Generate Tax Report**
6. The CSV file will download with tax reporting information

120
docs/user_manual/reporting.md Normal file
View File

@@ -0,0 +1,120 @@
# Reporting Guide
Export your trading data and generate reports.
## Export Formats
### CSV Export
Export data to CSV for spreadsheet analysis:
- **Trades**: All executed trades
- **Orders**: Order history
- **Positions**: Current and historical positions
- **Portfolio**: Portfolio snapshots
- **Backtest Results**: Backtesting data
### PDF Reports
Generate comprehensive PDF reports:
- **Trading Report**: Summary of trading activity
- **Performance Report**: Portfolio performance analysis
- **Tax Report**: Tax reporting information
## Exporting Trades
1. Navigate to Reporting view
2. Select "Export Trades"
3. Choose date range:
- **Start Date**: Beginning of period
- **End Date**: End of period
4. Select filters:
- **Symbol**: Specific trading pair
- **Paper Trading**: Include/exclude paper trades
- **Exchange**: Specific exchange
5. Choose format: CSV or PDF
6. Click "Export"
7. Save file
## Exporting Portfolio
1. Select "Export Portfolio"
2. Choose data:
- **Current Positions**: Open positions
- **Position History**: Historical positions
- **Performance Metrics**: Analytics data
3. Select format
4. Click "Export"
5. Save file
## Tax Reporting
Generate tax reports for accounting:
1. Navigate to Reporting > Tax Report
2. Select tax year
3. Choose method:
- **FIFO**: First In, First Out
- **LIFO**: Last In, First Out
- **Specific Identification**: Choose specific lots
4. Configure settings:
- **Currency**: Reporting currency
- **Include Fees**: Include trading fees
- **Include Paper Trades**: Optional
5. Generate report
6. Review and export
### Tax Report Contents
- **Realized Gains/Losses**: Profit/loss from closed trades
- **Trade Summary**: All trades in period
- **Cost Basis**: Purchase costs
- **Proceeds**: Sale proceeds
- **Gain/Loss**: Net gain or loss
## Scheduled Reports
Set up automatic report generation:
1. Navigate to Settings > Scheduled Reports
2. Click "Add Schedule"
3. Configure:
- **Report Type**: Trades, Portfolio, Tax
- **Frequency**: Daily, Weekly, Monthly
- **Format**: CSV, PDF
- **Email**: Optional email delivery
4. Save schedule
## Performance Reports
Generate performance analysis reports:
- **Period Performance**: Returns for time period
- **Risk Metrics**: Sharpe, Sortino, drawdown
- **Trade Analysis**: Win rate, average win/loss
- **Asset Performance**: Performance by asset
- **Monthly Breakdown**: Performance by month
## Custom Reports
Create custom reports:
1. Select "Custom Report"
2. Choose data sources:
- Trades
- Positions
- Portfolio snapshots
- Backtest results
3. Select metrics to include
4. Configure filters
5. Generate report
## Best Practices
1. **Regular Exports**: Export data regularly for backup
2. **Tax Records**: Keep detailed tax reports
3. **Performance Tracking**: Generate monthly performance reports
4. **Data Backup**: Export before major updates
5. **Record Keeping**: Maintain organized export files

286
docs/user_manual/strategies.md Normal file
View File

@@ -0,0 +1,286 @@
# Strategy Guide
Learn how to create, configure, and manage trading strategies in Crypto Trader.
## What is a Strategy?
A trading strategy is a set of rules that determine when to buy and sell cryptocurrencies. Strategies analyze market data and generate trading signals.
## Pre-built Strategies
Crypto Trader includes several pre-built strategies:
### RSI Strategy
Uses the Relative Strength Index to identify overbought and oversold conditions.
- **Buy Signal**: RSI below 30 (oversold)
- **Sell Signal**: RSI above 70 (overbought)
- **Parameters**: RSI period (default: 14)
### MACD Strategy
Uses Moving Average Convergence Divergence for trend following.
- **Buy Signal**: MACD crosses above signal line
- **Sell Signal**: MACD crosses below signal line
- **Parameters**: Fast period, slow period, signal period
### Moving Average Crossover
Uses two moving averages to identify trend changes.
- **Buy Signal**: Short MA crosses above long MA
- **Sell Signal**: Short MA crosses below long MA
- **Parameters**: Short MA period, long MA period
### Confirmed Strategy (Multi-Indicator)
Requires multiple indicators (RSI, MACD, Moving Average) to align before generating signals. This significantly reduces false signals by requiring confirmation from 2-3 indicators.
- **Buy Signal**: When majority of indicators agree on buy signal
- **Sell Signal**: When majority of indicators agree on sell signal
- **Parameters**:
- RSI period, oversold, overbought thresholds
- MACD fast, slow, signal periods
- MA fast, slow periods, MA type (SMA/EMA)
- Minimum confirmations required (default: 2)
- Which indicators to require (RSI, MACD, MA)
### Divergence Strategy
Detects price vs. indicator divergences which are powerful reversal signals. Works exceptionally well in ranging markets.
- **Buy Signal**: Bullish divergence (price makes lower low, indicator makes higher low)
- **Sell Signal**: Bearish divergence (price makes higher high, indicator makes lower high)
- **Parameters**:
- Indicator type: RSI or MACD (default: RSI)
- Lookback period for swing detection (default: 20)
- Minimum swings required (default: 2)
- Minimum confidence threshold (default: 0.5)
### Bollinger Bands Mean Reversion
Trades mean reversion using Bollinger Bands. Buys at lower band in uptrends, exits at middle band. Works well in ranging markets.
- **Buy Signal**: Price touches lower Bollinger Band in uptrend
- **Sell Signal**: Price reaches middle band (profit target) or touches upper band (stop loss)
- **Parameters**:
- Bollinger Bands period (default: 20)
- Standard deviation multiplier (default: 2.0)
- Trend filter enabled (default: True)
- Trend MA period (default: 50)
- Entry threshold (how close to band, default: 0.95)
- Exit threshold (when to take profit, default: 0.5)
### Consensus Strategy (Ensemble)
Combines signals from multiple strategies with voting mechanism. Only executes when multiple strategies agree, improving signal quality through ensemble methods.
- **Buy Signal**: When minimum number of strategies agree on buy
- **Sell Signal**: When minimum number of strategies agree on sell
- **Parameters**:
- Strategy names to include (None = all available)
- Minimum consensus count (default: 2)
- Use performance-based weights (default: True)
- Minimum weight threshold (default: 0.3)
- Strategies to exclude
## Strategy Management Page
The Strategy Management page provides a comprehensive interface for creating, editing, and managing all your trading strategies.
### Accessing Strategy Management
1. Click on **Strategies** in the navigation menu
2. You'll see a table listing all your strategies with:
- Strategy name and description
- Strategy type
- Trading symbol
- Timeframes
- Status (Enabled/Disabled)
- Paper Trading mode
- Action buttons (Start, Stop, Edit, Delete)
## Creating a Strategy
1. Navigate to the **Strategies** page
2. Click **Create Strategy** button
3. The strategy dialog has three tabs:
**Basic Settings Tab**:
- **Name**: Give your strategy a descriptive name (required)
- **Description**: Optional description
- **Strategy Type**: Select from RSI, MACD, Moving Average, Confirmed, Divergence, Bollinger Mean Reversion, Consensus, DCA, Grid, or Momentum
- **Symbol**: Trading pair (e.g., BTC/USD)
- **Exchange**: Select the exchange (required)
- **Timeframes**: Select one or more timeframes (1m, 5m, 15m, 30m, 1h, 4h, 1d)
- **Paper Trading Mode**: Toggle for paper trading (recommended for testing)
**Parameters Tab**:
- Configure strategy-specific parameters
- Parameters vary by strategy type
- Default values are provided for all parameters
- See strategy-specific sections below for parameter details
**Risk Settings Tab**:
- **Position Size (%)**: Percentage of capital to use per trade
- **Stop Loss (%)**: Maximum loss percentage before exit
- **Take Profit (%)**: Profit target percentage
- **Max Position Size**: Optional maximum position size limit
4. Click **Create** to save the strategy
The strategy will appear in the strategies table. New strategies start as **Disabled** - you must enable and start them manually.
## Managing Strategies
### Starting a Strategy
1. Find the strategy in the table
2. Click the **Start** button (green play icon)
3. The strategy status will change to **Enabled** and it will begin generating signals
### Stopping a Strategy
1. Find the running strategy in the table
2. Click the **Stop** button (red stop icon)
3. The strategy will stop generating new signals
### Editing a Strategy
1. Click the **Edit** button (pencil icon) for the strategy
2. Modify any settings in the dialog
3. Click **Update** to save changes
**Note**: Strategy type cannot be changed after creation. You must create a new strategy with a different type.
### Deleting a Strategy
1. Click the **Delete** button (red trash icon)
2. Confirm the deletion in the dialog
3. The strategy and all its configuration will be permanently deleted
## Strategy Types
### DCA (Dollar Cost Averaging)
Invests a fixed amount at regular intervals (daily, weekly, or monthly). Ideal for long-term accumulation.
**Parameters:**
- Amount: Fixed investment amount per interval
- Interval: Daily, weekly, or monthly
- Target Allocation: Target portfolio allocation percentage
### Grid Trading
Places buy orders at lower price levels and sell orders at higher levels. Profits from price oscillations.
**Parameters:**
- Grid Spacing: Percentage between grid levels
- Number of Levels: Grid levels above and below center price
- Profit Target: Profit percentage to take
### Momentum
Trades based on price momentum with volume confirmation. Enters on strong upward momentum, exits on reversal.
**Parameters:**
- Lookback Period: Period for momentum calculation
- Momentum Threshold: Minimum momentum to enter
- Volume Threshold: Volume increase multiplier for confirmation
- Exit Threshold: Momentum reversal threshold
## Strategy Configuration
### Basic Settings
- **Name**: Descriptive name for your strategy
- **Symbol**: Trading pair (e.g., BTC/USD)
- **Timeframe**: Data timeframe (1m, 5m, 15m, 1h, 4h, 1d)
- **Enabled**: Turn strategy on/off
### Parameters
Each strategy has specific parameters:
- **RSI Strategy**: RSI period, overbought threshold, oversold threshold
- **MACD Strategy**: Fast period, slow period, signal period
- **Moving Average**: Short period, long period, MA type (SMA/EMA)
- **Confirmed Strategy**: RSI, MACD, and MA parameters, minimum confirmations
- **Divergence Strategy**: Indicator type, lookback period, confidence threshold
- **Bollinger Mean Reversion**: Period, std dev, trend filter settings
- **Consensus Strategy**: Strategy selection, consensus threshold, weighting options
### Risk Settings
- **Position Size**: Amount to trade per signal
- **Max Position**: Maximum position size
- **Stop Loss**: Percentage, price level, or ATR-based dynamic stop
- **ATR-based stops**: Automatically adjust stop distance based on market volatility
- **ATR Multiplier**: Multiplier for ATR calculation (default: 2.0)
- **ATR Period**: Period for ATR calculation (default: 14)
- **Take Profit**: Profit target
- **Trend Filter**: Optional ADX-based trend filter to avoid trading in choppy markets
## Multi-Timeframe Strategies
Strategies can use multiple timeframes:
1. Primary timeframe for signal generation
2. Higher timeframes for trend confirmation
3. Lower timeframes for entry timing
## Strategy Scheduling
Strategies can be scheduled to run:
- **Continuous**: Runs on every new candle
- **Time-based**: Runs at specific times
- **Condition-based**: Runs when conditions are met
## Managing Strategies
### Enabling/Disabling
- Toggle strategy on/off without deleting
- Disabled strategies don't generate signals
- Useful for testing multiple strategies
### Editing Strategies
1. Select the strategy
2. Click "Edit"
3. Modify parameters
4. Save changes
### Deleting Strategies
1. Select the strategy
2. Click "Delete"
3. Confirm deletion
## Strategy Performance
Monitor strategy performance:
- **Win Rate**: Percentage of profitable trades
- **Total Return**: Overall return
- **Sharpe Ratio**: Risk-adjusted return
- **Max Drawdown**: Largest peak-to-trough decline
- **Number of Trades**: Total trades executed
## Best Practices
1. **Backtest First**: Always backtest strategies before live trading
2. **Start Small**: Use small position sizes initially
3. **Monitor Performance**: Regularly review strategy results
4. **Adjust Parameters**: Optimize based on performance
5. **Use Paper Trading**: Test changes in paper trading first
## Creating Custom Strategies
For advanced users, you can create custom strategies:
1. See [Developer Guide](../developer/creating_strategies.md)
2. Extend the `BaseStrategy` class
3. Implement signal generation logic
4. Register your strategy

332
docs/user_manual/trading.md Normal file
View File

@@ -0,0 +1,332 @@
# Trading Guide
This guide explains how to trade cryptocurrencies using Crypto Trader.
## Trading Modes
### Paper Trading
Paper trading allows you to practice trading with virtual funds without risking real money.
- Default starting capital: $100 USD
- All trades are simulated
- Perfect for testing strategies
- No real money at risk
### Live Trading
Live trading executes real orders on connected exchanges.
- Requires exchange API keys with trading permissions
- Real money is at risk
- Always test strategies in paper trading first
- Use risk management features
## Autopilot Modes
The Autopilot feature provides autonomous trading signal generation with two distinct modes, each optimized for different use cases and user preferences.
### Pattern-Based Autopilot
**What it does**: Detects technical chart patterns (Head & Shoulders, triangles, wedges, etc.) and combines them with sentiment analysis to generate trading signals.
**How it works**:
- Uses geometric pattern recognition to identify 40+ chart patterns
- Analyzes news headlines using FinBERT for market sentiment
- Generates signals when patterns align with sentiment
- Rule-based logic: Pattern + Sentiment Alignment = Signal
**Best for**:
- Users who want transparency and explainable decisions
- Users who understand technical analysis
- Users who prefer immediate setup without training data
- Users who want lightweight, fast execution
**Key Features**:
- ✅ Transparent and explainable - you can see exactly why each signal was generated
- ✅ No training data required - works immediately
- ✅ Fast and lightweight - minimal resource usage
- ✅ Pattern recognition for 40+ chart patterns
- ✅ Real-time sentiment analysis
**Tradeoffs**:
- ❌ Less adaptive to market changes (fixed rules)
- ❌ Requires both pattern and sentiment alignment for signals
### ML-Based Autopilot
**What it does**: Uses machine learning to analyze market conditions and automatically select the best trading strategy from available strategies.
**How it works**:
- Analyzes current market conditions (volatility, trend, volume, etc.)
- Uses ML model trained on historical performance data
- Selects optimal strategy based on market regime
- Can auto-execute trades when confidence is high
**Best for**:
- Users who want adaptive, data-driven decisions
- Users who don't need to understand every decision
- Advanced users seeking performance optimization
- Users with sufficient historical data for training
**Key Features**:
- ✅ Adapts to market conditions automatically
- ✅ Learns from historical performance
- ✅ Optimizes strategy selection
- ✅ Market condition analysis
- ✅ Performance tracking and learning
**Tradeoffs**:
- ❌ Requires training data (needs historical trades)
- ❌ Less transparent (ML model decisions are less explainable)
- ❌ More complex setup (model training required)
### Choosing the Right Autopilot Mode
Use this decision guide to select the appropriate mode:
**Choose Pattern-Based if**:
- You want to understand every trading decision
- You prefer transparent, explainable logic
- You want immediate setup without waiting for training data
- You understand technical analysis patterns
- You want lightweight, fast execution
**Choose ML-Based if**:
- You want adaptive, data-driven decisions
- You have sufficient historical trading data
- You want the system to learn and optimize automatically
- You don't need to understand every decision
- You want maximum performance optimization
### Mode Comparison
| Feature | Pattern-Based | ML-Based |
|---------|--------------|----------|
| **Transparency** | High - All decisions explainable | Low - ML model decisions less transparent |
| **Adaptability** | Low - Fixed rules | High - Learns and adapts |
| **Setup Time** | Immediate - No setup required | Requires training data collection |
| **Resource Usage** | Low - Lightweight | Medium - ML model overhead |
| **Training Data** | Not required | Required |
| **Pattern Recognition** | Yes (40+ patterns) | No (uses strategies) |
| **Sentiment Analysis** | Yes (FinBERT) | No |
| **ML Strategy Selection** | No | Yes |
| **Auto-Execution** | Configurable | Configurable |
### Auto-Execution
Both autopilot modes support auto-execution, which can be enabled independently of mode selection.
**What is Auto-Execution?**
- When enabled, the autopilot will automatically execute trades based on generated signals
- Trades are executed according to risk management rules
- You can monitor all auto-executed trades in the Trading page
**Safety Considerations**:
- ⚠️ **Warning**: Auto-execution will automatically execute trades with real money (if not in paper trading mode)
- Always test in paper trading mode first
- Set appropriate risk limits before enabling
- Monitor auto-executed trades regularly
- Start with small position sizes
**How to Enable/Disable**:
1. Go to the Dashboard page
2. Find the Autopilot Configuration section
3. Toggle the "Auto-Execute" switch
4. Confirm when prompted (first time only)
**Monitoring Auto-Executed Trades**:
- All auto-executed trades appear in the Trading page
- Check the Order History tab to review executed trades
- Monitor positions in the Positions tab
- Review autopilot status in the Dashboard
### Switching Between Modes
You can switch between autopilot modes at any time:
1. Stop the current autopilot (if running)
2. Select the desired mode in the Autopilot Configuration section
3. Configure mode-specific settings
4. Start the autopilot in the new mode
**Note**: You cannot run both modes simultaneously for the same symbol. Stopping one mode before starting another is required.
## Manual Trading Interface
The Trading page provides a comprehensive interface for manual order placement and management.
### Accessing the Trading Page
1. Click on **Trading** in the navigation menu
2. The page displays:
- Account balance and summary
- Open positions (card view)
- Active orders table
- Order history table
### Placing Orders
#### Market Orders
Market orders execute immediately at the current market price.
1. Click **Place Order** button
2. In the order dialog:
- Select **Exchange** from dropdown
- Select **Symbol** (e.g., BTC/USD)
- Choose **Side** (Buy or Sell)
- Select **Order Type**: Market
- Enter **Quantity**
3. Click **Place Order**
The order will execute immediately. You'll see a success notification and the order will appear in the Active Orders table.
#### Limit Orders
Limit orders execute only when the price reaches your specified limit.
1. Click **Place Order** button
2. Select **Order Type**: Limit
3. Enter **Price** (required for limit orders)
4. Enter **Quantity**
5. Click **Place Order**
The order will appear in Active Orders and execute when the price reaches your limit.
#### Advanced Order Types
**Stop Loss**: Automatically sells if price drops below threshold
- Select "Stop Loss" order type
- Enter stop price
- Enter quantity
**Take Profit**: Automatically sells when profit target is reached
- Select "Take Profit" order type
- Enter target price
- Enter quantity
**Trailing Stop**: Adjusts stop price as price moves favorably
- Select "Trailing Stop" order type
- Enter initial stop price
- Enter quantity
**OCO (One-Cancels-Other)**: Places two orders, one cancels the other when filled
- Select "OCO" order type
- Configure both orders in advanced options
**Iceberg**: Large order split into smaller visible orders
- Select "Iceberg" order type
- Configure in advanced options
## Managing Positions
### Viewing Positions
Positions can be viewed in two places:
1. **Trading Page - Positions Tab**:
- Card-based view showing all open positions
- Each card displays:
- Symbol
- Quantity
- Entry price
- Current price
- Unrealized P&L (with percentage)
- Realized P&L
- Position value
2. **Portfolio Page**:
- Detailed portfolio view with allocation charts
- Same position cards with close functionality
### Closing Positions
1. Navigate to **Trading** page and select **Positions** tab, or go to **Portfolio** page
2. Find the position card you want to close
3. Click **Close Position** button on the card
4. In the close dialog:
- Choose order type (Market or Limit)
- For limit orders, enter the limit price
5. Click **Close Position** to confirm
The position will be closed and removed from your open positions. You'll receive a notification when the order is filled.
## Order Management
### Viewing Orders
The Trading page has three tabs for order management:
1. **Positions Tab**: Shows all open positions with detailed P&L information
2. **Active Orders Tab**: Displays all pending, open, and partially filled orders
- Shows order details: time, symbol, side, type, quantity, price, fill status
- Real-time updates as orders are filled or canceled
3. **Order History Tab**: Shows completed, canceled, rejected, and expired orders
- Includes filled quantity, average fill price, and fees
- Limited to most recent 50 orders
### Canceling Orders
1. Navigate to **Trading** page
2. Select **Active Orders** tab
3. Find the order you want to cancel
4. Click the **Cancel** button (red X icon) in the Actions column
The order will be canceled immediately and moved to Order History. You'll receive a notification confirming the cancellation.
### Order Status Indicators
Orders are color-coded by status:
- **Green (Filled)**: Successfully executed
- **Yellow (Pending/Open/Partially Filled)**: Waiting to be filled
- **Red (Cancelled/Rejected/Expired)**: Failed or canceled orders
## Best Practices
1. **Start with Paper Trading**: Always test strategies first
2. **Use Risk Management**: Set stop-losses and position limits
3. **Monitor Positions**: Regularly check your open positions
4. **Start Small**: Begin with small position sizes
5. **Keep Records**: Review your trading history regularly
## Fees
Trading fees are automatically calculated and deducted:
- **Maker fees**: Lower fees for limit orders that add liquidity
- **Taker fees**: Higher fees for market orders
- Fees vary by exchange
### Paper Trading Fee Simulation
For paper trading, you can simulate different exchange fee structures:
1. Go to **Settings → Paper Trading**
2. Select **Fee Model (Exchange)** from the dropdown:
- **Default**: 0.1% maker / 0.1% taker
- **Coinbase**: 0.4% maker / 0.6% taker
- **Kraken**: 0.16% maker / 0.26% taker
- **Binance**: 0.1% maker / 0.1% taker
3. Click **Save Settings**
The current fee rates display shows:
- Maker fee rate
- Taker fee rate
- Estimated round-trip cost (buy + sell)
This helps you understand how fees impact your trading strategy profitability before going live.
## Troubleshooting
**Order not executing?**
- Check exchange connection
- Verify API permissions
- Check account balance
- Review order parameters
**Position not showing?**
- Refresh the portfolio view
- Check database connection
- Review application logs

254
docs/user_manual/troubleshooting.md Normal file
View File

@@ -0,0 +1,254 @@
# Troubleshooting Guide
Common issues and solutions for Crypto Trader.
## Application Won't Start
### Issue: Backend server won't start
**Solutions:**
1. Check Python version (requires 3.11+)
2. Verify all dependencies are installed: `pip install -r requirements.txt && pip install -r backend/requirements.txt`
3. Check if port 8000 is already in use: `lsof -i :8000` (Linux/macOS) or `netstat -ano | findstr :8000` (Windows)
4. Try running manually: `python -m uvicorn backend.main:app --reload --port 8000`
5. Check log files in `~/.local/share/crypto_trader/logs/`
6. Verify database permissions
### Issue: Frontend won't start
**Solutions:**
1. Verify Node.js is installed (v18+): `node --version`
2. Install dependencies: `cd frontend && npm install`
3. Check if port 3000 is already in use
4. Try running manually: `cd frontend && npm run dev`
5. Clear node_modules and reinstall: `rm -rf node_modules package-lock.json && npm install`
6. Check browser console for errors
### Issue: Cannot connect to backend from frontend
**Solutions:**
1. Verify backend is running on http://localhost:8000
2. Check API endpoint in browser: http://localhost:8000/docs
3. Check CORS settings in backend
4. Verify API client URL in frontend code
5. Check browser console for CORS errors
6. Verify firewall isn't blocking connections
### Issue: Import errors
**Solutions:**
1. Reinstall dependencies: `pip install -r requirements.txt`
2. Verify virtual environment is activated
3. Check Python path configuration
4. Reinstall problematic packages
## Exchange Connection Issues
### Issue: Cannot connect to exchange
**Solutions:**
1. Verify API keys are correct
2. Check API key permissions
3. Verify internet connection
4. Check exchange status (may be down)
5. Review exchange rate limits
6. Check firewall settings
### Issue: API key errors
**Solutions:**
1. Verify API keys are valid
2. Check key permissions (read-only vs trading)
3. Regenerate API keys if needed
4. Verify IP whitelist settings
5. Check key expiration dates
## Trading Issues
### Issue: Orders not executing
**Solutions:**
1. Check account balance
2. Verify API permissions include trading
3. Check order parameters (price, quantity)
4. Review exchange order limits
5. Check if market is open
6. Verify order type is supported
### Issue: Positions not updating
**Solutions:**
1. Refresh portfolio view
2. Check database connection
3. Verify exchange connection
4. Review application logs
5. Restart application
## Data Issues
### Issue: Missing historical data
**Solutions:**
1. Check data collection is enabled
2. Verify exchange connection
3. Check data storage permissions
4. Review data retention settings
5. Manually trigger data collection
### Issue: Incorrect price data
**Solutions:**
1. Verify exchange connection
2. Check data source
3. Review data quality settings
4. Clear and reload data
5. Check for data gaps
## Performance Issues
### Issue: Application is slow
**Solutions:**
1. Check system resources (CPU, memory)
2. Reduce historical data retention
3. Optimize database (VACUUM ANALYZE)
4. Close unnecessary strategies
5. Reduce chart data points
6. Check for memory leaks in logs
### Issue: High memory usage
**Solutions:**
1. Reduce data retention period
2. Limit number of active strategies
3. Reduce chart history
4. Clear old logs
5. Restart application periodically
## Database Issues
### Issue: Database errors
**Solutions:**
1. Check database connection to PostgreSQL
2. Verify disk space available
3. Check database user permissions
4. Backup and restore database if corrupted
5. Review database logs
### Issue: Database connection failed
**Solutions:**
1. Check if PostgreSQL service is running
2. Verify connection URL in `config.yaml`
3. Check network connectivity to database host
4. Verify database user credentials and permissions
5. Check PostgreSQL logs
## Configuration Issues
### Issue: Settings not saving
**Solutions:**
1. Check config directory permissions
2. Verify config file is writable
3. Check disk space
4. Review application logs
5. Manually edit config file if needed
### Issue: Configuration errors
**Solutions:**
1. Validate YAML syntax
2. Check for invalid values
3. Review default configuration
4. Reset to defaults if needed
5. Check configuration file encoding
## Web UI Issues
### Issue: Page not loading or blank screen
**Solutions:**
1. Check browser console for JavaScript errors (F12)
2. Clear browser cache and reload
3. Verify frontend server is running
4. Check network tab for failed API requests
5. Try a different browser
6. Check if backend is accessible
### Issue: WebSocket connection not working
**Solutions:**
1. Check WebSocket status indicator in Dashboard
2. Verify backend WebSocket endpoint is accessible
3. Check browser console for WebSocket errors
4. Verify firewall/proxy settings allow WebSocket connections
5. Try refreshing the page
6. Check backend logs for WebSocket errors
### Issue: Real-time updates not appearing
**Solutions:**
1. Check WebSocket connection status
2. Verify WebSocket is connected (green indicator)
3. Refresh the page
4. Check browser console for errors
5. Verify backend is sending WebSocket messages
6. Check network tab for WebSocket connection
### Issue: Forms not submitting
**Solutions:**
1. Check browser console for validation errors
2. Verify all required fields are filled
3. Check for error messages in the form
4. Verify API endpoint is accessible
5. Check network tab for failed requests
6. Look for Snackbar error notifications
## Strategy Issues
### Issue: Strategy not generating signals
**Solutions:**
1. Verify strategy is enabled (check Strategies page)
2. Check strategy parameters
3. Verify data is available
4. Check strategy logs
5. Review signal generation logic
6. Check Operations Panel for running strategies
### Issue: Strategy errors
**Solutions:**
1. Check strategy parameters in Strategy Management page
2. Verify data availability
3. Review strategy code
4. Check application logs
5. Test with different parameters
6. Check error notifications in UI
## Getting Help
If you continue to experience issues:
1. **Check Logs**: Review application logs in `~/.local/share/crypto_trader/logs/`
2. **Review Documentation**: Check user manual and API docs
3. **Check FAQ**: See [FAQ](faq.md) for common questions
4. **Report Issues**: Create an issue with:
- Error messages
- Steps to reproduce
- System information
- Log files
## Log Files
Log files are located in `~/.local/share/crypto_trader/logs/`:
- `app.log`: Main application log
- `trading.log`: Trading operations
- `errors.log`: Error messages
- `debug.log`: Debug information (if enabled)
Review logs for detailed error information.