wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.20__py3-none-any.whl

wayfinder_paths/strategies/basis_trading_strategy/README.md

@@ -1,213 +1,121 @@
 # Basis Trading Strategy
 
-Delta-neutral basis trading on Hyperliquid that captures funding rate payments through matched spot long and perpetual short positions.
+Delta-neutral basis trading on Hyperliquid for funding rate capture.
 
-## How It Works
+- **Module**: `wayfinder_paths.strategies.basis_trading_strategy.strategy.BasisTradingStrategy`
+- **Platform**: Hyperliquid
+- **Token**: USDC
 
-### Delta-Neutral Basis Trading
+## Overview
 
-The strategy maintains market neutrality by holding equal-and-opposite positions:
+This strategy captures funding rate payments through matched positions:
 - **Long Spot**: Buy the underlying asset (e.g., HYPE)
 - **Short Perp**: Short the perpetual contract for the same asset
 
-This creates a "basis trade" where:
-- Price movements cancel out (if HYPE goes up 10%, spot gains +10%, perp loses -10%)
-- You collect funding payments when longs pay shorts (positive funding rate)
-- The position is "delta-neutral" - profit comes from funding, not price direction
+Price movements cancel out, and profit comes from collecting funding payments when longs pay shorts.
+
+## How It Works
 
-### Position Sizing with Leverage
+### Position Sizing
 
-Given a deposit of `D` USDC and leverage `L`:
-- **Order Size**: `order_usd = D * (L / (L + 1))`
+Given deposit `D` USDC and leverage `L`:
+- **Order Size**: `D * (L / (L + 1))`
 - **Margin Reserved**: `D / (L + 1)`
 
 Example with $100 deposit at 2x leverage:
-- Order size: $100 * (2/3) = $66.67 per leg
-- Margin: $100 / 3 = $33.33
-
-## Opportunity Selection
+- Order size: $66.67 per leg
+- Margin: $33.33
 
-### 1. Candidate Discovery
+### Opportunity Selection
 
-The strategy scans all Hyperliquid markets to find spot-perp pairs:
-- Spots quoted in USDC that have matching perpetual contracts
-- Filters: minimum open interest, daily volume, order book depth
+1. **Discovery**: Scan Hyperliquid markets for spot-perp pairs
+2. **Historical Analysis**: Fetch up to 180 days of hourly funding/price data
+3. **Safe Leverage Calculation**: Stress test over rolling windows
+4. **Ranking**: Sort by expected APY = mean_funding * 24 * 365 * safe_leverage
 
-### 2. Historical Analysis (Backtesting)
+## Key Parameters
 
-For each candidate, fetches up to 180 days of hourly data:
-- **Funding rates**: Mean, volatility, negative hour fraction, worst 24h/7d sums
-- **Price candles**: Hourly closes and highs for volatility calculation
-
-### 3. Safe Leverage Calculation
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_leverage` | 3 | Maximum leverage allowed |
+| `lookback_days` | 180 | Days of historical data |
+| `confidence` | 0.975 | VaR confidence level (97.5%) |
+| `fee_eps` | 0.003 | Fee buffer (0.3%) |
+| `bootstrap_sims` | 50 | Monte Carlo simulations |
+| `MIN_DEPOSIT_USDC` | 50 | Minimum deposit |
 
-Uses a deterministic "stress test" approach over rolling historical windows:
+## Adapters Used
 
-```
-For each window of N hours:
-  - Track cumulative negative funding (adjusted for price run-up)
-  - Track maximum price run-up (high / entry - 1)
-  - Calculate buffer requirement:
-    buffer = maintenance_margin * (1 + runup) + runup + cum_neg_funding + fees
-```
+- **BalanceAdapter**: Wallet balances, ERC20 transfers
+- **LedgerAdapter**: Deposit/withdraw tracking
+- **TokenAdapter**: Token metadata
+- **HyperliquidAdapter**: Market data, order execution, account state
 
-The worst-case buffer across all windows determines the maximum safe leverage:
-- If buffer requirement is 50%, max safe leverage = 2x
-- If buffer requirement is 33%, max safe leverage = 3x
-
-### 4. Bootstrap Simulation (Optional)
-
-For additional statistical confidence, the strategy can run Monte Carlo simulations:
-- Resamples historical funding/price data in blocks (default 24h blocks)
-- Runs N simulations (configurable, e.g., 1000)
-- Calculates VaR at specified confidence level (default 97.5%)
-
-Configure via:
-```json
-{
-  "strategy_config": {
-    "bootstrap_sims": 1000,
-    "bootstrap_block_hours": 24
-  }
-}
-```
+## Actions
 
-### 5. Ranking
+### Analyze
 
-Opportunities are ranked by expected APY:
-```
-expected_apy = mean_hourly_funding * 24 * 365 * safe_leverage
+```bash
+poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
+    --action analyze --amount 1000 --config config.json
 ```
 
