crypto_trader/docs/user_manual/trading.md

# 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