96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# GEMINI Project Context: Uniswap Auto CLP & Hedger
|
|
|
|
**Last Updated:** January 6, 2026
|
|
**Project:** Uniswap V3 Automated Concentrated Liquidity (CLP) & Delta-Neutral Hedger
|
|
**Operating System:** Windows (win32)
|
|
|
|
## 1. Project Overview
|
|
This project is an automated high-frequency trading system designed to:
|
|
1. **Provide Concentrated Liquidity (CLP):** Automatically manages positions on Uniswap V3 and its forks (Aerodrome, PancakeSwap) to capture trading fees.
|
|
2. **Hedge Delta Exposure:** Simultaneously executes delta-neutral hedges on Hyperliquid (Perp DEX) to neutralize the price risk of the underlying assets (Impermanent Loss protection).
|
|
|
|
The system operates as a **Delta-Zero Yield Farmer**, effectively capturing LP fees with reduced market exposure.
|
|
|
|
## 2. System Architecture
|
|
The system consists of two main independent Python processes that coordinate via a shared JSON state file.
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[clp_manager.py] -- Reads/Writes --> C{status.json}
|
|
B[clp_hedger.py] -- Reads --> C
|
|
A -- On-Chain Tx --> D[EVM Chain (Base/Arb)]
|
|
B -- API Calls --> E[Hyperliquid Perp]
|
|
F[telegram_monitor.py] -- Reads --> C
|
|
F -- Alerts --> G[Telegram]
|
|
```
|
|
|
|
### Components
|
|
* **`clp_manager.py` (The Strategist):**
|
|
* **Role:** Active Liquidity Provision on EVM chains.
|
|
* **Actions:** Mints new positions, monitors ranges, auto-closes out-of-range positions, collects fees, and handles auto-wrapping/swapping.
|
|
* **State:** Updates `{TARGET_DEX}_status.json` with entry price, token amounts, and range details.
|
|
|
|
* **`clp_hedger.py` (The Guardian):**
|
|
* **Role:** Delta Neutralization on Hyperliquid.
|
|
* **Actions:** Calculates the LP's real-time delta. Executes short/long trades to maintain `Net Delta ≈ 0`.
|
|
* **Features:**
|
|
* **Dynamic Thresholds:** Adjusts rebalance sensitivity based on market volatility (StdDev).
|
|
* **Fishing Orders:** Places passive maker orders to capture spread and rebates.
|
|
* **Edge Protection:** Reduces hedging logic near range edges to prevent "buying high/selling low".
|
|
|
|
* **`clp_config.py`:** Centralized configuration. Uses `TARGET_DEX` env var to switch between profiles (e.g., `UNISWAP_V3`, `AERODROME_BASE_CL`).
|
|
|
|
## 3. Key Files & Directories
|
|
|
|
| File/Directory | Description |
|
|
| :--- | :--- |
|
|
| **`clp_manager.py`** | Main entry point for the LP Manager. |
|
|
| **`clp_hedger.py`** | Main entry point for the Delta Hedger. |
|
|
| **`clp_config.py`** | Configuration profiles and strategy settings. |
|
|
| **`requirements.txt`** | Python dependencies (`web3`, `hyperliquid-python-sdk`, `dotenv`). |
|
|
| **`doc/`** | Extensive documentation (`CHANGELOG.md`, `UNISWAP_MANAGER_WORKFLOW.md`). |
|
|
| **`florida/`** | A secondary deployment or research directory containing specific strategy configurations. |
|
|
| **`tools/`** | Utility scripts (e.g., `git_agent.py`, `universal_swapper.py`). |
|
|
| **`logs/`** | Runtime logs. |
|
|
| **`*_status.json`** | The shared state file (IPC). Specific name depends on `TARGET_DEX`. |
|
|
|
|
## 4. Setup & Usage
|
|
|
|
### Prerequisites
|
|
* Python 3.10+
|
|
* Hyperliquid Account & API Key (in `.env`)
|
|
* EVM Wallet Private Key (in `.env`)
|
|
* RPC URLs (in `.env`)
|
|
|
|
### Installation
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Configuration
|
|
1. Create a `.env` file (see `.env.example` in `tools/`).
|
|
2. Edit `clp_config.py` or set `TARGET_DEX` environment variable to choose a profile (e.g., `AERODROME_WETH-USDC_008`).
|
|
|
|
### Running the System
|
|
You typically run the Manager and Hedger in separate terminals:
|
|
|
|
**Terminal 1 (Manager):**
|
|
```bash
|
|
python clp_manager.py
|
|
```
|
|
|
|
**Terminal 2 (Hedger):**
|
|
```bash
|
|
python clp_hedger.py
|
|
```
|
|
|
|
## 5. Recent Developments (Jan 2026)
|
|
* **Low Volatility Optimization:** Increased base rebalance thresholds (from 5% to 8%) to reduce churn in sideways markets.
|
|
* **Fishing Orders:** Implemented passive limit orders to profit from rebalancing.
|
|
* **Shadow Logging:** The system now logs "Shadow" trades to simulate maker order performance vs taker execution.
|
|
* **Dynamic Edge Proximity:** Safety buffers now scale with position size.
|
|
|
|
## 6. Active Context
|
|
* **Current Profile:** The root directory contains `AERODROME_WETH-USDC_008_status.json`, indicating an active or recent session on **Aerodrome (Base Chain)**.
|
|
* **Workflows:** Refer to `doc/UNISWAP_MANAGER_WORKFLOW.md` for detailed state machine logic of the Manager.
|