polyrob 0.5.0__py3-none-any.whl

tools/oauth/providers/generic_oauth2.py

@@ -0,0 +1,96 @@
+"""Generic OAuth2 auth-code + refresh-token provider (Item 4).
+
+Driven by a plain config dict (client_id/secret/auth_url/token_url/scopes/
+redirect_uri). The HTTP token POST is injectable (``http_post``) so the provider is
+unit-testable WITHOUT hitting any live endpoint; the default uses ``httpx``.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Awaitable, Callable, Dict, Optional
+from urllib.parse import urlencode
+
+from tools.oauth.provider import OAuthError, OAuthProvider, OAuthToken
+
+# (url, form_data) -> token-endpoint JSON dict
+HttpPost = Callable[[str, Dict[str, Any]], Awaitable[Dict[str, Any]]]
+
+
+class GenericOAuth2Provider(OAuthProvider):
+    def __init__(self, name: str, config: Dict[str, Any], *, http_post: Optional[HttpPost] = None) -> None:
+        self.name = name
+        self.client_id = config["client_id"]
+        self.client_secret = config.get("client_secret", "")
+        self.auth_url = config["auth_url"]
+        self.token_url = config["token_url"]
+        self.scopes = config.get("scopes") or []
+        self.redirect_uri = config.get("redirect_uri")
+        self._http_post = http_post
+
+    def authorize_url(self, *, state: Optional[str] = None, redirect_uri: Optional[str] = None) -> str:
+        params = {
+            "response_type": "code",
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri or self.redirect_uri or "",
+        }
+        if self.scopes:
+            params["scope"] = " ".join(self.scopes)
+        if state:
+            params["state"] = state
+        sep = "&" if "?" in self.auth_url else "?"
+        return f"{self.auth_url}{sep}{urlencode(params)}"
+
+    async def exchange_code(self, code: str, *, redirect_uri: Optional[str] = None) -> OAuthToken:
+        data = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "redirect_uri": redirect_uri or self.redirect_uri or "",
+        }
+        return self._token_from_response(await self._post_token(data))
+
+    async def refresh(self, token: OAuthToken) -> OAuthToken:
+        if not token.refresh_token:
+            raise OAuthError(f"no refresh_token to refresh provider '{self.name}'")
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": token.refresh_token,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        new = self._token_from_response(await self._post_token(data))
+        # Many providers don't rotate the refresh token — keep the old one if absent.
+        if not new.refresh_token:
+            new.refresh_token = token.refresh_token
+        return new
+
+    # -- internals ------------------------------------------------------------
+
+    async def _post_token(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        if self._http_post is not None:
+            return await self._http_post(self.token_url, data)
+        import httpx  # lazy: only needed for the live path
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(self.token_url, data=data)
+            resp.raise_for_status()
+            return resp.json()
+
+    @staticmethod
+    def _token_from_response(resp: Dict[str, Any]) -> OAuthToken:
+        if not resp or "access_token" not in resp:
+            raise OAuthError(f"token endpoint returned no access_token: {resp}")
+        expires_at = None
+        if "expires_in" in resp:
+            try:
+                expires_at = time.time() + float(resp["expires_in"])
+            except (TypeError, ValueError):
+                expires_at = None
+        return OAuthToken(
+            access_token=resp["access_token"],
+            refresh_token=resp.get("refresh_token"),
+            expires_at=expires_at,
+            token_type=resp.get("token_type", "Bearer"),
+            scope=resp.get("scope"),
+        )

tools/perplexity_tool.py

@@ -0,0 +1,280 @@
+import logging
+from typing import List, Optional, Dict, Any
+import json
+import aiohttp
+import ssl
+import certifi
+from core.exceptions import ConfigurationError, APIError, AuthenticationError, ToolError
+from core.config import BotConfig
+from .base_tool import BaseTool
+from tools.controller.views import PerplexitySearchAction, PerplexityAnalyzeAction, PerplexitySourcesAction
+
+class PerplexityTool(BaseTool):
+    """Service for interacting with Perplexity API."""
+    
+    @property
+    def required_services(self) -> Dict[str, str]:
+        """Get required services."""
+        return {
+            'rate_limit_manager': 'Rate limit management'
+        }
+    
+    @property
+    def optional_services(self) -> Dict[str, str]:
+        """Get optional services."""
+        return {
+            'cache_manager': 'Cache for API responses'  # Only need caching
+        }
+
+    def __init__(self, name: str, config: BotConfig, container: Optional[Any] = None):
+        """Initialize Perplexity service."""
+        super().__init__(name=name, config=config, container=container)
+        
+        # Initialize SSL context during construction
+        self.ssl_context = ssl.create_default_context(cafile=certifi.where())
+        self.base_url = "https://api.perplexity.ai/chat/completions"
+        
+        # Enable if API key is present
+        self._enabled = bool(getattr(config, 'perplexity_api_key', None))
+        if not self._enabled:
+            self.logger.warning("Perplexity API key not found, service will be disabled")
+
+    @property
+    def required_config(self) -> Dict[str, str]:
+        """Get required configuration keys."""
+        return {
+            'perplexity_api_key': 'Perplexity API key'
+        }
+    
+    async def _initialize(self) -> None:
+        """Initialize Perplexity service."""
+        try:
+            # Services are automatically injected by BaseService
+            # Just validate API key BEFORE registering actions
+            if not self.config.perplexity_api_key or self.config.perplexity_api_key == "placeholder":
+                self.logger.warning("Perplexity API key not configured")
+                self._enabled = False
+                # Mark service as unavailable but don't raise exception
+                from tools.base_tool import ToolStatus
+                self._status = ToolStatus.FAILED
+                # Don't register actions for disabled service
+                return
+
+            # Only register actions if we have a valid API key
+            # Call parent's _initialize to register decorated actions
+            await super()._initialize()
+            
+            # Test API connection
+            try:
+                await self._test_api_connection()
+            except Exception as e:
+                self.logger.error(f"Failed to connect to Perplexity API: {e}")
+                self._enabled = False
+                from tools.base_tool import ToolStatus
+                self._status = ToolStatus.FAILED
+                return
+
+        except Exception as e:
+            self.logger.error(f"Failed to initialize Perplexity service: {e}")
+            # Don't raise for optional services - mark as unavailable
+            from tools.base_tool import ToolStatus
+            self._status = ToolStatus.FAILED
+            self._enabled = False
+
+    async def _test_api_connection(self) -> None:
+        """Test API connection."""
+        try:
+            # Make a minimal test request
+            messages = [
+                {"role": "user", "content": "test"}
+            ]
+            result = await self._make_request(messages)
+            if "error" in result:
+                raise APIError(f"API test failed: {result['error']}")
+            self.logger.info("Perplexity API connection test successful")
+        except AuthenticationError as e:
+            self.logger.error(f"Perplexity API authentication failed: {e}")
+            self.logger.error("The API key appears to be invalid. Please update PERPLEXITY_API_KEY in your .env file")
+            self.logger.error("You can generate a new API key at: https://www.perplexity.ai/settings/api")
+            raise
+        except Exception as e:
+            self.logger.error(f"Perplexity API connection test failed: {e}")
+            raise
+
+    async def _cleanup(self) -> None:
+        """Cleanup Perplexity service resources."""
+        try:
+            # Close any open connections
+            if hasattr(self, 'session') and self.session:
+                await self.session.close()
+                
+            self.logger.info("Perplexity service cleaned up successfully")
+            
+        except Exception as e:
+            self.logger.error(f"Error during Perplexity service cleanup: {e}")
+            raise ToolError(f"Failed to cleanup Perplexity service: {e}")
+            
+    @BaseTool.action(
+        'Search for information using Perplexity AI',
+        param_model=PerplexitySearchAction
+    )
+    async def perplexity_search(self, params: PerplexitySearchAction):
+        """Search using Perplexity API."""
+        await self.ensure_initialized()
+        
+        if not self._enabled:
+            raise ConfigurationError("Perplexity service is not enabled")
+            
+        try:
+            query = params.query.strip()
+            if not query:
+                return "Please provide a search query."
+            
+            messages = [
+                {"role": "system", "content": "You are a helpful AI assistant that provides accurate and concise information."},
+                {"role": "user", "content": query}
+            ]
+            
+            result = await self._make_request(messages)
+            if "error" in result:
+                return f"Error: {result['error']}"
+            
+            try:
+                content = result["choices"][0]["message"]["content"]
+                # Limit response size to prevent overwhelming the agent
+                MAX_RESPONSE_LENGTH = 50000  # 50k chars (reasonable for search responses)
+                if len(content) > MAX_RESPONSE_LENGTH:
+                    self.logger.warning(f"Perplexity response truncated from {len(content)} to {MAX_RESPONSE_LENGTH} characters")
+                    content = content[:MAX_RESPONSE_LENGTH] + "\n\n[Response truncated due to size...]"
+                return content
+            except (KeyError, IndexError) as e:
+                return f"Error parsing response: {str(e)}"
+
+        except AuthenticationError as e:
+            self.logger.error(f"Perplexity authentication error: {str(e)}")
+            self.logger.error("The API key is invalid. Please update PERPLEXITY_API_KEY in config/.env.development")
+            self.logger.error("Generate a new key at: https://www.perplexity.ai/settings/api")
+            raise APIError(f"Search failed: Invalid API key. Please update PERPLEXITY_API_KEY in the configuration.")
+        except Exception as e:
+            self.logger.error(f"Perplexity search error: {str(e)}")
+            raise APIError(f"Search failed: {str(e)}")
+            
+    @BaseTool.action(
+        'Get detailed analysis on a topic using Perplexity AI',
+        param_model=PerplexityAnalyzeAction
+    )
+    async def perplexity_analyze(self, params: PerplexityAnalyzeAction):
+        """Get detailed analysis from Perplexity."""
+        await self.ensure_initialized()
+        
+        try:
+            topic = params.topic.strip()
+            if not topic:
+                return "Please provide a topic to analyze."
+            
+            messages = [
+                {"role": "system", "content": "You are an analytical AI assistant. Provide a detailed analysis of the given topic."},
+                {"role": "user", "content": f"Please provide a detailed analysis of: {topic}"}
+            ]
+            
+            result = await self._make_request(messages)
+            if "error" in result:
+                return result["error"]
+            
+            try:
+                content = result["choices"][0]["message"]["content"]
+                # Limit response size to prevent overwhelming the agent
+                MAX_RESPONSE_LENGTH = 50000  # 50k chars (reasonable for analysis responses)
+                if len(content) > MAX_RESPONSE_LENGTH:
+                    self.logger.warning(f"Perplexity response truncated from {len(content)} to {MAX_RESPONSE_LENGTH} characters")
+                    content = content[:MAX_RESPONSE_LENGTH] + "\n\n[Response truncated due to size...]"
+                return content
+            except (KeyError, IndexError) as e:
+                return f"Error parsing response: {str(e)}"
+        except Exception as e:
+            self.logger.error(f"Perplexity analyze error: {str(e)}")
+            raise
+            
+    @BaseTool.action(
+        'Get trusted sources and references on a topic using Perplexity AI',
+        param_model=PerplexitySourcesAction
+    )
+    async def perplexity_sources(self, params: PerplexitySourcesAction):
+        """Get sources for a query."""
+        await self.ensure_initialized()
+        
+        query = params.topic.strip()
+        if not query:
+            return "Please provide a query to get sources for."
+            
+        messages = [
+            {"role": "system", "content": "You are a research assistant. Provide relevant sources and references for the query."},
+            {"role": "user", "content": f"Please provide sources and references for: {query}"}
+        ]
+        
+        result = await self._make_request(messages)
+        if "error" in result:
+            return result["error"]
+            
+        try:
+            return result["choices"][0]["message"]["content"]
+        except (KeyError, IndexError) as e:
+            return f"Error parsing response: {str(e)}"
+
+    async def ensure_initialized(self) -> None:
+        """Ensure service is initialized."""
+        if not self._initialized:
+            await self.initialize()
+
+    async def test_connection(self) -> bool:
+        """Test if the Perplexity API is accessible and properly configured"""
+        if not self.config.perplexity_api_key:
+            return False
+            
+        try:
+            # Make a minimal test request
+            messages = [
+                {"role": "user", "content": "test"}
+            ]
+            result = await self._make_request(messages)
+            return "error" not in result
+        except Exception as e:
+            self.logger.warning(f"Perplexity API connection test failed: {str(e)}")
+            return False
+        
+    async def _make_request(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
+        """Make a request to the Perplexity API."""
+        if not self.config.perplexity_api_key:
+            raise ConfigurationError("Perplexity API key not configured")
+            
+        headers = {
+            "Authorization": f"Bearer {self.config.perplexity_api_key}",
+            "Content-Type": "application/json"
+        }
+        
+        data = {
+            "model": "sonar",
+            "messages": messages
+        }
+        
+        try:
+            # Use SSL context in ClientSession
+            conn = aiohttp.TCPConnector(ssl=self.ssl_context)
+            async with aiohttp.ClientSession(connector=conn) as session:
+                async with session.post(
+                    self.base_url,
+                    headers=headers,
+                    json=data,
+                    ssl=self.ssl_context
+                ) as response:
+                    if response.status == 200:
+                        return await response.json()
+                    elif response.status == 401:
+                        raise AuthenticationError("Invalid Perplexity API key")
+                    else:
+                        error_text = await response.text()
+                        self.logger.error(f"Perplexity API error: {error_text}")
+                        raise APIError(f"API error: {response.status} - {error_text}")
+        except aiohttp.ClientError as e:
+            self.logger.error(f"Request error: {str(e)}")
+            raise APIError(f"Request failed: {str(e)}")

tools/polymarket/__init__.py

@@ -0,0 +1,41 @@
+"""
+Polymarket Integration Package.
+
+Provides access to Polymarket prediction markets through PolymarketTool,
+which uses direct API integration with Gamma + CLOB APIs.
+
+Usage:
+    polymarket.search_markets(query="...")
+    polymarket.get_trending_markets(limit=10)
+    polymarket.get_market_details(market_id="...")
+"""
+
+from tools.polymarket.service import PolymarketTool, PolymarketDataTool
+
+from tools.polymarket.models import (
+    PolymarketCredentials,
+    TradingLimits,
+    ExecutionResult,
+    ApiCredentials,
+    POLYGON_MAINNET,
+    POLYGON_AMOY_TESTNET,
+    SIGNATURE_TYPE_EOA,
+    SIGNATURE_TYPE_MAGIC,
+    SIGNATURE_TYPE_PROXY,
+    MIN_ORDER_VALUE_USD,
+)
+
+__all__ = [
+    "PolymarketTool",
+    "PolymarketDataTool",
+    "PolymarketCredentials",
+    "TradingLimits",
+    "ExecutionResult",
+    "ApiCredentials",
+    "POLYGON_MAINNET",
+    "POLYGON_AMOY_TESTNET",
+    "SIGNATURE_TYPE_EOA",
+    "SIGNATURE_TYPE_MAGIC",
+    "SIGNATURE_TYPE_PROXY",
+    "MIN_ORDER_VALUE_USD",
+]

tools/polymarket/clob_adapter.py

@@ -0,0 +1,76 @@
+"""Single seam for the Polymarket CLOB trading client.
+
+Polymarket archived `py-clob-client` in 2026 ("no longer functional"). The current
+maintained low-level client is `py-clob-client-v2`. This module is the ONE place that
+import happens, so a missing/incompatible client is a LOUD, actionable failure instead
+of silently dropping every trading action (the prior behavior, which degraded the tool
+to read-only with no signal).
+
+Contract:
+- The READ surface never imports this module.
+- The TRADE surface calls ``require_clob()`` before any order action; absence yields a
+  typed ``PolymarketDependencyError`` with an install hint, surfaced to the operator.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from core.exceptions import ToolError
+
+INSTALL_HINT = "pip install py-clob-client-v2"
+
+# The archived ``py_clob_client`` is intentionally NOT imported here — it is no longer
+# functional. Only the maintained v2 client is supported.
+try:
+    from py_clob_client_v2.client import ClobClient  # type: ignore
+    from py_clob_client_v2.clob_types import (  # type: ignore
+        ApiCreds,
+        OrderArgs,
+        OrderType,
+        BalanceAllowanceParams,
+        AssetType,
+    )
+
+    CLOB_AVAILABLE = True
+    CLOB_IMPORT_ERROR: Optional[str] = None
+    try:  # version is best-effort, never load-bearing
+        from importlib.metadata import version as _pkg_version
+
+        CLOB_VERSION: Optional[str] = _pkg_version("py-clob-client-v2")
+    except Exception:  # pragma: no cover - metadata absent
+        CLOB_VERSION = None
+except Exception as _exc:  # ImportError or any transitive failure
+    ClobClient = None  # type: ignore
+    ApiCreds = None  # type: ignore
+    OrderArgs = None  # type: ignore
+    OrderType = None  # type: ignore
+    BalanceAllowanceParams = None  # type: ignore
+    AssetType = None  # type: ignore
+    CLOB_AVAILABLE = False
+    CLOB_IMPORT_ERROR = f"{type(_exc).__name__}: {_exc}"
+    CLOB_VERSION = None
+
+
+class PolymarketDependencyError(ToolError):
+    """Raised when a Polymarket trade action needs the CLOB client but it is absent."""
+
+
+def trade_capability() -> Dict[str, Any]:
+    """Report whether the trade surface can function, with an actionable hint."""
+    if CLOB_AVAILABLE:
+        return {"available": True, "reason": "py-clob-client-v2 importable", "install_hint": INSTALL_HINT, "version": CLOB_VERSION}
+    return {
+        "available": False,
+        "reason": f"Polymarket trading client unavailable ({CLOB_IMPORT_ERROR})",
+        "install_hint": INSTALL_HINT,
+        "version": None,
+    }
+
+
+def require_clob() -> None:
+    """Raise a typed, actionable error if the CLOB trading client is missing."""
+    if not CLOB_AVAILABLE:
+        raise PolymarketDependencyError(
+            f"Polymarket trading requires py-clob-client-v2 ({INSTALL_HINT}); "
+            f"import failed: {CLOB_IMPORT_ERROR}"
+        )