-## Position Management
-
-### Opening a Position
-
-1. Transfers USDC from main wallet to strategy wallet
-2. Bridges USDC to Hyperliquid via Arbitrum
-3. Splits between perp margin and spot
-4. Uses `PairedFiller` to atomically execute both legs (buy spot + sell perp)
-5. Places protective orders:
-   - **Stop-loss**: Triggers if price approaches liquidation (default 65% of distance)
-   - **Limit sell**: Closes spot if funding flips negative
-
-### Incremental Scaling
+Analyzes opportunities without opening positions.
 
-When you deposit additional funds with an existing position:
-- Detects idle capital (undeployed USDC on Hyperliquid)
-- Calculates additional units to add to each leg
-- Uses `PairedFiller` to atomically add to both positions
-- Maintains delta neutrality throughout
+### Deposit
 
-### Monitoring (update)
-
-The `update` action:
-1. Checks if position needs rebalancing (funding flipped, leverage drift, etc.)
-2. Deploys any idle capital via scale-up
-3. Verifies leg balance (spot amount ≈ perp amount)
-4. Updates stop-loss/limit orders if liquidation price changed
-
-### Closing a Position
+```bash
+poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
+    --action deposit --main-token-amount 100 --config config.json
+```
 
-1. Cancels all open orders
-2. Uses `PairedFiller` to atomically close both legs (sell spot + buy perp)
-3. Withdraws USDC from Hyperliquid to Arbitrum
-4. Sends funds back to main wallet
+- Transfers USDC from main wallet to strategy wallet
+- Bridges USDC to Hyperliquid via Arbitrum
+- Splits between perp margin and spot
+- Uses PairedFiller for atomic execution (buy spot + sell perp)
+- Places protective orders (stop-loss, limit sell)
 
-## CLI Usage
+### Update
 
 ```bash
-# Analyze opportunities for a $1000 deposit (doesn't open position)
 poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
-    --action analyze --amount 1000 --config config.json
+    --action update --config config.json
+```
 
-# Deposit $100 USDC from main wallet
-poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
-    --action deposit --main-token-amount 100 --config config.json
+- Checks if position needs rebalancing
+- Deploys idle capital via scale-up
+- Verifies leg balance (spot ≈ perp)
+- Updates stop-loss/limit orders if needed
 
-# Analyze and open/manage position
-poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
-    --action update --config config.json
+### Status
 
-# Check current status
+```bash
 poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
     --action status --config config.json
+```
 
-# Withdraw all funds back to main wallet
-poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
-    --action withdraw --config config.json
+### Withdraw
 
-# Generate batch snapshot of all opportunities
+```bash
 poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
-    --action snapshot --amount 1000 --config config.json
-```
-
-## Configuration
-
-```json
-{
-  "main_wallet": {
-    "address": "0x...",
-    "private_key": "0x..."
-  },
-  "strategy_wallet": {
-    "address": "0x...",
-    "private_key": "0x..."
-  },
-  "strategy_config": {
-    "max_leverage": 3,
-    "lookback_days": 180,
-    "bootstrap_sims": 0,
-    "bootstrap_block_hours": 24
-  }
-}
+    --action withdraw --config config.json
 ```
 
