wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/adapters/pool_adapter/examples.json

@@ -0,0 +1,143 @@
+{
+  "get_pools_by_ids": {
+    "description": "Get pool information by pool IDs",
+    "input": {
+      "pool_ids": ["pool-123", "pool-456"],
+      "merge_external": true
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "apy": 0.05,
+            "tvl": 1000000,
+            "chain": "base"
+          }
+        ]
+      }
+    }
+  },
+  "get_all_pools": {
+    "description": "Get all available pools",
+    "input": {
+      "merge_external": false
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "apy": 0.05,
+            "tvl": 1000000
+          }
+        ],
+        "total": 1
+      }
+    }
+  },
+  "get_llama_matches": {
+    "description": "Get Llama protocol matches for pools",
+    "input": {},
+    "output": {
+      "success": true,
+      "data": {
+        "matches": [
+          {
+            "id": "pool-123",
+            "llama_apy_pct": 5.2,
+            "llama_tvl_usd": 1000000,
+            "llama_stablecoin": true,
+            "llama_il_risk": "no",
+            "network": "base"
+          }
+        ]
+      }
+    }
+  },
+  "find_high_yield_pools": {
+    "description": "Find high-yield pools based on criteria",
+    "input": {
+      "min_apy": 0.03,
+      "min_tvl": 500000,
+      "stablecoin_only": true,
+      "network_codes": ["base", "ethereum"]
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "llama_apy_pct": 5.2,
+            "llama_tvl_usd": 1000000,
+            "llama_stablecoin": true,
+            "network": "base"
+          }
+        ],
+        "total_found": 1,
+        "filters_applied": {
+          "min_apy": 0.03,
+          "min_tvl": 500000,
+          "stablecoin_only": true,
+          "network_codes": ["base", "ethereum"]
+        }
+      }
+    }
+  },
+  "get_pool_analytics": {
+    "description": "Get comprehensive analytics for specific pools",
+    "input": {
+      "pool_ids": ["pool-123"]
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "analytics": [
+          {
+            "pool": {
+              "id": "pool-123",
+              "name": "USDC/USDT Pool",
+              "symbol": "USDC-USDT"
+            },
+            "llama_data": {
+              "llama_apy_pct": 5.2,
+              "llama_tvl_usd": 1000000
+            },
+            "combined_apy": 0.052,
+            "tvl_usd": 1000000
+          }
+        ],
+        "total_pools": 1
+      }
+    }
+  },
+  "search_pools": {
+    "description": "Search pools by name, symbol, or other criteria",
+    "input": {
+      "query": "USDC",
+      "limit": 5
+    },
+    "output": {
+      "success": true,
+      "data": {
+        "pools": [
+          {
+            "id": "pool-123",
+            "name": "USDC/USDT Pool",
+            "symbol": "USDC-USDT",
+            "description": "Stablecoin pool on Base"
+          }
+        ],
+        "total_found": 1,
+        "query": "USDC"
+      }
+    }
+  }
+}

wayfinder_paths/adapters/pool_adapter/manifest.yaml

@@ -0,0 +1,10 @@
+schema_version: "0.1"
+entrypoint: "adapters.pool_adapter.adapter.PoolAdapter"
+capabilities:
+  - "pool.read"
+  - "pool.analytics"
+  - "pool.discovery"
+  - "llama.data"
+  - "pool.reports"
+dependencies:
+  - "PoolClient"

wayfinder_paths/adapters/pool_adapter/test_adapter.py

