# 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:
```env
# 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:**
    ```bash
    python clp_manager.py
    ```
    *   *Action:* Will check for existing positions. If none, it prepares to open one based on config.

2.  **Start the Hedger:**
    ```bash
    python clp_hedger.py
    ```
    *   *Action:* Will read the position created by the Manager and open a corresponding short on Hyperliquid.

3.  **Start Monitoring (Optional):**
    ```bash
    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:**
    ```bash
    python tools/git_agent.py --backup
    ```
*   **Status:**
    ```bash
    python tools/git_agent.py --status
    ```
*   **Restoration:**
    To restore a file from a backup branch:
    ```bash
    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.