hyper/clp_hedger/CLP_HEDGING_IMPLEMENTATION_PLAN.md

# CLP Hedging Zone Strategy Implementation Plan
*Generated: 2025-12-16*
*Session Focus: Risk analysis and zone-based hedge optimization*

## Executive Summary
This plan implements a zone-based hedging strategy for narrow CLP ranges (+/- 0.3%) with $100 position size and $10 minimum trade constraints. The strategy maintains the existing 7.5-minute hedge delay for mean reversion while adding preparation zones for potential CLP closing.

## Current System Analysis

### Scripts & Configuration
- **uniswap_manager.py**: CLP lifecycle management (451-second interval)
- **clp_scalper_hedger.py**: Active hedging (4-second interval)
- **Strategy**: Mean reversion with intentional 7.5-minute unhedged period
- **Position Size**: $100 CLP position
- **Range Width**: +/- 0.3% (extremely narrow, requiring precise zone management)
- **Minimum Trade**: $10 (10% of position size - significant constraint)

### Risk Assessment
- **Strategic Risk**: Intentional unhedged exposure during 7.5-minute delay (accepted)
- **Technical Risks**: JSON file corruption, price source divergence, oscillation
- **Financial Impact**: $10 minimum trades create risk of overshooting hedge targets

## Proposed Zone Strategy

### Zone Structure
```
Range Position (% from bottom):
├── TOP PREPARE ZONE (90-100%): Gradual reduction 100% → 0%
├── TOP HYSTERESIS ZONE (85-90%): Maintain current hedge
├── MIDDLE NORMAL ZONE (10-85%): Normal hedge (100%)  
├── BOTTOM HYSTERESIS ZONE (5-10%): Maintain current hedge
└── BOTTOM MAX ZONE (0-5%): Enhanced over-hedge (112.5%)
```

### Zone Rationale
- **90% Preparation Start**: Adequate preparation time while minimizing whipsaw risk
- **85-90% Hysteresis Buffer**: Prevents oscillation near top boundary
- **5-10% Bottom Buffer**: Reduces frequency of over-hedge adjustments
- **0-5% Enhanced Over-hedge**: Maximum protection when CLP is fully WETH

## Implementation Details

### Configuration Updates
```python
# Zone Boundaries for Narrow Range
TOP_PREPARE_START = 0.90           # Start unhedging at 90%
TOP_HYSTERESIS_START = 0.85        # Hysteresis buffer zone
BOTTOM_HYSTERESIS_END = 0.10      # Bottom hysteresis buffer
BOTTOM_MAX_ZONE_END = 0.05        # Enhanced over-hedge until 5%

# $10 Minimum Trade Controls
MIN_PRICE_MOVEMENT_PCT = 0.10      # 10% range movement before adjustment
MIN_TIME_BETWEEN_ADJUSTMENTS = 60  # 1 minute minimum between trades
MIN_TRADE_SIZE_USD = 10.0         # $10 minimum trade size

# Hedge Multipliers
TOP_PREPARE_MULTIPLIER = 0.0       # 0% hedge in prepare zone
NORMAL_HEDGE_MULTIPLIER = 1.0      # 100% normal hedge  
BOTTOM_MAX_MULTIPLIER = 1.125      # 112.5% over-hedge

# Risk Management
MAX_DAILY_TRADES = 3               # Maximum trades per day
MAX_DAILY_EXPOSURE_USD = 30.0      # Maximum daily trade exposure
OVERSHOOT_TOLERANCE_PCT = 0.05     # 5% tolerance on $10 trades
```

### Core Methods to Implement

#### 1. Zone Calculation Method
```python
def calculate_zone_multiplier(self, price_pct):
    """
    Calculate hedge multiplier based on price position within CLP range.
    Implements gradual transitions and hysteresis.
    """
    if price_pct >= 0.90:  # 90-100%: Gradual reduction
        return (1.0 - (price_pct - 0.90) / 0.10)
    elif price_pct <= 0.05:  # 0-5%: Enhanced over-hedge
        return 1.0 + (0.05 - price_pct) * 0.25  # 112.5% at 0%, 100% at 5%
    else:  # 5-90%: Normal hedge
        return 1.0
```

#### 2. Hysteresis Control
```python
def should_adjust_hedge(self, current_price_pct, last_adjustment_pct, last_adjustment_time):
    """
    Prevent frequent small adjustments due to $10 minimum trade constraint.
    """
    # Minimum price movement (equivalent to $10 trade)
    if abs(current_price_pct - last_adjustment_pct) < self.MIN_PRICE_MOVEMENT_PCT:
        return False
    
    # Minimum time between adjustments
    if time.time() - last_adjustment_time < self.MIN_TIME_BETWEEN_ADJUSTMENTS:
        return False
        
    return True
```

#### 3. Trade Size Optimization
```python
def calculate_optimal_trade_size(self, diff, position_value):
    """
    Round trades to $10 increments and enforce minimum trade size.
    """
    trade_value_usd = abs(diff * position_value)
    
    # Skip if below minimum
    if trade_value_usd < self.MIN_TRADE_SIZE_USD:
        return 0
    
    # Round to nearest $10 increment for efficiency
    rounded_trade_value = round(trade_value_usd / 10.0) * 10.0
    
    # Convert back to position units
    return rounded_trade_value / position_value
```

