hyper/clp_hedger/GEMINI.md

Session Summary

Date: 2025-12-11

Objective(s): Fix API errors, enhance bot functionality with safety features (auto-close), and add leverage/funding monitoring.

Key Accomplishments:

• Fixed API Price Error: Implemented round_to_sig_figs to ensure limit prices meet Hyperliquid's 5 significant figure requirement, resolving the "Order has invalid price" error.
• Safety Shutdown: Added close_all_positions method and linked it to KeyboardInterrupt. The bot now automatically closes its hedge position when stopped manually.
• Leverage Management: Configured the bot to automatically set leverage to 4x Cross (LEVERAGE = 4) upon initialization.
• Market Monitoring: Added real-time Funding Rate display to the main logging loop using meta_and_asset_ctxs.

Key Files Modified:

• clp_hedger.py

Decisions Made:

• Used math.log10 based calculation for significant figures to ensure broad compatibility with asset price ranges.
• Implemented close_all_positions as a blocking call during shutdown to prioritize safety over an immediate exit.
• Hardcoded LEVERAGE in configuration for now, with a plan to potentially move to a config file later if needed.

Session Summary

Date: 2025-12-11

Objective(s): Implement a dynamic gap recovery strategy to neutralize initial losses from delayed hedging.

Key Accomplishments:

• Implemented "Gap Recovery" logic to dynamically adjust hedging based on current price relative to CLP ENTRY_PRICE and initial START_PRICE.
• Defined three distinct hedging zones:
  • NORMAL (below Entry): 100% hedge for safety.
  • RECOVERY (between Entry and Recovery Target): 0% hedge (naked long) to maximize recovery.
  • NORMAL (above Recovery Target): 100% hedge after gap is neutralized.
• Introduced PRICE_BUFFER_PCT and TIME_BUFFER_SECONDS to prevent trade churn around zone boundaries.

Key Files Modified:

• clp_hedger.py

Decisions Made:

• Chosen a dynamic START_PRICE capture at bot initialization to calculate the GAP.
• Opted for 0% hedge in the recovery zone for faster loss neutralization, acknowledging higher short-term risk.
• Implemented price and time buffers for robust mode switching.

Session Summary

Date: 2025-12-12

Objective(s): Develop a Uniswap V3 position manager script (formerly monitor) for Arbitrum, including fee collection, closing positions, and automated opening of new positions with auto-swapping. Refine hedging architecture for multi-position management.

Key Accomplishments:

• uniswap_manager.py (Unified Lifecycle Manager):
  • Transformed into a continuous lifecycle manager for AUTOMATIC positions.
  • Features:
    • Manages "AUTOMATIC" CLP positions (Open, Monitor, Close, Collect Fees).
    • Reads/Writes state to hedge_status.json.
    • Implemented auto-wrapping of native ETH to WETH when needed.
    • Includes robust auto-swapping (WETH <-> USDC) to balance tokens before minting.
    • Implemented robust event parsing using process_receipt to extract exact amount0 and amount1 from mint transactions.
    • Fixed web3.py v7 raw_transaction access across all transaction types.
    • Fixed Uniswap V3 Math precision in calculate_mint_amounts for accurate token splits.
  • Troubleshooting & Resolution:
    • Address Validation: Replaced hardcoded factory address with dynamic lookup.
    • ABI Mismatch: Updated NPM ABI with event definitions for IncreaseLiquidity and Transfer.
    • Typo/Indentation Errors: Resolved multiple NameError (target_tick_lower, w3_instance, position_details) and IndentationError issues during script refactoring.
    • JSON Update Failure: Fixed mint_new_position's log parsing for Token ID to correctly update hedge_status.json after successful mint.
• clp_scalper_hedger.py (Dedicated Automatic Hedger):
  • Created as a new script to hedge type: "AUTOMATIC" positions defined in hedge_status.json.
  • Uses SCALPER_AGENT_PK from .env.
  • Accurate L Calculation: Calculates Uniswap V3 liquidity (L) using amount0_initial or amount1_initial from hedge_status.json, falling back to a heuristic based on target_value if amounts are missing.
  • Dynamic Rebalance Threshold: Threshold adapts to 5% of the position's maximum ETH risk (max_potential_eth).
  • Minimum Order Value: Enforces a minimum order size of $10 to prevent dust trades and API errors.
• clp_hedger.py (Updated Manual Hedger):
  • Modified to load its configuration entirely from the type: "MANUAL" entry in hedge_status.json.
  • Respects the hedge_enabled flag from the JSON.
  • Idles if hedging is disabled or no manual position is found.
• hedge_status.json:
  • Becomes the central source of truth for all (MANUAL and AUTOMATIC) CLP positions, including their type, status, ranges, entry_price, target_value (for automatic), and hedge_enabled flag.
• .env File Location: All scripts updated to load .env from the current working directory (clp_hedger/).

Decisions Made:

• Adopted a multi-script architecture for clarity and separation of concerns (Manager vs. Hedgers).
• Used hedge_status.json as the centralized state manager for all CLP positions.
• Implemented robust error handling and debugging throughout the development process.
• Ensured clp_scalper_hedger.py is resilient to missing initial amount data in hedge_status.json by implementing fallback L calculation methods.