wayfinder-paths 0.1.15__tar.gz → 0.1.17__tar.gz

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: wayfinder-paths
-Version: 0.1.15
+Version: 0.1.17
 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
+Classifier: Programming Language :: Python :: 3.13
 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)
@@ -275,7 +276,6 @@ Strategies implement trading logic using adapters and the unified client system.
 
 ```python
 # wayfinder_paths/strategies/my_strategy/strategy.py
-from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
 from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
@@ -291,9 +291,8 @@ class MyStrategy(Strategy):
     ):
         super().__init__(api_key=api_key)  # Pass to base class for auto-discovery
         self.config = config or {}
-        web3_service = DefaultWeb3Service(self.config)
         # Adapters automatically discover API key from constructor or config.json
-        balance_adapter = BalanceAdapter(self.config, web3_service=web3_service)
+        balance_adapter = BalanceAdapter(self.config)
         self.register_adapters([balance_adapter])
         self.balance_adapter = balance_adapter
 
@@ -311,7 +310,6 @@ class MyStrategy(Strategy):
         if not success:
             return (False, "Unable to fetch balances")
 
-        # Use BalanceAdapter (which leverages LocalTokenTxnService builders) for transfers here.
         self.last_deposit = main_token_amount
         return (True, f"Deposited {main_token_amount} tokens")
 
@@ -344,42 +342,6 @@ The following strategies are available and can be run using the CLI:
 
 #### Running Strategies
 
-```bash
-# Check strategy status
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  status
-
-# Deposit funds (USDC amount, optional ETH for gas)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  deposit --usdc 100 --eth 0.01
-
-# Run periodic update
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  update
-
-# Withdraw funds (omit --amount for full withdrawal)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  withdraw --amount 50
-
-# Run in simulation mode (no real transactions)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --simulation \
-  status
-```
-
 ### Built-in adapters
 
 - **BALANCE (BalanceAdapter)**: wraps `WalletClient`/`TokenClient` to read wallet, token, and pool balances and now orchestrates transfers between the main/strategy wallets with ledger bookkeeping. Requires a `Web3Service` so it can share the same wallet provider as the strategy.

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/README.md

@@ -254,7 +254,6 @@ Strategies implement trading logic using adapters and the unified client system.
 
 ```python
 # wayfinder_paths/strategies/my_strategy/strategy.py
-from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
 from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
@@ -270,9 +269,8 @@ class MyStrategy(Strategy):
     ):
         super().__init__(api_key=api_key)  # Pass to base class for auto-discovery
         self.config = config or {}
-        web3_service = DefaultWeb3Service(self.config)
         # Adapters automatically discover API key from constructor or config.json
-        balance_adapter = BalanceAdapter(self.config, web3_service=web3_service)
+        balance_adapter = BalanceAdapter(self.config)
         self.register_adapters([balance_adapter])
         self.balance_adapter = balance_adapter
 
@@ -290,7 +288,6 @@ class MyStrategy(Strategy):
         if not success:
             return (False, "Unable to fetch balances")
 
-        # Use BalanceAdapter (which leverages LocalTokenTxnService builders) for transfers here.
         self.last_deposit = main_token_amount
         return (True, f"Deposited {main_token_amount} tokens")
 
@@ -323,42 +320,6 @@ The following strategies are available and can be run using the CLI:
 
 #### Running Strategies
 
-```bash
-# Check strategy status
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  status
-
-# Deposit funds (USDC amount, optional ETH for gas)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  deposit --usdc 100 --eth 0.01
-
-# Run periodic update
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  update
-
-# Withdraw funds (omit --amount for full withdrawal)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --main-wallet-label main \
-  --strategy-wallet-label moonwell_wsteth_loop_strategy \
-  withdraw --amount 50
-
-# Run in simulation mode (no real transactions)
-poetry run python wayfinder_paths/scripts/run_strategy.py \
-  --strategy moonwell_wsteth_loop_strategy \
-  --simulation \
-  status
-```
-
 ### Built-in adapters
 
 - **BALANCE (BalanceAdapter)**: wraps `WalletClient`/`TokenClient` to read wallet, token, and pool balances and now orchestrates transfers between the main/strategy wallets with ledger bookkeeping. Requires a `Web3Service` so it can share the same wallet provider as the strategy.

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/pyproject.toml

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

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/wayfinder_paths/adapters/balance_adapter/README.md

@@ -7,43 +7,42 @@ Adapter that exposes wallet, token, and pool balances backed by `WalletClient`/`
 
 ## Capabilities
 
-The adapter provides both wallet read and wallet transfer capabilities. Transfers are executed by leveraging the shared `DefaultWeb3Service.token_transactions` helper, but ledger recording + wallet selection now live inside the adapter.
+The adapter provides both wallet read and wallet transfer capabilities. Ledger recording + wallet selection now live inside the adapter.
 
 ## Construction
 
 ```python
