wayfinder-paths 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

wayfinder_paths/core/clients/LedgerClient.py

@@ -176,7 +176,7 @@ class LedgerClient:
             "offset": offset,
         }
 
-    async def get_strategy_net_deposit(self, *, wallet_address: str) -> NetDeposit:
+    async def get_strategy_net_deposit(self, *, wallet_address: str) -> float:
         """
         Calculate the net deposit (deposits - withdrawals) for a strategy wallet.
 
@@ -210,12 +210,7 @@ class LedgerClient:
 
         net_deposit = total_deposits - total_withdrawals
 
-        return {
-            "net_deposit": str(net_deposit),
-            "total_deposits": str(total_deposits),
-            "total_withdrawals": str(total_withdrawals),
-            "wallet_address": wallet_address,
-        }
+        return float(net_deposit)
 
     async def get_strategy_latest_transactions(
         self, *, wallet_address: str, limit: int = 10

wayfinder_paths/core/clients/PoolClient.py

@@ -85,22 +85,6 @@ class PoolClient(WayfinderClient):
         data = response.json()
         return data.get("data", data)
 
-    async def get_all_pools(self, *, merge_external: bool | None = None) -> PoolList:
-        """
-        Fetch all pools.
-
-        Example:
-        GET /api/v1/public/pools/?merge_external=false
-        """
-        url = f"{self.api_base_url}/public/pools/"
-        params: dict[str, Any] = {}
-        if merge_external is not None:
-            params["merge_external"] = "true" if merge_external else "false"
-        response = await self._request("GET", url, params=params, headers={})
-        response.raise_for_status()
-        data = response.json()
-        return data.get("data", data)
-
     async def get_llama_matches(self) -> dict[str, LlamaMatch]:
         """
         Fetch Llama matches for pools.

wayfinder_paths/core/clients/WalletClient.py

@@ -92,30 +92,3 @@ class WalletClient(WayfinderClient):
         response = await self._authed_request("POST", url, json=payload)
         data = response.json()
         return data.get("data", data)
-
-    async def get_all_enriched_token_balances_for_wallet(
-        self,
-        *,
-        wallet_address: str,
-        enrich: bool = True,
-        from_cache: bool = False,
-        add_llama: bool = True,
-    ) -> EnrichedBalances:
-        """
-        Fetch all token balances for a wallet with enrichment via the enriched endpoint.
-
-        Mirrors POST /api/v1/public/balances/enriched/
-        """
-        url = f"{self.api_base_url}/public/balances/enriched/"
-        payload = {
-            "wallet_address": wallet_address,
-            "enrich": enrich,
-            "from_cache": from_cache,
-            "add_llama": add_llama,
-        }
-        try:
-            response = await self._authed_request("POST", url, json=payload)
-            data = response.json()
-            return data.get("data", data)
-        except Exception:
-            raise

wayfinder_paths/core/clients/protocols.py

@@ -20,7 +20,6 @@ if TYPE_CHECKING:
         StableMarket,
     )
     from wayfinder_paths.core.clients.LedgerClient import (
-        NetDeposit,
         StrategyTransactionList,
         TransactionRecord,
     )
@@ -36,7 +35,6 @@ if TYPE_CHECKING:
     )
     from wayfinder_paths.core.clients.TransactionClient import TransactionPayload
     from wayfinder_paths.core.clients.WalletClient import (
-        EnrichedBalances,
         PoolBalance,
         TokenBalance,
     )
@@ -113,7 +111,7 @@ class LedgerClientProtocol(Protocol):
         """Fetch a paginated list of transactions for a given strategy wallet"""
         ...
 
-    async def get_strategy_net_deposit(self, *, wallet_address: str) -> NetDeposit:
+    async def get_strategy_net_deposit(self, *, wallet_address: str) -> float:
         """Fetch the net deposit (deposits - withdrawals) for a strategy"""
         ...
 
@@ -187,17 +185,6 @@ class WalletClientProtocol(Protocol):
         """Fetch a wallet's LP/share balance for a given pool address and chain"""
         ...
 
-    async def get_all_enriched_token_balances_for_wallet(
-        self,
-        *,
-        wallet_address: str,
-        enrich: bool = True,
-        from_cache: bool = False,
-        add_llama: bool = True,
-    ) -> EnrichedBalances:
-        """Fetch all token balances for a wallet with enrichment"""
-        ...
-
 
 class TransactionClientProtocol(Protocol):
     """Protocol for transaction operations"""
@@ -226,10 +213,6 @@ class PoolClientProtocol(Protocol):
         """Fetch pools by comma-separated pool ids"""
         ...
 
-    async def get_all_pools(self, *, merge_external: bool | None = None) -> PoolList:
-        """Fetch all pools"""
-        ...
-
     async def get_llama_matches(self) -> dict[str, LlamaMatch]:
         """Fetch Llama matches for pools"""
         ...
