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

{wayfinder_paths-0.1.13 → wayfinder_paths-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wayfinder-paths
-Version: 0.1.13
+Version: 0.1.14
 Summary: Wayfinder Path: strategies and adapters
 Author: Wayfinder
 Author-email: dev@wayfinder.ai
@@ -216,63 +216,28 @@ See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
 
 ### Authentication
 
-Wayfinder Paths supports two authentication methods:
+Wayfinder Paths uses API key authentication via the `X-API-KEY` header.
 
-#### 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
-)
-```
-
-**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
 
@@ -299,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)
+            pool_ids=pool_ids
         )
         return (True, data)
 ```
@@ -340,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:
@@ -357,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 {

{wayfinder_paths-0.1.13 → wayfinder_paths-0.1.14}/README.md

@@ -195,63 +195,28 @@ See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
 
 ### Authentication
 
-Wayfinder Paths supports two authentication methods:
+Wayfinder Paths uses API key authentication via the `X-API-KEY` header.
 
-#### 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
-)
-```
-
-**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
 
@@ -278,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)
+            pool_ids=pool_ids
         )
         return (True, data)
 ```
@@ -319,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:
@@ -336,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 {

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wayfinder-paths"
-version = "0.1.13"
+version = "0.1.14"
 description = "Wayfinder Path: strategies and adapters"
 readme = "README.md"
 authors = ["Wayfinder <dev@wayfinder.ai>"]

{wayfinder_paths-0.1.13 → 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.13 → wayfinder_paths-0.1.14}/wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -42,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),
             )
-            return (True, data.get("balance"))
+            # 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, self._parse_balance(raw))
         except Exception as e:
             return (False, str(e))
 
@@ -159,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,
@@ -166,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,
                 },
@@ -176,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(
@@ -208,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))

wayfinder_paths-0.1.14/wayfinder_paths/adapters/balance_adapter/test_adapter.py