tools/polymarket/models.py

@@ -0,0 +1,182 @@
+"""
+Polymarket data models.
+
+Defines credentials, trading limits, and execution results.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# Chain IDs
+POLYGON_MAINNET = 137
+POLYGON_AMOY_TESTNET = 80002
+
+# Signature Types for CLOB client authentication
+SIGNATURE_TYPE_EOA = 0      # Standard EOA (MetaMask, hardware wallets)
+SIGNATURE_TYPE_MAGIC = 1    # Email/Magic wallet (delegated signing)
+SIGNATURE_TYPE_PROXY = 2    # Browser wallet proxy (Polymarket website users)
+
+# Trading Constants
+MIN_ORDER_VALUE_USD = 1.00
+
+# Polymarket Contract Addresses (Polygon)
+USDC_ADDRESS = "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
+CTF_ADDRESS = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"
+EXCHANGE_ADDRESS = "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E"
+NEG_RISK_EXCHANGE = "0xC5d563A36AE78145C45a50134d48A1215220f80a"
+NEG_RISK_ADAPTER = "0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296"
+
+
+@dataclass
+class TradingLimits:
+    """
+    Trading safety limits for Polymarket operations.
+
+    All limits are enforced at the tool level before
+    making API calls.
+    """
+    max_order_size_usd: int = 1000
+    max_total_exposure_usd: int = 5000
+    max_position_per_market_usd: int = 2000
+    min_liquidity_required: int = 10000
+    max_spread_tolerance: float = 0.05
+    require_confirmation_above_usd: int = 500
+    enable_autonomous_trading: bool = False
+    allowed_categories: List[str] = field(default_factory=lambda: ["*"])
+    blocked_markets: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for storage."""
+        return {
+            "max_order_size_usd": self.max_order_size_usd,
+            "max_total_exposure_usd": self.max_total_exposure_usd,
+            "max_position_per_market_usd": self.max_position_per_market_usd,
+            "min_liquidity_required": self.min_liquidity_required,
+            "max_spread_tolerance": self.max_spread_tolerance,
+            "require_confirmation_above_usd": self.require_confirmation_above_usd,
+            "enable_autonomous_trading": self.enable_autonomous_trading,
+            "allowed_categories": self.allowed_categories,
+            "blocked_markets": self.blocked_markets,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TradingLimits":
+        """Create from dictionary."""
+        if not data:
+            return cls()
+        return cls(
+            max_order_size_usd=data.get("max_order_size_usd", 1000),
+            max_total_exposure_usd=data.get("max_total_exposure_usd", 5000),
+            max_position_per_market_usd=data.get("max_position_per_market_usd", 2000),
+            min_liquidity_required=data.get("min_liquidity_required", 10000),
+            max_spread_tolerance=data.get("max_spread_tolerance", 0.05),
+            require_confirmation_above_usd=data.get("require_confirmation_above_usd", 500),
+            enable_autonomous_trading=data.get("enable_autonomous_trading", False),
+            allowed_categories=data.get("allowed_categories", ["*"]),
+            blocked_markets=data.get("blocked_markets", []),
+        )
+
+
+@dataclass
+class ApiCredentials:
+    """
+    L2 API credentials for authenticated CLOB operations.
+
+    These are created via the CLOB API using the private key,
+    and stored encrypted for reuse.
+    """
+    api_key: str
+    api_secret: str  # Same as passphrase in some contexts
+    api_passphrase: str
+    created_at: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary (secrets included for encrypted storage)."""
+        return {
+            "api_key": self.api_key,
+            "api_secret": self.api_secret,
+            "api_passphrase": self.api_passphrase,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Optional["ApiCredentials"]:
+        """Create from dictionary."""
+        if not data or not data.get("api_key"):
+            return None
+        return cls(
+            api_key=data.get("api_key", ""),
+            api_secret=data.get("api_secret", ""),
+            api_passphrase=data.get("api_passphrase", ""),
+            created_at=data.get("created_at"),
+        )
+
+
+@dataclass
+class PolymarketCredentials:
+    """
+    User's Polymarket credentials with proxy wallet support.
+
+    The private_key is stored encrypted in the database and only
+    decrypted in memory when needed for API authentication.
+
+    L2 API credentials (api_credentials) are created via CLOB API
+    and stored for reuse to avoid repeated key creation.
+
+    Polymarket uses a proxy wallet system:
+    - wallet_address: EOA address (derived from private key)
+    - proxy_wallet_address: Smart contract wallet (shown on Polymarket profile)
+
+    Most Polymarket website users need signature_type=2 (PROXY).
+    """
+    user_id: str
+    wallet_address: Optional[str] = None  # EOA address (derived from private key)
+    proxy_wallet_address: Optional[str] = None  # Smart contract wallet (from Polymarket profile)
+    private_key: Optional[str] = field(default=None, repr=False)  # Never log this
+    signature_type: int = SIGNATURE_TYPE_PROXY  # Default to proxy (2) - most common
+    demo_mode: bool = True
+    enabled: bool = True
+    chain_id: int = POLYGON_MAINNET
+    trading_limits: TradingLimits = field(default_factory=TradingLimits)
+    api_credentials: Optional[ApiCredentials] = field(default=None, repr=False)
+    allowances_verified: bool = False  # Track if allowances are configured
+
+    @property
+    def funder_address(self) -> Optional[str]:
+        """
+        Get the address that holds funds (proxy wallet if set, else EOA).
+
+        This is the address used for balance checks and as the 'funder'
+        parameter in CLOB client for proxy wallet users.
+        """
+        return self.proxy_wallet_address or self.wallet_address
+
+    def is_configured(self) -> bool:
+        """Check if credentials are properly configured."""
+        if self.demo_mode:
+            return True
+        return bool(self.wallet_address and self.private_key)
+
+    def has_api_credentials(self) -> bool:
+        """Check if L2 API credentials are available."""
+        return self.api_credentials is not None
+
+    def can_trade(self) -> bool:
+        """Check if user can perform trading operations."""
+        return (
+            not self.demo_mode
+            and self.enabled
+            and self.is_configured()
+            and self.trading_limits.enable_autonomous_trading
+        )
+
+
+@dataclass
+class ExecutionResult:
+    """Result from executing a Polymarket action."""
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    tool_name: Optional[str] = None
+    execution_time_ms: float = 0.0