### Files to Modify

#### Primary: clp_scalper_hedger.py
**Lines to Update:**
- **44-53**: Zone configuration constants
- **252-284**: Core `calculate_rebalance()` method
- **255-265**: Integrate with existing over-hedge logic

**Methods to Add:**
- `calculate_zone_multiplier()` - Zone-based hedge calculation
- `should_adjust_hedge()` - $10 minimum trade logic  
- `calculate_optimal_trade_size()` - Rounding to $10 increments
- `update_zone_state()` - Hysteresis zone management

#### Secondary: hedge_status.json (runtime)
- Add zone transition tracking fields
- Add last adjustment timestamps
- Add daily trade count tracking

## Risk Management Strategy

### Financial Risk Controls
- **Position Size Limit**: $100 maximum CLP position
- **Daily Trade Limit**: Maximum 3 trades ($30 exposure)
- **Over-hedge Cap**: 125% absolute maximum (vs 112.5% target)
- **Transaction Cost Budget**: $5 maximum daily trading costs

### Technical Risk Mitigation
- **JSON File Locking**: Prevent concurrent access corruption
- **Hysteresis Implementation**: Prevent oscillation trading
- **Position Validation**: Verify hedge calculations before execution
- **Emergency Stops**: Circuit breakers on extreme market moves

### Operational Risk Controls
- **Time-based Limits**: Minimum intervals between adjustments
- **Movement Thresholds**: Minimum price changes before trading
- **Overshoot Protection**: Tolerance bands around target hedge ratios
- **Daily Cumulative Limits**: Maximum position change per day

## Implementation Sequence

### Phase 1: Core Zone Logic (Priority 1)
1. **Implement zone calculation method**
2. **Add hysteresis controls**
3. **Integrate with existing over-hedge logic**
4. **Update configuration constants**

### Phase 2: Trade Optimization (Priority 2)
1. **Implement $10 minimum trade logic**
2. **Add rounding to nearest $10 increment**
3. **Add minimum time between trades**
4. **Integrate with existing `manage_orders()` method**

### Phase 3: Risk Controls (Priority 3)
1. **Add daily trade count limits**
2. **Implement overshoot protection**
3. **Add position validation checks**
4. **Create monitoring/logging for zone transitions**

### Phase 4: Live Deployment & Optimization (Priority 4)
1. **Deploy with $100 position**
2. **Monitor zone transition frequency**
3. **Adjust zone boundaries based on observations**
4. **Optimize trade timing and size**

## Key Questions for Finalization

### Configuration Preferences
1. **Zone Boundaries**: Are 90%/85%/10%/5% boundaries optimal, or should they be adjusted?
2. **Trade Frequency**: Is 3 trades per day acceptable, or prefer fewer/larger trades?
3. **Over-hedge Level**: Is 112.5% multiplier appropriate, or more/less aggressive?
4. **Time Buffers**: Is 1-minute minimum between trades sufficient?

### Risk Tolerance
5. **Maximum Daily Exposure**: Is $30 daily trade exposure acceptable?
6. **Overshoot Tolerance**: Is 5% tolerance on $10 trades appropriate?
7. **Position Size**: Should we start with smaller position during testing?

### Strategy Behavior
8. **Zone Entry Logic**: Should we implement different thresholds for entering vs exiting zones?
9. **Trade Timing**: Should trades occur immediately on zone entry or wait for confirmation?
10. **Market Conditions**: Should zones adapt based on volatility or time of day?

## Success Metrics

### Primary Metrics
- **Oscillation Frequency**: < 2 zone changes per hour
- **Trade Efficiency**: > 80% of trades executed at optimal size ($10+)
- **Hedge Accuracy**: Average hedge ratio within 5% of target
- **Transaction Costs**: < 3% of position value per day

### Secondary Metrics
- **Zone Transition Smoothness**: Gradual transitions without sudden jumps
- **Risk Control Compliance**: No violations of daily limits
- **System Stability**: No JSON corruption or sync issues
- **Strategy Performance**: Improvement over current baseline

## Monitoring & Alerts

### Real-time Monitoring
- Zone transition logging
- Hedge ratio tracking
- Trade execution verification
- Price source divergence detection

### Alert Conditions
- Excessive oscillation (> 5 zone changes/hour)
- Approaching daily trade limits
- Large hedge ratio deviations (> 10% from target)
- JSON file access conflicts

## Rollback Plan

### Immediate Rollback Triggers
- Financial losses > 15% of position value
- System instability or crashes
- Excessive trading frequency (> 5 trades/hour)
- Hedge calculation errors

### Rollback Procedure
1. Stop both scripts
2. Restore original configuration
3. Verify position status
4. Resume with baseline strategy
5. Analyze failure causes

## Next Steps

1. **Confirm Final Configuration**: Zone boundaries, trade limits, risk tolerances
2. **Implement Core Logic**: Zone calculation and hysteresis methods
3. **Integrate with Existing Code**: Update calculate_rebalance() method
4. **Test with Small Position**: Validate with $100 position
5. **Monitor and Optimize**: Adjust based on observed behavior

---

*This plan serves as the complete technical specification for implementing zone-based hedging strategy with $10 minimum trade constraints. The solution maintains the existing mean reversion strategy while adding sophisticated preparation zones for CLP closing scenarios.*