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

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.