-from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
-web3_service = DefaultWeb3Service(config)
-balance = BalanceAdapter(config, web3_service=web3_service)
 ```
 
-`web3_service` is required so the adapter can share the same wallet provider (and `TokenTxn` helper) as the rest of the strategy.
-
 ## API surface
 
-### `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.
+### `get_balance(token_id: str, wallet_address: str)`
 
-`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.
+Returns the raw balance (as an integer) for a specific token on a wallet.
 
 ```python
-# Token balance (chain_id auto-resolved)
 success, balance = await balance.get_balance(
-    query="usd-coin-base",
+    token_id="usd-coin-base",
     wallet_address=config["main_wallet"]["address"],
 )
+```
+
+### `get_pool_balance(pool_address: str, chain_id: int, user_address: str)`
 
-# Pool balance (chain_id required)
-success, pool_balance = await balance.get_balance(
-    query="0xPool...",
-    wallet_address=config["strategy_wallet"]["address"],
+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",
     chain_id=8453,
+    user_address=config["strategy_wallet"]["address"],
 )
 ```
 
 ### `move_from_main_wallet_to_strategy_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+
 Sends the specified token from the configured `main_wallet` to the strategy wallet, records the ledger deposit (unless `skip_ledger=True`), and returns the `(success, tx_result)` tuple from the underlying send helper.
 
 ```python
@@ -55,6 +54,7 @@ success, tx = await balance.move_from_main_wallet_to_strategy_wallet(
 ```
 
 ### `move_from_strategy_wallet_to_main_wallet(token_id: str, amount: float, strategy_name="unknown", skip_ledger=False)`