@@ -0,0 +1,182 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
+
+
+class TestBalanceAdapter:
+    """Test cases for BalanceAdapter"""
+
+    @pytest.fixture
+    def mock_wallet_client(self):
+        """Mock WalletClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def mock_token_client(self):
+        """Mock TokenClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def mock_web3_service(self):
+        """Mock TokenClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_wallet_client, mock_token_client, mock_web3_service):
+        """Create a BalanceAdapter instance with mocked clients for testing"""
+        with (
+            patch(
+                "wayfinder_paths.adapters.balance_adapter.adapter.WalletClient",
+                return_value=mock_wallet_client,
+            ),
+            patch(
+                "wayfinder_paths.adapters.balance_adapter.adapter.TokenClient",
+                return_value=mock_token_client,
+            ),
+        ):
+            return BalanceAdapter(config={}, web3_service=mock_web3_service)
+
+    @pytest.mark.asyncio
+    async def test_health_check(self, adapter):
+        """Test adapter health check"""
+        health = await adapter.health_check()
+        assert isinstance(health, dict)
+        assert health.get("status") in {"healthy", "unhealthy", "error"}
+
+    @pytest.mark.asyncio
+    async def test_connect(self, adapter):
+        """Test adapter connection"""
+        ok = await adapter.connect()
+        assert isinstance(ok, bool)
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "BALANCE"
+
+    @pytest.mark.asyncio
+    async def test_get_balance_with_query_string(
+        self, adapter, mock_token_client, mock_wallet_client
+    ):
+        """Test get_balance with query as string (auto-resolves chain_id)."""
+        mock_token_client.get_token_details = AsyncMock(
+            return_value={
+                "token_id": "usd-coin-base",
+                "address": "0x123",
+                "chain": {"id": 8453, "code": "base"},
+            }
+        )
+        mock_wallet_client.get_token_balance_for_address = AsyncMock(
+            return_value={"balance": 1000000}
+        )
+
+        success, balance = await adapter.get_balance(
+            query="usd-coin-base",
+            wallet_address="0xWallet",
+        )
+
+        assert success is True
+        assert balance == 1000000
+        mock_token_client.get_token_details.assert_called_once_with("usd-coin-base")
+        mock_wallet_client.get_token_balance_for_address.assert_called_once_with(
+            wallet_address="0xWallet",
+            query="usd-coin-base",
+            chain_id=8453,
+        )
+
+    @pytest.mark.asyncio
+    async def test_get_balance_with_query_dict(
+        self, adapter, mock_token_client, mock_wallet_client
+    ):
+        """get_balance accepts query= as dict with token_id key."""
+        mock_token_client.get_token_details = AsyncMock(
+            return_value={
+                "token_id": "wsteth-base",
+                "address": "0x456",
+                "chain": {"id": 8453, "code": "base"},
+            }
+        )
+        mock_wallet_client.get_token_balance_for_address = AsyncMock(
+            return_value={"balance": 3000000}
+        )
+
+        success, balance = await adapter.get_balance(
+            query={"token_id": "wsteth-base"},
+            wallet_address="0x123",
+        )
+        assert success is True
+        assert balance == 3000000
+        mock_token_client.get_token_details.assert_called_once_with("wsteth-base")
+        mock_wallet_client.get_token_balance_for_address.assert_called_once_with(
+            wallet_address="0x123",
+            query="wsteth-base",
+            chain_id=8453,
+        )
+
+    @pytest.mark.asyncio
+    async def test_get_balance_missing_query(self, adapter):
+        """get_balance returns error when query is empty or missing token_id."""
+        success, result = await adapter.get_balance(query={}, wallet_address="0xabc")
+        assert success is False
+        assert "missing query" in str(result)
+
+    @pytest.mark.asyncio
+    async def test_get_balance_with_pool_address(
+        self, adapter, mock_token_client, mock_wallet_client
+    ):
+        """Test get_balance with pool address (explicit chain_id)"""
+        mock_wallet_client.get_token_balance_for_address = AsyncMock(
+            return_value={"balance": 5000000}
+        )
+        mock_token_client.get_token_details = AsyncMock()
+
+        success, balance = await adapter.get_balance(
+            query="0xPoolAddress",
+            wallet_address="0xWallet",
+            chain_id=8453,
+        )
+
+        assert success is True
+        assert balance == 5000000
+        mock_wallet_client.get_token_balance_for_address.assert_called_once_with(
+            wallet_address="0xWallet",
+            query="0xPoolAddress",
+            chain_id=8453,
+        )
+        mock_token_client.get_token_details.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_get_balance_token_not_found(self, adapter, mock_token_client):
+        """Test get_balance when token is not found"""
+        mock_token_client.get_token_details = AsyncMock(return_value=None)
+
+        success, error = await adapter.get_balance(
+            query="invalid-token",
+            wallet_address="0xWallet",
+        )
+
+        assert success is False
+        assert "Token not found" in str(error)
+
+    @pytest.mark.asyncio
+    async def test_get_balance_missing_chain_id(self, adapter, mock_token_client):
+        """Test get_balance when chain_id cannot be resolved"""
+        mock_token_client.get_token_details = AsyncMock(
+            return_value={
+                "token_id": "token-without-chain",
+                "address": "0x123",
+                "chain": {},
+            }
+        )
+
+        success, error = await adapter.get_balance(
+            query="token-without-chain",
+            wallet_address="0xWallet",
+        )
+
+        assert success is False
+        assert "missing a chain id" in str(error)

{wayfinder_paths-0.1.13 → wayfinder_paths-0.1.14}/wayfinder_paths/adapters/brap_adapter/README.md

@@ -46,10 +46,9 @@ success, data = await adapter.get_swap_quote(
     slippage=0.01  # 1% slippage
 )
 if success:
-    quotes = data.get("quotes", {})
-    best_quote = quotes.get("best_quote", {})
+    best_quote = data.get("best_quote", {})
     print(f"Output amount: {best_quote.get('output_amount')}")
-    print(f"Total fee: {best_quote.get('total_fee')}")
+    print(f"Fee estimate: {best_quote.get('fee_estimate', {}).get('fee_total_usd')}")
 else:
     print(f"Error: {data}")
 ```
@@ -68,8 +67,7 @@ success, data = await adapter.get_best_quote(
 )
 if success:
     print(f"Best output: {data.get('output_amount')}")
-    print(f"Gas fee: {data.get('gas_fee')}")
-    print(f"Bridge fee: {data.get('bridge_fee')}")
+    print(f"Fee estimate (USD): {data.get('fee_estimate', {}).get('fee_total_usd')}")
 else:
     print(f"Error: {data}")
 ```
@@ -88,10 +86,8 @@ success, data = await adapter.calculate_swap_fees(
 if success:
     print(f"Input amount: {data.get('input_amount')}")
     print(f"Output amount: {data.get('output_amount')}")
-    print(f"Gas fee: {data.get('gas_fee')}")
-    print(f"Bridge fee: {data.get('bridge_fee')}")
-    print(f"Protocol fee: {data.get('protocol_fee')}")
-    print(f"Total fee: {data.get('total_fee')}")
+    print(f"Gas estimate: {data.get('gas_fee')}")
+    print(f"Total fee (USD): {data.get('total_fee')}")
     print(f"Price impact: {data.get('price_impact')}")
 else:
     print(f"Error: {data}")
@@ -112,7 +108,7 @@ if success:
     print(f"Best route output: {data.get('best_route', {}).get('output_amount')}")
     
     for i, route in enumerate(data.get('all_routes', [])):
-        print(f"Route {i+1}: Output {route.get('output_amount')}, Fee {route.get('total_fee')}")
+        print(f\"Route {i+1}: Output {route.get('output_amount')}, Fee USD {route.get('fee_estimate', {}).get('fee_total_usd')}\")
 else:
     print(f"Error: {data}")
 ```
@@ -170,7 +166,7 @@ success, data = await adapter.get_bridge_quote(
     slippage=0.01
 )
 if success:
-    print(f"Bridge quote received: {data.get('quotes', {}).get('best_quote', {}).get('output_amount')}")
+    print(f"Bridge quote received: {data.get('best_quote', {}).get('output_amount')}")
 else:
     print(f"Error: {data}")
 ```
@@ -196,8 +192,7 @@ if success:
     fastest = analysis.get("fastest")
     
     print(f"Highest output route: {highest_output.get('output_amount')}")
-    print(f"Lowest fees route: {lowest_fees.get('total_fee')}")
-    print(f"Fastest route: {fastest.get('estimated_time')} seconds")
+    print(f\"Lowest fees route (USD): {lowest_fees.get('fee_estimate', {}).get('fee_total_usd')}\")
 ```
 
 ### Fee Analysis
@@ -215,19 +210,19 @@ success, data = await adapter.calculate_swap_fees(
 if success:
     input_amount = int(data.get("input_amount", 0))
     output_amount = int(data.get("output_amount", 0))
-    total_fee = int(data.get("total_fee", 0))
+    total_fee_usd = float(data.get("total_fee", 0))
     
     # Calculate effective rate
     effective_rate = (input_amount - output_amount) / input_amount
     print(f"Effective rate: {effective_rate:.4f} ({effective_rate * 100:.2f}%)")
-    print(f"Total fees: {total_fee / 1e18:.6f} tokens")
+    print(f"Total fees: ${total_fee_usd:.4f}")
 ```
 
 ## API Endpoints
 
 The adapter uses the following Wayfinder API endpoints:
 
-- `POST /api/v1/public/quotes/` - Get swap/bridge quotes
+- `GET /api/v1/blockchain/braps/quote/` - Get swap/bridge quotes
 
 ## Error Handling