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.
tools/	Utility scripts, including the Git Agent for auto-backups.
logs/	Detailed logs for all processes.

Configuration

Environment Variables (.env)

Required variables for operation:

# Blockchain
MAINNET_RPC_URL=...      # Arbitrum
BNB_RPC_URL=...          # BNB Chain
BASE_RPC_URL=...         # Base
MAIN_WALLET_PRIVATE_KEY=...
MAIN_WALLET_ADDRESS=...

# Hyperliquid
HEDGER_PRIVATE_KEY=...   # Usually same as Main Wallet or specialized sub-account

# Telegram
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
TELEGRAM_MONITOR_ENABLED=True

Strategy Config (clp_config.py)

Key parameters controlling the bot's behavior:

• TARGET_DEX: Selects the active chain/profile (e.g., "UNISWAP_V3", "PANCAKESWAP_BNB").
• RANGE_WIDTH_PCT: Width of the LP position (e.g., 0.05 for +/- 5%).
• TARGET_INVESTMENT_AMOUNT: Notional size of the position in USD.
• SLIPPAGE_TOLERANCE: Max slippage for minting/swapping.

Usage

The system is designed to run continuously. It is recommended to use a process manager like pm2 or systemd, or simply run in separate terminal tabs.

1. Start the Manager:

   python clp_manager.py
   

   • Action: Will check for existing positions. If none, it prepares to open one based on config.

2. Start the Hedger:

   python clp_hedger.py
   

   • Action: Will read the position created by the Manager and open a corresponding short on Hyperliquid.

3. Start Monitoring (Optional):

   python telegram_monitor.py
   

Development & Git Agent

This project uses a custom Git Agent (tools/git_agent.py) for automated version control and backups.

• Auto-Backup: Runs hourly (if configured) to create backup branches (e.g., backup-2025-01-01-12).
• Manual Commit:

  python tools/git_agent.py --backup
  

• Status:

  python tools/git_agent.py --status
  

• Restoration: To restore a file from a backup branch:

  git checkout backup-BRANCH-NAME -- path/to/file.py
  

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.