uniswap_auto_clp/florida/GEMINI.md

Uniswap Auto CLP & Delta-Neutral Hedger

Project Overview

This project is an automated high-frequency trading system designed to provide Concentrated Liquidity (CLP) on Uniswap V3 (and forks) while simultaneously hedging delta exposure on Hyperliquid.

The goal is to capture trading fees from the Liquidity Pool (LP) while neutralizing the price risk of the underlying assets (Impermanent Loss protection). The system operates as a Delta-Zero Scalper, effectively farming yields with reduced market exposure.

Architecture

The system consists of three independent Python processes that coordinate via shared JSON state files.

1. Position Manager (clp_manager.py)

• Role: Active Liquidity Provision.
• Functionality:
  • Connects to EVM chains (Arbitrum, BNB Chain, Base) via Web3.
  • Monitors {TARGET_DEX}_status.json and on-chain pool state.
  • Auto-Entry: Detects when no position exists, calculates optimal tick ranges based on RANGE_WIDTH_PCT, and mints a new NFT position.
  • Auto-Wrap: Automatically wraps native tokens (ETH -> WETH) if balances are insufficient.
  • Auto-Exit: Detects out-of-range positions, removes liquidity, and collects fees (CLOSE_POSITION_ENABLED).
  • State Sync: Updates {TARGET_DEX}_status.json with entry price, amounts, and token IDs for the Hedger.

2. Delta Hedger (clp_hedger.py)

• Role: Delta Neutralization (Risk Management).
• Functionality:
  • Connects to Hyperliquid (Perp DEX).
  • Reads {TARGET_DEX}_status.json to understand the current LP position's delta profile.
  • Dynamic Hedging: Calculates the precise Gamma (rate of change of delta) and rebalances the short position to keep Net Delta close to zero.
  • Scalping: Uses "Fishing Orders" (Maker orders) and volatility-adjusted thresholds to profit from hedging rebalances rather than just paying taker fees.
  • Safety: Includes emergency closures, edge protection logic (to avoid hedging at max loss points), and disconnect protection.

3. Monitoring (telegram_monitor.py)

• Role: Alerting.
• Functionality:
  • Watches {TARGET_DEX}_status.json for state transitions (OPEN -> CLOSED).
  • Sends real-time notifications to Telegram with PnL summaries, duration, and fees collected.

Key Files & Directories

File/Dir	Description
clp_manager.py	Main logic for Uniswap V3 interaction (Mint/Burn/Collect).
clp_hedger.py	Main logic for Hyperliquid hedging (Open/Close/Rebalance).
clp_config.py	Configuration profiles (Chain IDs, Contract Addresses) and Strategy settings.
telegram_monitor.py	Telegram bot for notifications.
{TARGET_DEX}_status.json	Critical: Shared state file acting as the database between Manager and Hedger.
.env	Stores secrets (Private Keys, RPCs). Do not commit.
tests/backtest/	New: Professional Backtesting & Optimization Framework.
tools/	Utility scripts, including the Git Agent for auto-backups.
logs/	Detailed logs for all processes.

Backtesting Framework (Jan 2026 Update)

A robust simulation engine has been implemented to validate strategies before capital commitment.

Components

• tests/backtest/backtester.py: Event-driven engine mocking Web3/Hyperliquid interactions.
• tests/backtest/mocks.py: Stateful simulator handling balance tracking, V3 tick math, and fee accrual.
• tests/backtest/grid_search.py: Optimization runner to test parameter combinations (Range Width, Hedging Threshold).
• tests/backtest/analyze_results.py: Helper to interpret simulation CSV results.

Progress Status (Jan 1, 2026)

• Completed:
  • Simulation loop runs end-to-end (Mint -> Accrue Fees -> Close).
  • Fixed Mock Pricing logic (handling inverted T0/T1 pairs like USDT/WBNB).
  • Implemented realistic Fee Accrual based on Trade Volume + Market Share.
  • Verified "In Range" detection and position lifecycle.
• Pending / Next Steps:
  • Hedger PnL Verification: Simulation showed 0.0 Hedging Fees because the price volatility in the 1-day sample was too low to trigger the 10% rebalance threshold. We are lowering thresholds to 1% to force activity and verify costs.
  • NAV Calculation: Refine "Total PnL" to include Unrealized PnL from both LP and Hedge to handle Impermanent Loss correctly.
  • Final Optimization: Run the grid_search.py with the corrected Market Share (0.02%) and lower thresholds to find the profitable "Sweet Spot".

Logic Details

Hedging Mathematics

The hedger calculates the Pool Delta derived from the V3 liquidity math:

\Delta_{LP} = L \times (\frac{1}{\sqrt{P}} - \frac{1}{\sqrt{P_{upper}}})

(For Token0/Token1 where we hedge Token0).

It then maintains a Short Position (S) such that:

S \approx \Delta_{LP}

Rebalancing

Rebalancing is triggered when:

1. Delta Drift: |S - \Delta_{LP}| > Threshold
2. Volatility: Thresholds expand during high volatility to reduce churn (fees).
3. Edge Proximity: Hedging logic changes when price approaches the range boundaries to prevent "buying high/selling low" behavior at the edges.

Troubleshooting

• Logs: Check logs/clp_manager.log and logs/clp_hedger.log first.
• Stuck Position: If a position is closed on-chain but {TARGET_DEX}_status.json says OPEN, manually edit the JSON status to CLOSED or delete the entry (with caution).
• RPC Errors: Ensure your RPC URLs in .env are active and have sufficient rate limits.