@@ -0,0 +1,220 @@
+from unittest.mock import AsyncMock
+
+import pytest
+
+from wayfinder_paths.adapters.pool_adapter.adapter import PoolAdapter
+
+
+class TestPoolAdapter:
+    """Test cases for PoolAdapter"""
+
+    @pytest.fixture
+    def mock_pool_client(self):
+        """Mock PoolClient for testing"""
+        mock_client = AsyncMock()
+        return mock_client
+
+    @pytest.fixture
+    def adapter(self, mock_pool_client):
+        """Create a PoolAdapter instance with mocked client for testing"""
+        adapter = PoolAdapter()
+        adapter.pool_client = mock_pool_client
+        return adapter
+
+    @pytest.mark.asyncio
+    async def test_get_pools_by_ids_success(self, adapter, mock_pool_client):
+        """Test successful pool retrieval by IDs"""
+        mock_response = {
+            "pools": [
+                {
+                    "id": "pool-123",
+                    "name": "USDC/USDT Pool",
+                    "symbol": "USDC-USDT",
+                    "apy": 0.05,
+                    "tvl": 1000000,
+                }
+            ]
+        }
+        mock_pool_client.get_pools_by_ids = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_pools_by_ids(
+            pool_ids=["pool-123", "pool-456"], merge_external=True
+        )
+
+        assert success is True
+        assert data == mock_response
+        mock_pool_client.get_pools_by_ids.assert_called_once_with(
+            pool_ids="pool-123,pool-456", merge_external=True
+        )
+
+    @pytest.mark.asyncio
+    async def test_get_all_pools_success(self, adapter, mock_pool_client):
+        """Test successful retrieval of all pools"""
+        # Mock response
+        mock_response = {
+            "pools": [
+                {"id": "pool-123", "name": "Pool 1"},
+                {"id": "pool-456", "name": "Pool 2"},
+            ],
+            "total": 2,
+        }
+        mock_pool_client.get_all_pools = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_all_pools(merge_external=False)
+
+        assert success is True
+        assert data == mock_response
+        mock_pool_client.get_all_pools.assert_called_once_with(merge_external=False)
+
+    @pytest.mark.asyncio
+    async def test_get_llama_matches_success(self, adapter, mock_pool_client):
+        """Test successful Llama matches retrieval"""
+        # Mock response
+        mock_response = {
+            "matches": [
+                {
+                    "id": "pool-123",
+                    "llama_apy_pct": 5.2,
+                    "llama_tvl_usd": 1000000,
+                    "llama_stablecoin": True,
+                    "network": "base",
+                }
+            ]
+        }
+        mock_pool_client.get_llama_matches = AsyncMock(return_value=mock_response)
+
+        success, data = await adapter.get_llama_matches()
+
+        assert success is True
+        assert data == mock_response
+
+    @pytest.mark.asyncio
+    async def test_find_high_yield_pools_success(self, adapter, mock_pool_client):
+        """Test successful high yield pool discovery"""
+        mock_llama_response = {
+            "matches": [
+                {
+                    "pool_id": "pool-123",
+                    "llama_apy_pct": 5.2,
+                    "llama_tvl_usd": 1000000,
+                    "llama_stablecoin": True,
+                    "network": "base",
+                },
+                {
+                    "pool_id": "pool-456",
+                    "llama_apy_pct": 2.0,
+                    "llama_tvl_usd": 500000,
+                    "llama_stablecoin": True,
+                    "network": "ethereum",
+                },
+                {
+                    "pool_id": "pool-789",
+                    "llama_apy_pct": 6.0,
+                    "llama_tvl_usd": 2000000,
+                    "llama_stablecoin": False,
+                    "network": "base",
+                },
+            ]
+        }
+        mock_pool_client.get_llama_matches = AsyncMock(return_value=mock_llama_response)
+
+        success, data = await adapter.find_high_yield_pools(
+            min_apy=0.03, min_tvl=500000, stablecoin_only=True, network_codes=["base"]
+        )
+
+        assert success is True
+        assert len(data["pools"]) == 1  # Only pool-123 meets criteria
+        assert (
+            data["pools"][0].get("pool_id") == "pool-123"
+            or data["pools"][0].get("id") == "pool-123"
+        )
+        assert data["total_found"] == 1
+        assert data["filters_applied"]["min_apy"] == 0.03
+        assert data["filters_applied"]["stablecoin_only"] is True
+
+    @pytest.mark.asyncio
+    async def test_get_pool_analytics_success(self, adapter, mock_pool_client):
+        """Test successful pool analytics generation"""
+        mock_pool_data = {
+            "pools": [
+                {"id": "pool-123", "name": "USDC/USDT Pool", "symbol": "USDC-USDT"}
+            ]
+        }
+        mock_pool_client.get_pools_by_ids = AsyncMock(return_value=mock_pool_data)
+
+        mock_llama_data = {
+            "pool-123": {
+                "llama_apy_pct": 5.2,
+                "llama_combined_apy_pct": 5.2,
+                "llama_tvl_usd": 1000000,
+            }
+        }
+        mock_pool_client.get_llama_reports = AsyncMock(return_value=mock_llama_data)
+
+        success, data = await adapter.get_pool_analytics(["pool-123"])
+
+        assert success is True
+        assert len(data["analytics"]) == 1
+        assert data["analytics"][0]["pool"]["id"] == "pool-123"
+        assert round(data["analytics"][0]["combined_apy"], 6) == round(0.052, 6)
+        assert data["analytics"][0]["tvl_usd"] == 1000000
+
+    @pytest.mark.asyncio
+    async def test_search_pools_success(self, adapter, mock_pool_client):
+        """Test successful pool search"""
+        mock_all_pools = {
+            "pools": [
+                {
+                    "id": "pool-123",
+                    "name": "USDC/USDT Pool",
+                    "symbol": "USDC-USDT",
+                    "description": "Stablecoin pool on Base",
+                },
+                {
+                    "id": "pool-456",
+                    "name": "ETH/WETH Pool",
+                    "symbol": "ETH-WETH",
+                    "description": "Ethereum pool",
+                },
+            ]
+        }
+        mock_pool_client.get_all_pools = AsyncMock(return_value=mock_all_pools)
+
+        success, data = await adapter.search_pools("USDC", limit=5)
+
+        assert success is True
+        assert len(data["pools"]) == 1
+        assert data["pools"][0]["id"] == "pool-123"
+        assert data["total_found"] == 1
+        assert data["query"] == "USDC"
+
+    @pytest.mark.asyncio
+    async def test_get_pools_by_ids_failure(self, adapter, mock_pool_client):
+        """Test pool retrieval failure"""
+        mock_pool_client.get_pools_by_ids = AsyncMock(
+            side_effect=Exception("API Error")
+        )
+
+        success, data = await adapter.get_pools_by_ids(["pool-123"])
+
+        assert success is False
+        assert "API Error" in data
+
+    @pytest.mark.asyncio
+    async def test_find_high_yield_pools_no_matches(self, adapter, mock_pool_client):
+        """Test high yield pool discovery with no matches"""
+        mock_llama_response = {"matches": []}
+        mock_pool_client.get_llama_matches.return_value = mock_llama_response
+
+        success, data = await adapter.find_high_yield_pools(
+            min_apy=0.10,
+            min_tvl=10000000,
+        )
+
+        assert success is True
+        assert len(data["pools"]) == 0
+        assert data["total_found"] == 0
+
+    def test_adapter_type(self, adapter):
+        """Test adapter has adapter_type"""
+        assert adapter.adapter_type == "POOL"

