ManualTrader/docs/position-notifications.md

Position Notification Improvements

Overview

Enhanced the external event monitoring system to provide clear, distinct notifications for all position state changes. The system now properly distinguishes between position opening, closing, size increases, and size decreases.

Key Changes

1. Enhanced External Event Monitor (src/monitoring/external_event_monitor.py)

Added Methods:

• _determine_position_action_type(): Analyzes fills and current exchange state to determine the type of position action
• _update_lifecycle_position_size(): Updates position size in the lifecycle when positions change
• _send_position_change_notification(): Sends appropriate notifications based on position action type

Improved Logic:

• Better distinction between position opening, closing, increasing, and decreasing
• Real-time position size tracking and updates
• Enhanced PnL calculations for partial position changes

2. Enhanced Notification Manager (src/notifications/notification_manager.py)

Added Support:

• position_decreased action type in send_external_trade_notification()
• Detailed notifications showing before/after position sizes
• Partial PnL calculations for position decreases

Notification Types

1. Position Opened 🚀

When: New position created from zero Includes:

• Token and direction (LONG/SHORT)
• Entry size and price
• Total position value
• Timestamp

2. Position Closed 🎯

When: Position fully closed to zero Includes:

• Token and direction
• Size closed and exit price
• Entry vs exit price comparison
• Realized P&L with color coding
• Performance impact note

3. Position Increased 📈

When: Existing position size increased Includes:

• Token and direction
• Size added and add price
• Previous size vs new size
• Value of addition
• Current position status

4. Position Decreased 📉

When: Existing position partially closed Includes:

• Token and direction
• Size reduced and exit price
• Previous size vs remaining size
• Partial P&L for reduced amount
• Remaining position note

Benefits

1. Clear Position State Tracking

• No more confusion about whether a notification is for opening vs increasing position
• Distinct notifications for each type of position change
• Real-time position size updates in the database

2. Better PnL Visibility

• Immediate P&L calculations for position closures
• Partial P&L for position decreases
• Color-coded profit/loss indicators

3. Reduced Notification Noise

• Single notification per position change (no duplicate order fill notifications)
• Consolidated information in each notification
• Clear distinction between bot-initiated and external trades

4. Enhanced Decision Making

• Clear visibility into position size changes
• Better understanding of trading activity
• Improved risk management through real-time updates

Technical Implementation

Position State Detection Algorithm

1. Check if existing lifecycle exists for symbol
2. Get current position size from exchange
3. Compare with previous position size from lifecycle
4. Determine action based on:
   - No lifecycle + exchange position = position_opened
   - Lifecycle exists + no exchange position = position_closed
   - Same side trade + larger size = position_increased
   - Opposite side trade + smaller size = position_decreased

Lifecycle Updates

The system now properly updates the current_position_size field in trade lifecycles, ensuring accurate tracking of position changes over time.

Notification Flow

Fill Detected → Action Type Determined → Lifecycle Updated → Notification Sent

Future Enhancements

Potential Additions

1. Position flip detection (LONG to SHORT or vice versa)
2. Average entry price tracking for multiple entries
3. Position size alerts (e.g., when position exceeds certain thresholds)
4. Integration with risk management alerts

Configuration Options

1. Notification filtering by position size
2. Custom P&L thresholds for notifications
3. Different notification styles for different action types

Migration Notes

Backwards Compatibility

• Existing notification methods remain functional
• No breaking changes to current bot functionality
• Enhanced notifications work alongside existing position synchronizer

Database Updates

• Uses existing current_position_size field in trade lifecycles
• No schema changes required
• Leverages existing update_trade_market_data() method

Testing Recommendations

Test Scenarios

1. External position opening from zero
2. External position size increase
3. External position size decrease (partial close)
4. External position full close
5. Multiple consecutive size changes
6. Position changes while bot orders are active

Verification Points

• Notification accuracy and timing
• Position size tracking in database
• P&L calculations correctness
• No duplicate notifications
• Proper lifecycle state management