@@ -300,3 +283,106 @@ class SimulationClientProtocol(Protocol):
     ) -> SimulationResult:
         """Simulate token swap operation"""
         ...
+
+
+class HyperliquidExecutorProtocol(Protocol):
+    """Protocol for Hyperliquid order execution operations."""
+
+    async def place_market_order(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        slippage: float,
+        size: float,
+        address: str,
+        reduce_only: bool = False,
+        cloid: Any = None,
+        builder: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Place a market order."""
+        ...
+
+    async def cancel_order(
+        self,
+        *,
+        asset_id: int,
+        order_id: int,
+        address: str,
+    ) -> dict[str, Any]:
+        """Cancel an open order."""
+        ...
+
+    async def update_leverage(
+        self,
+        *,
+        asset_id: int,
+        leverage: int,
+        is_cross: bool,
+        address: str,
+    ) -> dict[str, Any]:
+        """Update leverage for an asset."""
+        ...
+
+    async def transfer_spot_to_perp(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Transfer USDC from spot to perp balance."""
+        ...
+
+    async def transfer_perp_to_spot(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Transfer USDC from perp to spot balance."""
+        ...
+
+    async def place_stop_loss(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        trigger_price: float,
+        size: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Place a stop-loss order."""
+        ...
+
+    async def place_limit_order(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        price: float,
+        size: float,
+        address: str,
+        reduce_only: bool = False,
+        builder: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Place a limit order."""
+        ...
+
+    async def withdraw(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Withdraw USDC from Hyperliquid to Arbitrum."""
+        ...
+
+    async def approve_builder_fee(
+        self,
+        *,
+        builder: str,
+        max_fee_rate: str,
+        address: str,
+    ) -> dict[str, Any]:
+        """Approve a builder fee for the user."""
+        ...

wayfinder_paths/scripts/make_wallets.py

@@ -62,8 +62,17 @@ def main():
         default=None,
         help="Create a wallet with a custom label (e.g., strategy name). If not provided, auto-generates labels.",
     )
+    parser.add_argument(
+        "--default",
+        action="store_true",
+        help="Create a default 'main' wallet if none exists (used by CI)",
+    )
     args = parser.parse_args()
 
+    # --default is equivalent to -n 1 (create main wallet if needed)
+    if args.default and args.n == 0 and not args.label:
+        args.n = 1
+
     args.out_dir.mkdir(parents=True, exist_ok=True)
 
     # Load existing wallets

wayfinder_paths/scripts/run_strategy.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _load_wallets(path: Path) -> list[dict[str, Any]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a list in {path}")
+    return [w for w in data if isinstance(w, dict)]
+
+
+def _find_wallet(wallets: list[dict[str, Any]], label: str) -> dict[str, Any]:
+    for w in wallets:
+        if w.get("label") == label:
+            return w
+    raise ValueError(f"Wallet label not found in wallets.json: {label}")
+
+
+def _get_strategy_class(strategy: str):
+    if strategy == "basis_trading_strategy":
+        from wayfinder_paths.strategies.basis_trading_strategy.strategy import (
+            BasisTradingStrategy,
+        )
+
+        return BasisTradingStrategy
+
+    if strategy == "hyperlend_stable_yield_strategy":
+        from wayfinder_paths.strategies.hyperlend_stable_yield_strategy.strategy import (
+            HyperlendStableYieldStrategy,
+        )
+
+        return HyperlendStableYieldStrategy
+
+    raise ValueError(f"Unknown strategy: {strategy}")
+
+
+async def _run(args: argparse.Namespace) -> int:
+    repo_root = Path(__file__).resolve().parents[2]
+    wallets_path = (
+        Path(args.wallets).resolve() if args.wallets else repo_root / "wallets.json"
+    )
+    wallets = _load_wallets(wallets_path)
+
+    main_wallet = _find_wallet(wallets, args.main_wallet_label)
+    strategy_wallet = _find_wallet(wallets, args.strategy_wallet_label)
+
+    strategy_class = _get_strategy_class(args.strategy)
+    s = strategy_class(
+        {
+            "main_wallet": main_wallet,
+            "strategy_wallet": strategy_wallet,
+        },
+        simulation=args.simulation,
+    )
+
+    await s.setup()
+
+    if args.command == "deposit":
+        ok, msg = await s.deposit(
+            main_token_amount=float(args.usdc), gas_token_amount=float(args.eth)
+        )
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "update":
+        ok, msg = await s.update()
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "withdraw":
+        ok, msg = await s.withdraw(
+            amount=float(args.amount) if args.amount is not None else None
+        )
+        print(msg)
+        return 0 if ok else 1
+
+    if args.command == "status":
+        st = await s.status()
+        print(json.dumps(st, indent=2, sort_keys=True))
+        return 0
+
+    raise ValueError(f"Unknown command: {args.command}")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        description="Run a strategy locally (deposit/update/withdraw/status)."
+    )
+    p.add_argument(
+        "--strategy",
+        default="basis_trading_strategy",
+        choices=["basis_trading_strategy", "hyperlend_stable_yield_strategy"],
+    )
+    p.add_argument(
+        "--wallets", default=None, help="Path to wallets.json (default: repo root)"
+    )
+    p.add_argument("--main-wallet-label", default="main")
+    p.add_argument("--strategy-wallet-label", default="basis_trading_strategy")
+    p.add_argument("--simulation", action="store_true")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    dep = sub.add_parser("deposit")
+    dep.add_argument("--usdc", required=True, type=float)
+    dep.add_argument("--eth", default=0.0, type=float)
+
+    sub.add_parser("update")
+
+    wd = sub.add_parser("withdraw")
+    wd.add_argument("--amount", default=None, type=float)
+
+    sub.add_parser("status")
+
+    args = p.parse_args()
+    return asyncio.run(_run(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wayfinder_paths/strategies/basis_trading_strategy/README.md

@@ -0,0 +1,213 @@
+# Basis Trading Strategy
+
+Delta-neutral basis trading on Hyperliquid that captures funding rate payments through matched spot long and perpetual short positions.
+
+## How It Works
+
+### Delta-Neutral Basis Trading
+
+The strategy maintains market neutrality by holding equal-and-opposite 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
+
+### Position Sizing with Leverage
+
+Given a deposit of `D` USDC and leverage `L`:
+- **Order Size**: `order_usd = 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
+
+### 1. Candidate Discovery
+
+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
+
+### 2. Historical Analysis (Backtesting)
+
+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
+
+Uses a deterministic "stress test" approach over rolling historical windows:
+
+```
+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
+```
+
+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
+  }
+}
+```
+
+### 5. Ranking
+
+Opportunities are ranked by expected APY:
+```
+expected_apy = mean_hourly_funding * 24 * 365 * safe_leverage
+```
+
+## 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
+
+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
+
+### 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
+
+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
+
+## CLI Usage
+
+```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
+
+# 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
+
+# Analyze and open/manage position
+poetry run python wayfinder_paths/run_strategy.py basis_trading_strategy \
+    --action update --config config.json
+
+# Check current status
+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
+
+# Generate batch snapshot of all opportunities
+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
+  }
+}
+```
+
+### 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
+
+## 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
+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
+
+```
+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
+```

wayfinder_paths/strategies/basis_trading_strategy/__init__.py

@@ -0,0 +1,3 @@
+from .strategy import BasisTradingStrategy
+
+__all__ = ["BasisTradingStrategy"]

wayfinder_paths/strategies/basis_trading_strategy/constants.py

@@ -0,0 +1 @@
+USDC_ARBITRUM_TOKEN_ID = "usd-coin-arbitrum"

wayfinder_paths/strategies/basis_trading_strategy/examples.json

@@ -0,0 +1,16 @@
+{
+  "smoke": {
+    "deposit": {"main_token_amount": 100, "gas_token_amount": 0.0001},
+    "update": {},
+    "status": {},
+    "withdraw": {}
+  },
+  "min_deposit_fail": {
+    "deposit": {"main_token_amount": 10, "gas_token_amount": 0.0},
+    "expect": {"success": false, "message_contains": "Minimum deposit"}
+  },
+  "analysis_only": {
+    "deposit": {"main_token_amount": 200, "gas_token_amount": 0.0001},
+    "update": {}
+  }
+}

wayfinder_paths/strategies/basis_trading_strategy/manifest.yaml

@@ -0,0 +1,23 @@
+schema_version: "0.1"
+entrypoint: "wayfinder_paths.strategies.basis_trading_strategy.strategy.BasisTradingStrategy"
+permissions:
+  policy: |
+    (wallet.id == 'FORMAT_WALLET_ID') AND (
+      # Allow Hyperliquid EIP-712 order actions
+      (action.type == 'hyperliquid_order') OR
+      (action.type == 'hyperliquid_cancel') OR
+      (action.type == 'hyperliquid_transfer') OR
+      # Allow USDC transfers to Hyperliquid bridge
+      (action.type == 'erc20_transfer' AND action.to == '0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7') OR
+      # Allow USDC withdraw to main wallet
+      (action.type == 'erc20_transfer' AND action.to == main_wallet.address)
+    )
+adapters:
+  - name: "BALANCE"
+    capabilities: ["wallet_read", "wallet_transfer"]
+  - name: "LEDGER"
+    capabilities: ["ledger.read", "ledger.write", "strategy.transactions"]
+  - name: "TOKEN"
+    capabilities: ["token.read"]
+  - name: "HYPERLIQUID"
+    capabilities: ["market.read", "market.meta", "market.funding", "market.candles", "market.orderbook", "order.execute", "order.cancel", "position.manage", "transfer"]