-### Parameters
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `max_leverage` | 3 | Maximum leverage allowed |
-| `lookback_days` | 180 | Days of historical data for analysis |
-| `confidence` | 0.975 | VaR confidence level (97.5%) |
-| `fee_eps` | 0.003 | Fee buffer (0.3%) |
-| `oi_floor` | 50 | Minimum open interest (USD) |
-| `day_vlm_floor` | 100,000 | Minimum daily volume (USD) |
-| `bootstrap_sims` | 50 | Monte Carlo simulations for VaR estimation |
-| `bootstrap_block_hours` | 24 | Block size for bootstrap resampling |
-
-### Thresholds
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `MIN_DEPOSIT_USDC` | 50 | Minimum deposit |
-| `LIQUIDATION_REBALANCE_THRESHOLD` | 0.65 | Stop-loss at 65% of liquidation distance |
-| `MIN_UNUSED_USD` | 5.0 | Minimum idle capital to trigger scale-up |
-| `UNUSED_REL_EPS` | 0.05 | Relative threshold (5% of deposit) |
-
-## Adapters Used
-
-- **BALANCE**: Wallet balances and ERC20 transfers
-- **LEDGER**: Transaction recording for deposit/withdraw tracking
-- **TOKEN**: Token metadata (decimals, addresses)
-- **HYPERLIQUID**: Market data, order execution, account state
+- Cancels all open orders
+- Uses PairedFiller to close both legs (sell spot + buy perp)
+- Withdraws USDC from Hyperliquid to Arbitrum
+- Sends funds back to main wallet
 
 ## Risk Factors
 
-1. **Funding Rate Flips**: Rates can turn negative, causing losses instead of gains
-2. **Liquidation Risk**: High leverage + adverse price movement can liquidate the perp
+1. **Funding Rate Flips**: Rates can turn negative
+2. **Liquidation Risk**: High leverage + adverse price movement
 3. **Execution Slippage**: Large orders may move the market
 4. **Withdrawal Delays**: Hyperliquid withdrawals take ~15-30 minutes
 5. **Smart Contract Risk**: Funds are held on Hyperliquid's L1
 
-## Architecture
+## Testing
 
-```
-BasisTradingStrategy
-├── HyperliquidAdapter       # Market data, account state
-├── LocalHyperliquidExecutor # Order execution (spot + perp)
-├── PairedFiller             # Atomic paired order execution
-├── BalanceAdapter           # Arbitrum wallet balances
-├── LedgerAdapter            # Deposit/withdraw tracking
-└── LocalEvmTxn              # Arbitrum transaction signing
+```bash
+poetry run pytest wayfinder_paths/strategies/basis_trading_strategy/ -v
 ```

wayfinder_paths/strategies/basis_trading_strategy/snapshot_mixin.py

@@ -1,9 +1,3 @@
-"""
-Basis trading snapshot/backtest helpers.
-
-Kept as a mixin so the main strategy file stays readable without changing behavior.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -38,7 +32,6 @@ class BasisSnapshotMixin:
         entry_cost_usd: float,
         exit_cost_usd: float,
     ) -> dict[str, Any]:
-        """Build the `safe[horizon]` entry matching the expected output shape."""
         L = max(1, int(leverage))
 
         depth_checks = depth_checks or {}
@@ -167,8 +160,6 @@ class BasisSnapshotMixin:
         bootstrap_block_hours: int | None = None,
         bootstrap_seed: int | None = None,
     ) -> dict[str, Any] | None:
-        """Return the top-ranked candidate with solver diagnostics for downstream use."""
-
         bootstrap_sims = int(
             self.DEFAULT_BOOTSTRAP_SIMS if bootstrap_sims is None else bootstrap_sims
         )
@@ -315,14 +306,6 @@ class BasisSnapshotMixin:
         bootstrap_block_hours: int | None = None,
         bootstrap_seed: int | None = None,
     ) -> dict[str, Any]:
-        """
-        Build an hourly, shareable snapshot of:
-        - performance table (net APY + churn stats)
-        - liquidity capacity per pair (max order/deposit supported by depth checks)
-
-        Intended for batch jobs: compute once, distribute to workers, and have workers
-        filter by user deposit size without re-hitting Hyperliquid APIs.
-        """
         stop_frac = float(
             stop_frac if stop_frac is not None else self.LIQUIDATION_REBALANCE_THRESHOLD
         )
@@ -681,7 +664,6 @@ class BasisSnapshotMixin:
         snapshot: dict[str, Any],
         deposit_usdc: float,
     ) -> list[dict[str, Any]]:
-        """Filter a batch snapshot for a specific deposit size."""
         if deposit_usdc <= 0:
             return []
 
@@ -754,12 +736,6 @@ class BasisSnapshotMixin:
         bootstrap_block_hours: int = 48,
         bootstrap_seed: int | None = None,
     ) -> dict[str, Any] | None:
-        """
-        Given a snapshot-selected opportunity, recompute a full single-coin backtest
-        + safe sizing for the user's exact deposit size using fresh market data.
-
-        This avoids running the full cross-asset scan on every worker.
-        """
         if deposit_usdc <= 0:
             return None