+
 Mirrors the previous method but withdraws from the strategy wallet back to the main wallet while recording a ledger withdrawal entry.
 
 ```python
@@ -73,16 +73,15 @@ All methods return `(success: bool, payload: Any)` tuples. On failure the payloa
 class MyStrategy(Strategy):
     def __init__(self, config):
         super().__init__()
-        web3_service = DefaultWeb3Service(config)
-        balance_adapter = BalanceAdapter(config, web3_service=web3_service)
+        balance_adapter = BalanceAdapter(config)
         self.register_adapters([balance_adapter])
         self.balance_adapter = balance_adapter
 
     async def _status(self):
-        success, pool_balance = await self.balance_adapter.get_balance(
-            query=self.current_pool["address"],
-            wallet_address=self.config["strategy_wallet"]["address"],
+        success, pool_balance = await self.balance_adapter.get_pool_balance(
+            pool_address=self.current_pool["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.15 → wayfinder_paths-0.1.17}/wayfinder_paths/adapters/balance_adapter/adapter.py

@@ -5,9 +5,9 @@ from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
 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.utils.erc20_service import build_send_transaction
 from wayfinder_paths.core.utils.evm_helpers import resolve_chain_id
+from wayfinder_paths.core.utils.transaction import send_transaction
 
 
 class BalanceAdapter(BaseAdapter):
@@ -16,17 +16,19 @@ class BalanceAdapter(BaseAdapter):
     def __init__(
         self,
         config: dict[str, Any],
-        web3_service: Web3Service,
+        simulation: bool = False,
+        main_wallet_signing_callback=None,
+        strategy_wallet_signing_callback=None,
     ):
         super().__init__("balance", config)
+        self.simulation = simulation
+        self.main_wallet_signing_callback = main_wallet_signing_callback
+        self.strategy_wallet_signing_callback = strategy_wallet_signing_callback
         self.wallet_client = WalletClient()
         self.token_client = TokenClient()
         self.token_adapter = TokenAdapter()
         self.ledger_adapter = LedgerAdapter()
 
-        self.wallet_provider = web3_service.evm_transactions
-        self.token_transactions = web3_service.token_transactions
-
     def _parse_balance(self, raw: Any) -> int:
         """Parse balance value to integer, handling various formats."""
         if raw is None:
@@ -42,15 +44,23 @@ class BalanceAdapter(BaseAdapter):
     async def get_balance(
         self,
         *,
-        query: str | dict[str, Any],
+        query: str | dict[str, Any] | None = None,
+        token_id: str | None = None,
         wallet_address: str,
         chain_id: int | None = None,
     ) -> tuple[bool, str | int]:
         """Get token or pool balance for a wallet.
 
         query: token_id/address string or a dict with a "token_id" key.
+        token_id: alternative to query for convenience.
         """
-        resolved = query if isinstance(query, str) else (query or {}).get("token_id")
+        # Support both query= and token_id= for caller convenience
+        effective_query = query if query is not None else token_id
+        resolved = (
+            effective_query
+            if isinstance(effective_query, str)
+            else (effective_query or {}).get("token_id")
+        )
         if not resolved:
             return (False, "missing query")
         try:
@@ -119,15 +129,13 @@ class BalanceAdapter(BaseAdapter):
     async def send_to_address(
         self,
         token_id: str,
-        amount: float,
+        amount: int,
         from_wallet: dict[str, Any] | None,
         to_address: str,
+        signing_callback=None,
         skip_ledger: bool = True,
     ) -> tuple[bool, Any]:
         """Send tokens from a wallet to an arbitrary address (e.g., bridge contract)."""
-        if self.token_transactions is None:
-            return False, "Token transaction service not configured"
-
         from_address = self._wallet_address(from_wallet)
         if not from_address:
             return False, "from_wallet missing or invalid"
@@ -139,22 +147,28 @@ class BalanceAdapter(BaseAdapter):
         if not token_info:
             return False, f"Token not found: {token_id}"
 
-        build_success, tx_data = await self.token_transactions.build_send(
-            token_id=token_id,
-            amount=amount,
+        chain_id = resolve_chain_id(token_info, self.logger)
+        if chain_id is None:
+            return False, f"Token {token_id} is missing chain_id"
+
+        token_address = token_info.get("address")
+
+        tx = await build_send_transaction(
             from_address=from_address,
             to_address=to_address,
-            token_info=token_info,
+            token_address=token_address,
+            chain_id=chain_id,
+            amount=int(amount),
         )
-        if not build_success:
-            return False, tx_data
 
-        tx = tx_data
-        broadcast_result = await self.wallet_provider.broadcast_transaction(
-            tx, wait_for_receipt=True, timeout=DEFAULT_TRANSACTION_TIMEOUT
-        )
+        if self.simulation:
+            return True, {"simulation": tx}
 
-        return broadcast_result
+        if not signing_callback:
+            return False, "signing_callback is required"
+
+        tx_hash = await send_transaction(tx, signing_callback)
+        return True, tx_hash
 
     async def _move_between_wallets(
         self,
@@ -168,9 +182,6 @@ class BalanceAdapter(BaseAdapter):
         strategy_name: str,
         skip_ledger: bool,
     ) -> tuple[bool, Any]:
-        if self.token_transactions is None:
-            return False, "Token transaction service not configured"
-
         from_address = self._wallet_address(from_wallet)
         to_address = self._wallet_address(to_wallet)
         if not from_address or not to_address:
@@ -180,20 +191,21 @@ class BalanceAdapter(BaseAdapter):
         if not token_info:
             return False, f"Token not found: {token_id}"
 
-        build_success, tx_data = await self.token_transactions.build_send(
-            token_id=token_id,
-            amount=amount,
+        chain_id = resolve_chain_id(token_info, self.logger)
+        if chain_id is None:
+            return False, f"Token {token_id} is missing chain_id"
+
+        decimals = token_info.get("decimals", 18)
+        raw_amount = int(amount * (10**decimals))
+
+        tx = await build_send_transaction(
             from_address=from_address,
             to_address=to_address,
-            token_info=token_info,
-        )
-        if not build_success:
-            return False, tx_data
-
-        tx = tx_data
-        broadcast_result = await self.wallet_provider.broadcast_transaction(
-            tx, wait_for_receipt=True, timeout=DEFAULT_TRANSACTION_TIMEOUT
+            token_address=token_info.get("address"),
+            chain_id=chain_id,
+            amount=raw_amount,
         )
+        broadcast_result = await self._send_tx(tx, from_address)
 
         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
@@ -207,6 +219,23 @@ class BalanceAdapter(BaseAdapter):
 
         return broadcast_result
 
+    async def _send_tx(self, tx: dict[str, Any], from_address: str) -> tuple[bool, Any]:
+        """Send transaction with simulation check, using appropriate signing callback."""
+        if self.simulation:
+            return True, {"simulation": tx}
+
+        # Choose callback based on which wallet is sending
+        main_wallet = self.config.get("main_wallet") or {}
+        main_addr = main_wallet.get("address", "").lower()
+
+        if from_address.lower() == main_addr:
+            callback = self.main_wallet_signing_callback
+        else:
+            callback = self.strategy_wallet_signing_callback
+
+        txn_hash = await send_transaction(tx, callback)
+        return True, txn_hash
+
     async def _record_ledger_entry(
         self,
         *,

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/wayfinder_paths/adapters/balance_adapter/test_adapter.py

@@ -21,13 +21,7 @@ class TestBalanceAdapter:
         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):
+    def adapter(self, mock_wallet_client, mock_token_client):
         """Create a BalanceAdapter instance with mocked clients for testing"""
         with (
             patch(
@@ -39,7 +33,7 @@ class TestBalanceAdapter:
                 return_value=mock_token_client,
             ),
         ):
-            return BalanceAdapter(config={}, web3_service=mock_web3_service)
+            return BalanceAdapter(config={})
 
     @pytest.mark.asyncio
     async def test_health_check(self, adapter):

{wayfinder_paths-0.1.15 → wayfinder_paths-0.1.17}/wayfinder_paths/adapters/brap_adapter/README.md

@@ -13,9 +13,8 @@ A Wayfinder adapter that provides high-level operations for cross-chain swaps an
 
 ## Configuration
 
-The adapter uses the BRAPClient which automatically handles authentication and API configuration through the Wayfinder settings. Pass a `Web3Service` instance so it can broadcast transactions and reuse the shared `LocalTokenTxnService` for approvals.
-
 The BRAPClient will automatically:
+
 - Use the WAYFINDER_API_URL from settings
 - Handle authentication via config.json
 - Manage token refresh and retry logic
@@ -25,11 +24,9 @@ The BRAPClient will automatically:
 ### Initialize the Adapter
 
 ```python