wayfinder_paths/adapters/token_adapter/README.md

@@ -0,0 +1,101 @@
+# Token Adapter
+
+A Wayfinder adapter that wraps the `_get_token_via_api` method for fetching token data via HeadlessAPIViewSet endpoints. This adapter supports both address and token_id lookups.
+
+## Capabilities
+
+- `token.read`: Retrieve token information by address or token ID
+
+## Configuration
+
+The adapter uses the TokenClient which automatically handles authentication and API configuration through the Wayfinder settings. No additional configuration is required.
+
+The TokenClient will automatically:
+- Use the WAYFINDER_API_URL from settings
+- Handle authentication via environment variables or config.json
+- Manage token refresh and retry logic
+
+## Usage
+
+### Initialize the Adapter
+
+```python
+from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
+
+# No configuration needed - uses TokenClient with automatic settings
+adapter = TokenAdapter()
+```
+
+### Get Token Metadata
+
+Both contract addresses and token ids are supported with the same method. Pass whichever identifier you have:
+
+```python
+success, data = await adapter.get_token("0x1234...")        # by address
+# or
+success, data = await adapter.get_token("usd-coin-base")    # by token id
+
+if success:
+    print(data)
+else:
+    print(f"Error: {data}")
+```
+
+### Get Token Price
+
+```python
+success, data = await adapter.get_token_price("token-123")
+if success:
+    print(f"Price: ${data['current_price']}")
+    print(f"24h Change: {data['price_change_percentage_24h']}%")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Gas Token
+
+```python
+success, data = await adapter.get_gas_token("base")
+if success:
+    print(f"Gas token: {data['symbol']} - {data['name']}")
+    print(f"Address: {data['address']}")
+else:
+    print(f"Error: {data}")
+```
+
+### Get Token (Flexible)
+
+```python
+# Try by address first, then by token_id
+success, data = await adapter.get_token(address="0x1234...", token_id="token-123")
+if success:
+    print(f"Token data: {data}")
+else:
+    print(f"Error: {data}")
+```
+
+## API Endpoints
+
+The adapter uses the following existing public API endpoints:
+
+1. **Token Details** (by address): `GET /public/tokens/detail/?query={address}&get_chart=false`
+2. **Token by ID**: `GET /public/tokens/lookup/?token_id={token_id}`
+
+## Error Handling
+
+All methods return a tuple of `(success: bool, data: Any)` where:
+- `success` indicates whether the operation was successful
+- `data` contains either the token information (on success) or an error message (on failure)
+
+## Health Check
+
+The adapter includes a health check that tests connectivity to the API:
+
+```python
+health = await adapter.health_check()
+print(f"Status: {health['status']}")
+```
+
+## Examples
+
+See `examples.json` for more detailed usage examples.

wayfinder_paths/adapters/token_adapter/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import TokenAdapter
+
+__all__ = ["TokenAdapter"]

wayfinder_paths/adapters/token_adapter/adapter.py

@@ -0,0 +1,96 @@
+from typing import Any
+
+from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.clients.TokenClient import (
+    GasToken,
+    TokenClient,
+    TokenDetails,
+)
+
+
+class TokenAdapter(BaseAdapter):
+    """
+    Token adapter that wraps the _get_token_via_api method for fetching token data
+    via HeadlessAPIViewSet endpoints. Supports both address and token_id lookups.
+    """
+
+    adapter_type: str = "TOKEN"
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        token_client: TokenClient | None = None,
+    ):
+        super().__init__("token_adapter", config)
+        self.token_client = token_client or TokenClient()
+
+    async def get_token(self, query: str) -> tuple[bool, TokenDetails | str]:
+        """
+        Get token data by address using the token-details endpoint.
+
+        Args:
+            address: Token contract address
+
+        Returns:
+            Tuple of (success, data) where data is the token information or error message
+        """
+        try:
+            data = await self.token_client.get_token_details(query)
+            if not data:
+                return (False, f"No token found for: {query}")
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error getting token by query {query}: {e}")
+            return (False, str(e))
+
+    async def get_token_price(self, token_id: str) -> tuple[bool, dict[str, Any] | str]:
+        """
+        Get token price by token ID or address using the token-details endpoint.
+
+        Args:
+            token_id: Token identifier or address
+
+        Returns:
+            Tuple of (success, data) where data is the price information or error message
+        """
+        try:
+            data = await self.token_client.get_token_details(token_id)
+            if not data:
+                return (False, f"No token found for: {token_id}")
+
+            # Extract just the price information
+            price_data = {
+                "current_price": data.get("current_price", 0.0),
+                "price_change_24h": data.get("price_change_24h", 0.0),
+                "price_change_percentage_24h": data.get(
+                    "price_change_percentage_24h", 0.0
+                ),
+                "market_cap": data.get("market_cap", 0),
+                "total_volume": data.get("total_volume", 0),
+                "symbol": data.get("symbol", ""),
+                "name": data.get("name", ""),
+                "address": data.get("address", ""),
+            }
+            return (True, price_data)
+        except Exception as e:
+            self.logger.error(f"Error getting token price for {token_id}: {e}")
+            return (False, str(e))
+
+    async def get_gas_token(self, chain_code: str) -> tuple[bool, GasToken | str]:
+        """
+        Get gas token for a given chain code.
+
+        Args:
+            chain_code: Chain code (e.g., "base", "ethereum")
+
+        Returns:
+            Tuple of (success, data) where data is the gas token information or error message
+        """
+        try:
+            data = await self.token_client.get_gas_token(chain_code)
+            if not data:
+                return (False, f"No gas token found for chain: {chain_code}")
+            return (True, data)
+        except Exception as e:
+            self.logger.error(f"Error getting gas token for chain {chain_code}: {e}")
+            return (False, str(e))

wayfinder_paths/adapters/token_adapter/examples.json

@@ -0,0 +1,26 @@
+{
+  "basic_usage": {
+    "description": "Basic usage of TokenAdapter to get token information",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by address\nsuccess, data = await adapter.get_token_by_address(\"0x1234567890abcdef1234567890abcdef12345678\")\nif success:\n    print(f\"Token symbol: {data.get('symbol')}\")\n    print(f\"Token name: {data.get('name')}\")\n    print(f\"Decimals: {data.get('decimals')}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "get_by_token_id": {
+    "description": "Get token information using token ID",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Get token by ID\nsuccess, data = await adapter.get_token_by_id(\"token-12345\")\nif success:\n    print(f\"Token data: {data}\")\nelse:\n    print(f\"Error: {data}\")"
+  },
+  "flexible_lookup": {
+    "description": "Use flexible get_token method that tries both address and token_id",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Try both address and token_id\nsuccess, data = await adapter.get_token(\n    address=\"0x1234567890abcdef1234567890abcdef12345678\",\n    token_id=\"token-12345\"\n)\nif success:\n    print(f\"Found token: {data}\")\nelse:\n    print(f\"Token not found: {data}\")"
+  },
+  "error_handling": {
+    "description": "Proper error handling for various scenarios",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Handle missing parameters\ntry:\n    success, data = await adapter.get_token()\n    if not success:\n        print(f\"Error: {data}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n\n# Handle API errors\nsuccess, data = await adapter.get_token_by_address(\"invalid-address\")\nif not success:\n    print(f\"API error: {data}\")\nelse:\n    print(f\"Token found: {data}\")"
+  },
+  "health_check": {
+    "description": "Check adapter health and connectivity",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# Check health\nhealth = await adapter.health_check()\nprint(f\"Adapter status: {health['status']}\")\nprint(f\"Connected: {health['connected']}\")\nprint(f\"Adapter type: {health['adapter']}\")\n\nif health['status'] == 'healthy':\n    print(\"Adapter is ready to use\")\nelse:\n    print(f\"Adapter has issues: {health.get('error', 'Unknown error')}\")"
+  },
+  "batch_operations": {
+    "description": "Perform multiple token lookups efficiently",
+    "code": "from adapters.token_adapter.adapter import TokenAdapter\nimport asyncio\n\n# Initialize adapter (no config needed)\nadapter = TokenAdapter()\n\n# List of token addresses to lookup\ntoken_addresses = [\n    \"0x1234567890abcdef1234567890abcdef12345678\",\n    \"0xabcdef1234567890abcdef1234567890abcdef12\",\n    \"0x9876543210fedcba9876543210fedcba98765432\"\n]\n\n# Batch lookup\ntoken_data = {}\nfor address in token_addresses:\n    success, data = await adapter.get_token_by_address(address)\n    if success:\n        token_data[address] = data\n    else:\n        print(f\"Failed to get token for {address}: {data}\")\n\nprint(f\"Successfully retrieved {len(token_data)} tokens\")\nfor address, data in token_data.items():\n    print(f\"{address}: {data.get('symbol', 'Unknown')} - {data.get('name', 'Unknown')}\")"
+  }
+}

wayfinder_paths/adapters/token_adapter/manifest.yaml

@@ -0,0 +1,6 @@
+schema_version: "0.1"
+entrypoint: "adapters.token_adapter.adapter.TokenAdapter"
+capabilities:
+  - "token.read"
+dependencies:
+  - "TokenClient"