wayfinder-paths 0.1.11__tar.gz → 0.1.14__tar.gz

wayfinder_paths-0.1.11/README.md → wayfinder_paths-0.1.14/PKG-INFO

@@ -1,3 +1,24 @@
+Metadata-Version: 2.1
+Name: wayfinder-paths
+Version: 0.1.14
+Summary: Wayfinder Path: strategies and adapters
+Author: Wayfinder
+Author-email: dev@wayfinder.ai
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiohttp (>=3.13.0,<4.0.0)
+Requires-Dist: eth-account (>=0.13.7,<0.14.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: hyperliquid-python-sdk (>=0.21.0,<0.22.0)
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: pydantic (>=2.11.9,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: web3 (>=7.13.0,<8.0.0)
+Description-Content-Type: text/markdown
+
 # 🔐 Wayfinder Paths
 
 [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
@@ -20,7 +41,7 @@ curl -sSL https://install.python-poetry.org | python3 -
 poetry install
 
 # ⚠️ Generate test wallets FIRST (required!)
-# This creates wallets.json with a main wallet for local testing
+# This creates config.json with a main wallet for local testing
 just create-wallets
 # Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
@@ -69,8 +90,7 @@ wayfinder_paths/
 │   ├── config.example.json       # Example configuration
 │   ├── scripts/                  # Utility scripts
 │   └── run_strategy.py           # Strategy runner script
-├── config.json                   # Your local config (created by you)
-├── wallets.json                  # Generated dev wallets
+├── config.json                   # Your local config with credentials and wallets
 ├── pyproject.toml                # Poetry configuration
 └── README.md                     # This file
 ```
@@ -196,63 +216,28 @@ See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
 
 ### Authentication
 
-Wayfinder Paths supports two authentication methods:
-
-#### 1. Service Account Authentication (API Key)
-
-For backend services and automated systems with higher rate limits:
-
-**Option A: Pass to Strategy Constructor**
-
-```python
-from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
-
-strategy = StablecoinYieldStrategy(
-    config={...},
-    api_key="sk_live_abc123..."  # API key is auto-discovered by all clients
-)
-```
+Wayfinder Paths uses API key authentication via the `X-API-KEY` header.
 
-**Option B: Add to config.json**
+**Add API key to config.json:**
 
 ```json
 {
-  "user": {
-    "api_key": "sk_live_abc123..."
-  },
   "system": {
-    "api_key": "sk_live_abc123..." // Alternative: system-level API key
-  }
-}
-```
-
-**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key)
-
-**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This allows flexible credential loading.
-
-#### 2. Personal Access Authentication (OAuth)
-
-For standalone SDK users with username/password:
-
-```json
-{
-  "user": {
-    "username": "your_username",
-    "password": "your_password",
-    "refresh_token": null // Optional: use refresh token instead
+    "api_key": "sk_live_abc123...",
+    "api_base_url": "https://wayfinder.ai/api/v1",
+    "wallets_path": "wallets.json"
   }
 }
 ```
 
 **How It Works:**
 
-- API keys are automatically discovered by all clients (no need to pass explicitly)
-- When an API key is available, it's used for all API requests (including public endpoints) for rate limiting
-- If no API key is found, the system falls back to OAuth authentication
-- All clients created by adapters automatically inherit the API key discovery mechanism
-- API keys in `config.json` are loaded directly by `WayfinderClient._load_config_credentials()` from `user.api_key` or `system.api_key`, not stored in the `UserConfig` or `SystemConfig` dataclasses
+- API key is automatically loaded from `system.api_key` in config.json
+- The API key is sent as the `X-API-KEY` header on all API requests
+- All clients automatically include the API key header
+- No need to pass API keys explicitly to strategies or clients
 
-See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed authentication documentation.
+See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed configuration documentation.
 
 ## 🔌 Creating Adapters
 
@@ -279,7 +264,7 @@ class MyAdapter(BaseAdapter):
 
     async def get_pools(self, pool_ids: list[str]):
         data = await self.pool_client.get_pools_by_ids(
-            pool_ids=",".join(pool_ids), merge_external=True
+            pool_ids=pool_ids
         )
         return (True, data)
 ```
@@ -320,7 +305,7 @@ class MyStrategy(Strategy):
             return (False, "Nothing to deposit")
 
         success, _ = await self.balance_adapter.get_balance(
-            token_id=self.config.get("token_id"),
+            query=self.config.get("token_id"),
             wallet_address=self.config.get("main_wallet", {}).get("address"),
         )
         if not success:
@@ -337,7 +322,7 @@ class MyStrategy(Strategy):
     async def _status(self) -> StatusDict:
         """Report balances back to the runner"""
         success, balance = await self.balance_adapter.get_balance(
-            token_id=self.config.get("token_id"),
+            query=self.config.get("token_id"),
             wallet_address=self.config.get("strategy_wallet", {}).get("address"),
         )
         return {
@@ -468,7 +453,7 @@ poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --de
 
 ### Wallet Generation for Testing
 
-**Before running any strategies, generate test wallets.** This creates `wallets.json` in the repository root with throwaway wallets for local testing:
+**Before running any strategies, generate test wallets.** This creates `config.json` in the repository root with throwaway wallets for local testing:
 
 ```bash
 # Essential: Create main wallet for testing
@@ -478,8 +463,8 @@ just create-wallets
 
 This creates:
 
-- `main` wallet - your main wallet for testing (labeled "main" in wallets.json)
-- `wallets.json` - wallet addresses and private keys for local testing
+- `main` wallet - your main wallet for testing (labeled "main" in config.json)
+- `config.json` - wallet addresses and private keys for local testing
 
 **Note:** Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`. For manual creation, use `just create-wallet "strategy_name"` or `poetry run python wayfinder_paths/scripts/make_wallets.py --label "strategy_name"`.
 
@@ -515,9 +500,9 @@ cp wayfinder_paths/config.example.json config.json
 #   - user.username: Your Wayfinder username
 #   - user.password: Your Wayfinder password
 #   - OR user.refresh_token: Your refresh token
-#   - system.wallets_path: Path to wallets.json (default: "wallets.json")
+#   - system.wallets_path: Path to config.json (default: "config.json")
 #
-# Wallet addresses are auto-loaded from wallets.json by default.
+# Wallet addresses are auto-loaded from config.json by default.
 # Then run with:
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
 ```
@@ -642,3 +627,4 @@ Need help or want to discuss strategies? Join our [Discord](https://discord.gg/f
 MIT License - see [LICENSE](LICENSE) file for details
 
 🚀 **Happy Wayfinding!**
+

wayfinder_paths-0.1.11/PKG-INFO → wayfinder_paths-0.1.14/README.md

@@ -1,26 +1,3 @@
-Metadata-Version: 2.1
-Name: wayfinder-paths
-Version: 0.1.11
-Summary: Wayfinder Path: strategies and adapters
-Author: Wayfinder
-Author-email: dev@wayfinder.ai
-Requires-Python: >=3.12,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: aiohttp (>=3.13.0,<4.0.0)
-Requires-Dist: eth-account (>=0.13.7,<0.14.0)
-Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: hyperliquid-python-sdk (>=0.21.0,<0.22.0)
-Requires-Dist: loguru (>=0.7.3,<0.8.0)
-Requires-Dist: numpy (>=1.26.0,<2.0.0)
-Requires-Dist: pandas (>=2.2.0,<3.0.0)
-Requires-Dist: pydantic (>=2.11.9,<3.0.0)
-Requires-Dist: pydantic-settings (>=2.7.0,<3.0.0)
-Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
-Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
-Requires-Dist: web3 (>=7.13.0,<8.0.0)
-Description-Content-Type: text/markdown
-
 # 🔐 Wayfinder Paths
 
 [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
@@ -43,7 +20,7 @@ curl -sSL https://install.python-poetry.org | python3 -
 poetry install
 
 # ⚠️ Generate test wallets FIRST (required!)
-# This creates wallets.json with a main wallet for local testing
+# This creates config.json with a main wallet for local testing
 just create-wallets
 # Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
@@ -92,8 +69,7 @@ wayfinder_paths/
 │   ├── config.example.json       # Example configuration
 │   ├── scripts/                  # Utility scripts
 │   └── run_strategy.py           # Strategy runner script
-├── config.json                   # Your local config (created by you)
-├── wallets.json                  # Generated dev wallets
+├── config.json                   # Your local config with credentials and wallets
 ├── pyproject.toml                # Poetry configuration
 └── README.md                     # This file
 ```
@@ -219,63 +195,28 @@ See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
 
 ### Authentication
 
-Wayfinder Paths supports two authentication methods:
-
-#### 1. Service Account Authentication (API Key)
-
-For backend services and automated systems with higher rate limits:
-
-**Option A: Pass to Strategy Constructor**
-
-```python
-from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
-
-strategy = StablecoinYieldStrategy(
-    config={...},
-    api_key="sk_live_abc123..."  # API key is auto-discovered by all clients
-)
-```
+Wayfinder Paths uses API key authentication via the `X-API-KEY` header.
 
-**Option B: Add to config.json**
+**Add API key to config.json:**
 
 ```json
 {
-  "user": {
-    "api_key": "sk_live_abc123..."
-  },
   "system": {
-    "api_key": "sk_live_abc123..." // Alternative: system-level API key
-  }
-}
-```
-
-**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key)
-
-**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This allows flexible credential loading.
-
-#### 2. Personal Access Authentication (OAuth)
-
-For standalone SDK users with username/password:
-
-```json
-{
-  "user": {
-    "username": "your_username",
-    "password": "your_password",
-    "refresh_token": null // Optional: use refresh token instead
+    "api_key": "sk_live_abc123...",
+    "api_base_url": "https://wayfinder.ai/api/v1",
+    "wallets_path": "wallets.json"
   }
 }
 ```
 
 **How It Works:**
 
-- API keys are automatically discovered by all clients (no need to pass explicitly)
-- When an API key is available, it's used for all API requests (including public endpoints) for rate limiting
-- If no API key is found, the system falls back to OAuth authentication
-- All clients created by adapters automatically inherit the API key discovery mechanism
-- API keys in `config.json` are loaded directly by `WayfinderClient._load_config_credentials()` from `user.api_key` or `system.api_key`, not stored in the `UserConfig` or `SystemConfig` dataclasses
+- API key is automatically loaded from `system.api_key` in config.json
+- The API key is sent as the `X-API-KEY` header on all API requests
+- All clients automatically include the API key header
+- No need to pass API keys explicitly to strategies or clients
 
-See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed authentication documentation.
+See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed configuration documentation.
 
 ## 🔌 Creating Adapters
 
@@ -302,7 +243,7 @@ class MyAdapter(BaseAdapter):
 
     async def get_pools(self, pool_ids: list[str]):
         data = await self.pool_client.get_pools_by_ids(
-            pool_ids=",".join(pool_ids), merge_external=True
+            pool_ids=pool_ids
         )
         return (True, data)
 ```
@@ -343,7 +284,7 @@ class MyStrategy(Strategy):
             return (False, "Nothing to deposit")
 
         success, _ = await self.balance_adapter.get_balance(
-            token_id=self.config.get("token_id"),
+            query=self.config.get("token_id"),
             wallet_address=self.config.get("main_wallet", {}).get("address"),
         )
         if not success:
@@ -360,7 +301,7 @@ class MyStrategy(Strategy):
     async def _status(self) -> StatusDict:
         """Report balances back to the runner"""
         success, balance = await self.balance_adapter.get_balance(
-            token_id=self.config.get("token_id"),
+            query=self.config.get("token_id"),
             wallet_address=self.config.get("strategy_wallet", {}).get("address"),
         )
         return {
@@ -491,7 +432,7 @@ poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --de
 
 ### Wallet Generation for Testing
 
-**Before running any strategies, generate test wallets.** This creates `wallets.json` in the repository root with throwaway wallets for local testing:
+**Before running any strategies, generate test wallets.** This creates `config.json` in the repository root with throwaway wallets for local testing:
 
 ```bash
 # Essential: Create main wallet for testing
@@ -501,8 +442,8 @@ just create-wallets
 
 This creates:
 
-- `main` wallet - your main wallet for testing (labeled "main" in wallets.json)
-- `wallets.json` - wallet addresses and private keys for local testing
+- `main` wallet - your main wallet for testing (labeled "main" in config.json)
+- `config.json` - wallet addresses and private keys for local testing
 
 **Note:** Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`. For manual creation, use `just create-wallet "strategy_name"` or `poetry run python wayfinder_paths/scripts/make_wallets.py --label "strategy_name"`.
 
@@ -538,9 +479,9 @@ cp wayfinder_paths/config.example.json config.json
 #   - user.username: Your Wayfinder username
 #   - user.password: Your Wayfinder password
 #   - OR user.refresh_token: Your refresh token
-#   - system.wallets_path: Path to wallets.json (default: "wallets.json")
+#   - system.wallets_path: Path to config.json (default: "config.json")
 #
-# Wallet addresses are auto-loaded from wallets.json by default.
+# Wallet addresses are auto-loaded from config.json by default.
 # Then run with:
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
 ```
@@ -665,4 +606,3 @@ Need help or want to discuss strategies? Join our [Discord](https://discord.gg/f
 MIT License - see [LICENSE](LICENSE) file for details
 
 🚀 **Happy Wayfinding!**
-

{wayfinder_paths-0.1.11 → wayfinder_paths-0.1.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wayfinder-paths"
-version = "0.1.11"
+version = "0.1.14"
 description = "Wayfinder Path: strategies and adapters"
 readme = "README.md"
 authors = ["Wayfinder <dev@wayfinder.ai>"]
@@ -14,10 +14,8 @@ loguru = "^0.7.3"
 httpx = "^0.28.1"
 pyyaml = "^6.0.1"
 pydantic = "^2.11.9"
-pydantic-settings = "^2.7.0"
 web3 = "^7.13.0"
 eth-account = "^0.13.7"
-python-dotenv = "^1.1.1"
 aiohttp = "^3.13.0"
 numpy = "^1.26.0"
 pandas = "^2.2.0"
@@ -34,6 +32,7 @@ ruff = "^0.13.2"
 bandit = "^1.7.5"
 safety = "^2.3.5"
 twine = "^6.2.0"
+vulture = "^2.14"
 
 [tool.ruff]
 target-version = "py312"

{wayfinder_paths-0.1.11 → wayfinder_paths-0.1.14}/wayfinder_paths/adapters/balance_adapter/README.md

@@ -23,24 +23,23 @@ balance = BalanceAdapter(config, web3_service=web3_service)
 
 ## API surface
 
-### `get_balance(token_id: str, wallet_address: str)`
-Returns the raw balance (as an integer) for a specific token on a wallet.
+### `get_balance(*, query: str | dict, wallet_address: str, chain_id: int | None = None)`
+Returns the raw balance (as an integer) for a specific token or pool on a wallet.
+
+`query`: token_id/address string or a dict with a `"token_id"` key. When `query` is a token identifier (e.g. `"usd-coin-base"`), `chain_id` is auto-resolved from token info; when it is a pool address, `chain_id` must be provided.
 
 ```python
+# Token balance (chain_id auto-resolved)
 success, balance = await balance.get_balance(
-    token_id="usd-coin-base",
+    query="usd-coin-base",
     wallet_address=config["main_wallet"]["address"],
 )
-```
 
-### `get_pool_balance(pool_address: str, chain_id: int, user_address: str)`
-Fetches the amount supplied to a specific pool, using the `/wallets/pool-balance` endpoint.
-
-```python
-success, amount = await balance.get_pool_balance(
-    pool_address="0xPool",
+# Pool balance (chain_id required)
+success, pool_balance = await balance.get_balance(
+    query="0xPool...",
+    wallet_address=config["strategy_wallet"]["address"],
     chain_id=8453,
-    user_address=config["strategy_wallet"]["address"],
 )
 ```
 
@@ -80,10 +79,10 @@ class MyStrategy(Strategy):
         self.balance_adapter = balance_adapter
 
     async def _status(self):
-        success, pool_balance = await self.balance_adapter.get_pool_balance(
-            pool_address=self.current_pool["address"],
+        success, pool_balance = await self.balance_adapter.get_balance(
+            query=self.current_pool["address"],
+            wallet_address=self.config["strategy_wallet"]["address"],
             chain_id=self.current_pool["chain"]["id"],
-            user_address=self.config["strategy_wallet"]["address"],
         )
         return {"portfolio_value": float(pool_balance or 0), ...}
 ```

{wayfinder_paths-0.1.11 → wayfinder_paths-0.1.14}/wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -7,7 +7,6 @@ from wayfinder_paths.core.clients.TokenClient import TokenClient
 from wayfinder_paths.core.clients.WalletClient import WalletClient
 from wayfinder_paths.core.constants.base import DEFAULT_TRANSACTION_TIMEOUT
 from wayfinder_paths.core.services.base import Web3Service
-from wayfinder_paths.core.settings import settings
 from wayfinder_paths.core.utils.evm_helpers import resolve_chain_id
 
 
@@ -43,16 +42,39 @@ class BalanceAdapter(BaseAdapter):
     async def get_balance(
         self,
         *,
-        token_id: str,
+        query: str | dict[str, Any],
         wallet_address: str,
+        chain_id: int | None = None,
     ) -> tuple[bool, str | int]:
-        """Get token balance for a wallet."""
+        """Get token or pool balance for a wallet.
+
+        query: token_id/address string or a dict with a "token_id" key.
+        """
+        resolved = query if isinstance(query, str) else (query or {}).get("token_id")
+        if not resolved:
+            return (False, "missing query")
         try:
-            data = await self.wallet_client.get_token_balance_for_wallet(
-                token_id=token_id,
+            if chain_id is None:
+                token_info = await self.token_client.get_token_details(resolved)
+                if not token_info:
+                    return (False, f"Token not found: {resolved}")
+                resolved_chain_id = resolve_chain_id(token_info, self.logger)
+                if resolved_chain_id is None:
+                    return (False, f"Token {resolved} is missing a chain id")
+                chain_id = resolved_chain_id
+
+            data = await self.wallet_client.get_token_balance_for_address(
                 wallet_address=wallet_address,
+                query=resolved,
+                chain_id=int(chain_id),
+            )
+            # Use _parse_balance for consistent parsing (handles balance_raw or balance)
+            raw = (
+                data.get("balance_raw") or data.get("balance")
+                if isinstance(data, dict)
+                else None
             )
-            return (True, data.get("balance"))
+            return (True, self._parse_balance(raw))
         except Exception as e:
             return (False, str(e))
 
@@ -129,12 +151,9 @@ class BalanceAdapter(BaseAdapter):
             return False, tx_data
 
         tx = tx_data
-        if getattr(settings, "DRY_RUN", False):
-            broadcast_result = (True, {"dry_run": True, "transaction": tx})
-        else:
-            broadcast_result = await self.wallet_provider.broadcast_transaction(
-                tx, wait_for_receipt=True, timeout=DEFAULT_TRANSACTION_TIMEOUT
-            )
+        broadcast_result = await self.wallet_provider.broadcast_transaction(
+            tx, wait_for_receipt=True, timeout=DEFAULT_TRANSACTION_TIMEOUT
+        )
 
         if broadcast_result[0] and not skip_ledger and ledger_method is not None:
             wallet_for_ledger = from_address if ledger_wallet == "from" else to_address
@@ -163,6 +182,7 @@ class BalanceAdapter(BaseAdapter):
 
         usd_value = await self._token_amount_usd(token_info, amount)
         try:
+            token_id = token_info.get("token_id") or token_info.get("id")
             success, response = await ledger_method(
                 wallet_address=wallet_address,
                 chain_id=chain_id,
@@ -170,7 +190,7 @@ class BalanceAdapter(BaseAdapter):
                 token_amount=str(amount),
                 usd_value=usd_value,
                 data={
-                    "token_id": token_info.get("token_id"),
+                    "token_id": token_id,
                     "amount": str(amount),
                     "usd_value": usd_value,
                 },
@@ -180,15 +200,16 @@ class BalanceAdapter(BaseAdapter):
                 self.logger.warning(
                     "Ledger entry failed",
                     wallet=wallet_address,
-                    token_id=token_info.get("token_id"),
+                    token_id=token_id,
                     amount=amount,
                     error=response,
                 )
         except Exception as exc:  # noqa: BLE001
+            token_id = token_info.get("token_id") or token_info.get("id")
             self.logger.warning(
                 f"Ledger entry raised: {exc}",
                 wallet=wallet_address,
-                token_id=token_info.get("token_id"),
+                token_id=token_id,
             )
 
     async def _token_amount_usd(
@@ -212,27 +233,3 @@ class BalanceAdapter(BaseAdapter):
         if isinstance(evm_wallet, dict):
             return evm_wallet.get("address")
         return None
-
-    async def get_pool_balance(
-        self,
-        *,
-        pool_address: str,
-        chain_id: int,
-        user_address: str,
-    ) -> tuple[bool, Any]:
-        """Get pool balance for a wallet."""
-        try:
-            data = await self.wallet_client.get_pool_balance_for_wallet(
-                pool_address=pool_address,
-                chain_id=chain_id,
-                user_address=user_address,
-                human_readable=False,
-            )
-            raw = (
-                data.get("balance_raw") or data.get("balance")
-                if isinstance(data, dict)
-                else None
-            )
-            return (True, self._parse_balance(raw))
-        except Exception as e:
-            return (False, str(e))