-from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.adapters.brap_adapter.adapter import BRAPAdapter
 
-web3_service = DefaultWeb3Service(config)
-adapter = BRAPAdapter(web3_service=web3_service)
+adapter = BRAPAdapter()
 ```
 
 ### Get Swap Quote
@@ -46,9 +43,10 @@ success, data = await adapter.get_swap_quote(
     slippage=0.01  # 1% slippage
 )
 if success:
-    best_quote = data.get("best_quote", {})
+    quotes = data.get("quotes", {})
+    best_quote = quotes.get("best_quote", {})
     print(f"Output amount: {best_quote.get('output_amount')}")
-    print(f"Fee estimate: {best_quote.get('fee_estimate', {}).get('fee_total_usd')}")
+    print(f"Total fee: {best_quote.get('total_fee')}")
 else:
     print(f"Error: {data}")
 ```
@@ -67,7 +65,8 @@ success, data = await adapter.get_best_quote(
 )
 if success:
     print(f"Best output: {data.get('output_amount')}")
-    print(f"Fee estimate (USD): {data.get('fee_estimate', {}).get('fee_total_usd')}")
+    print(f"Gas fee: {data.get('gas_fee')}")
+    print(f"Bridge fee: {data.get('bridge_fee')}")
 else:
     print(f"Error: {data}")
 ```
@@ -86,8 +85,10 @@ 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 estimate: {data.get('gas_fee')}")
-    print(f"Total fee (USD): {data.get('total_fee')}")
+    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"Price impact: {data.get('price_impact')}")
 else:
     print(f"Error: {data}")
@@ -106,9 +107,9 @@ success, data = await adapter.compare_routes(
 if success:
     print(f"Total routes available: {data.get('total_routes')}")
     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 USD {route.get('fee_estimate', {}).get('fee_total_usd')}\")
+        print(f"Route {i+1}: Output {route.get('output_amount')}, Fee {route.get('total_fee')}")
 else:
     print(f"Error: {data}")
 ```
@@ -166,7 +167,7 @@ success, data = await adapter.get_bridge_quote(
     slippage=0.01
 )
 if success:
-    print(f"Bridge quote received: {data.get('best_quote', {}).get('output_amount')}")
+    print(f"Bridge quote received: {data.get('quotes', {}).get('best_quote', {}).get('output_amount')}")
 else:
     print(f"Error: {data}")
 ```
@@ -190,9 +191,10 @@ if success:
     highest_output = analysis.get("highest_output")
     lowest_fees = analysis.get("lowest_fees")
     fastest = analysis.get("fastest")
-    
+
     print(f"Highest output route: {highest_output.get('output_amount')}")
-    print(f\"Lowest fees route (USD): {lowest_fees.get('fee_estimate', {}).get('fee_total_usd')}\")
+    print(f"Lowest fees route: {lowest_fees.get('total_fee')}")
+    print(f"Fastest route: {fastest.get('estimated_time')} seconds")
 ```
 
 ### Fee Analysis
@@ -210,23 +212,24 @@ 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_usd = float(data.get("total_fee", 0))
-    
+    total_fee = int(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_usd:.4f}")
+    print(f"Total fees: {total_fee / 1e18:.6f} tokens")
 ```
 
 ## API Endpoints
 
 The adapter uses the following Wayfinder API endpoints:
 
-- `GET /api/v1/blockchain/braps/quote/` - Get swap/bridge quotes
+- `POST /api/v1/public/quotes/` - Get swap/bridge quotes
 
 ## Error Handling
 
 All methods return a tuple of `(success: bool, data: Any)` where:
+
 - `success` is `True` if the operation succeeded
 - `data` contains the response data on success or error message on failure