intentkit 0.6.21.dev2__py3-none-any.whl → 0.6.22__py3-none-any.whl

intentkit/skills/dexscreener/get_tokens_info.py

@@ -0,0 +1,213 @@
+import logging
+from typing import Any, List, Type
+
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from intentkit.skills.dexscreener.base import DexScreenerBaseTool
+from intentkit.skills.dexscreener.model.search_token_response import (
+    SearchTokenResponseModel,
+)
+from intentkit.skills.dexscreener.utils import (
+    API_ENDPOINTS,
+    MAX_TOKENS_BATCH,
+    RATE_LIMITS,
+    create_error_response,
+    create_no_results_response,
+    format_success_response,
+    get_liquidity_value,
+    group_pairs_by_token,
+    handle_validation_error,
+    truncate_large_fields,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GetTokensInfoInput(BaseModel):
+    """Input schema for the DexScreener get_tokens_info tool."""
+
+    chain_id: str = Field(
+        description="The blockchain chain ID (e.g., 'ethereum', 'solana', 'bsc', 'polygon', 'arbitrum', 'base', 'avalanche')"
+    )
+    token_addresses: List[str] = Field(
+        description=f"List of token contract addresses to retrieve info for (maximum {MAX_TOKENS_BATCH} addresses). "
+        "Each address should be in the format '0x1234...abcd' for Ethereum-based chains."
+    )
+
+    @field_validator("token_addresses")
+    @classmethod
+    def validate_token_addresses(cls, v: List[str]) -> List[str]:
+        if not v:
+            raise ValueError("At least one token address is required")
+        if len(v) > MAX_TOKENS_BATCH:
+            raise ValueError(f"Maximum {MAX_TOKENS_BATCH} token addresses allowed")
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_addresses = []
+        for addr in v:
+            if addr not in seen:
+                seen.add(addr)
+                unique_addresses.append(addr)
+        return unique_addresses
+
+
+class GetTokensInfo(DexScreenerBaseTool):
+    """
+    Tool to get detailed information for multiple tokens at once on DexScreener.
+    """
+
+    name: str = "dexscreener_get_tokens_info"
+    description: str = (
+        f"Retrieves detailed trading pair information for multiple tokens (up to {MAX_TOKENS_BATCH}) "
+        "using chain ID and a list of token addresses. For each token, returns all available "
+        "trading pairs with price, volume, liquidity, market data, and DEX information. "
+        "This is more efficient than making individual calls when you need info for multiple tokens. "
+        "Use this tool for portfolio analysis or comparing multiple tokens at once."
+    )
+    args_schema: Type[BaseModel] = GetTokensInfoInput
+
+    async def _arun(
+        self,
+        chain_id: str,
+        token_addresses: List[str],
+        **kwargs: Any,
+    ) -> str:
+        """Implementation to get information for multiple tokens."""
+
+        # Apply rate limiting
+        await self.user_rate_limit_by_category(
+            user_id=f"{self.category}{self.name}",
+            limit=RATE_LIMITS["tokens"],
+            minutes=1,
+        )
+
+        logger.info(
+            f"Executing DexScreener get_tokens_info tool with chain_id: '{chain_id}', "
+            f"token_addresses: {len(token_addresses)} tokens"
+        )
+
+        try:
+            # Construct API path - addresses are comma-separated
+            addresses_param = ",".join(token_addresses)
+            api_path = f"{API_ENDPOINTS['tokens']}/{chain_id}/{addresses_param}"
+
+            data, error_details = await self._get(path=api_path)
+
+            if error_details:
+                return await self._handle_error_response(error_details)
+
+            if not data:
+                logger.error(f"No data returned for tokens on {chain_id}")
+                return create_error_response(
+                    error_type="empty_success",
+                    message="API call returned empty success response.",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "token_addresses": token_addresses,
+                    },
+                )
+
+            try:
+                # Validate response using SearchTokenResponseModel since API returns similar structure
+                result = SearchTokenResponseModel.model_validate(data)
+            except ValidationError as e:
+                return handle_validation_error(
+                    e, f"{chain_id}/{len(token_addresses)} tokens", len(str(data))
+                )
+
+            if not result.pairs:
+                return create_no_results_response(
+                    f"{chain_id} - {len(token_addresses)} tokens",
+                    reason="no trading pairs found for any of the specified tokens",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "requested_addresses": token_addresses,
+                        "tokens_data": {},
+                        "all_pairs": [],
+                        "found_tokens": 0,
+                        "total_pairs": 0,
+                    },
+                )
+
+            pairs_list = [p for p in result.pairs if p is not None]
+
+            if not pairs_list:
+                return create_no_results_response(
+                    f"{chain_id} - {len(token_addresses)} tokens",
+                    reason="all pairs were null or invalid",
+                    additional_data={
+                        "chain_id": chain_id,
+                        "requested_addresses": token_addresses,
+                        "tokens_data": {},
+                        "all_pairs": [],
+                        "found_tokens": 0,
+                        "total_pairs": 0,
+                    },
+                )
+
+            # Group pairs by token address for better organization
+            tokens_data = group_pairs_by_token(pairs_list)
+
+            # Sort pairs within each token by liquidity (highest first)
+            for token_addr, pairs in tokens_data.items():
+                try:
+                    pairs.sort(key=get_liquidity_value, reverse=True)
+                except Exception as sort_err:
+                    logger.warning(
+                        f"Failed to sort pairs for token {token_addr}: {sort_err}"
+                    )
+
+            logger.info(
+                f"Found {len(pairs_list)} total pairs across {len(tokens_data)} tokens "
+                f"for {len(token_addresses)} requested addresses on {chain_id}"
+            )
+
+            return format_success_response(
+                {
+                    "tokens_data": {
+                        addr: [p.model_dump() for p in pairs]
+                        for addr, pairs in tokens_data.items()
+                    },
+                    "all_pairs": [p.model_dump() for p in pairs_list],
+                    "chain_id": chain_id,
+                    "requested_addresses": token_addresses,
+                    "found_tokens": len(tokens_data),
+                    "total_pairs": len(pairs_list),
+                }
+            )
+
+        except Exception as e:
+            return await self._handle_unexpected_runtime_error(
+                e, f"{chain_id}/{len(token_addresses)} tokens"
+            )
+
+    async def _handle_error_response(self, error_details: dict) -> str:
+        """Formats error details (from _get) into a JSON string."""
+        if error_details.get("error_type") in [
+            "connection_error",
+            "parsing_error",
+            "unexpected_error",
+        ]:
+            logger.error(
+                f"DexScreener get_tokens_info tool encountered an error: {error_details}"
+            )
+        else:  # api_error
+            logger.warning(f"DexScreener API returned an error: {error_details}")
+
+        # Truncate potentially large fields before returning to user/LLM
+        truncated_details = truncate_large_fields(error_details)
+        return format_success_response(truncated_details)
+
+    async def _handle_unexpected_runtime_error(
+        self, e: Exception, query_info: str
+    ) -> str:
+        """Formats unexpected runtime exception details into a JSON string."""
+        logger.exception(
+            f"An unexpected runtime error occurred in get_tokens_info tool _arun method for {query_info}: {e}"
+        )
+        return create_error_response(
+            error_type="runtime_error",
+            message="An unexpected internal error occurred processing the tokens info request",
+            details=str(e),
+            additional_data={"query_info": query_info},
+        )

intentkit/skills/dexscreener/schema.json

@@ -34,7 +34,52 @@
                         "Agent Owner + All Users",
                         "Agent Owner Only"
                     ],
-                    "description": "Searches on DexScreener for token pairs matching a query (symbol, name, address). Returns up to 50 pairs sorted by 'liquidity' or 'volume24h' (required input), including price, volume, etc. Use this tool to find token information based on user queries.",
+                    "description": "Searches on DexScreener for token pairs matching a query (symbol, name, address). Returns up to 25 pairs sorted by 'liquidity' or 'volume' with timeframe options, including price, volume, etc. Use this tool to find token information based on user queries.",
+                    "default": "disabled"
+                },
+                "get_pair_info": {
+                    "type": "string",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "Retrieves detailed information about a specific trading pair using chain ID and pair address. Returns comprehensive data including current price, volume, liquidity, price changes, market cap, FDV, transaction counts, and social links.",
+                    "default": "disabled"
+                },
+                "get_token_pairs": {
+                    "type": "string",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "Finds all trading pairs for a specific token using chain ID and token address. Returns a list of all pools/pairs where this token is traded, including pair addresses, DEX information, liquidity, volume, and pricing data for each pair.",
+                    "default": "disabled"
+                },
+                "get_tokens_info": {
+                    "type": "string",
+                    "enum": [
+                        "disabled",
+                        "public",
+                        "private"
+                    ],
+                    "x-enum-title": [
+                        "Disabled",
+                        "Agent Owner + All Users",
+                        "Agent Owner Only"
+                    ],
+                    "description": "Retrieves detailed trading pair information for multiple tokens (up to 30) using chain ID and a list of token addresses. More efficient than making individual calls when you need info for multiple tokens. Use for portfolio analysis or comparing multiple tokens at once.",
                     "default": "disabled"
                 }
             }

intentkit/skills/dexscreener/search_token.py

@@ -1,48 +1,32 @@
-import json
 import logging
-from enum import Enum
-from typing import (
-    Any,
-    Callable,
-    Literal,
-    Optional,
-    Type,
-)
+from typing import Any, Optional, Type
 
 from pydantic import BaseModel, Field, ValidationError
 
 from intentkit.skills.dexscreener.base import DexScreenerBaseTool
 from intentkit.skills.dexscreener.model.search_token_response import (
-    PairModel,
     SearchTokenResponseModel,
 )
+from intentkit.skills.dexscreener.utils import (
+    API_ENDPOINTS,
+    MAX_SEARCH_RESULTS,
+    SEARCH_DISCLAIMER,
+    QueryType,
+    SortBy,
+    VolumeTimeframe,
+    create_error_response,
+    create_no_results_response,
+    determine_query_type,
+    filter_address_pairs,
+    filter_ticker_pairs,
+    format_success_response,
+    handle_validation_error,
+    sort_pairs_by_criteria,
+    truncate_large_fields,
+)
 
 logger = logging.getLogger(__name__)
 
-MAX_RESULTS_LIMIT = 25  # limit to 25 pair entries
-SEARCH_TOKEN_API_PATH = "/latest/dex/search"
-
-# Define the allowed sort options, including multiple volume types
-SortByOption = Literal["liquidity", "volume"]
-VolumeTimeframeOption = Literal["24_hour", "6_hour", "1_hour", "5_minutes"]
-
-
-class QueryType(str, Enum):
-    TEXT = "TEXT"
-    TICKER = "TICKER"
-    ADDRESS = "ADDRESS"
-
-
-# this will bring aloside with pairs information
-DISCLAIMER_TEXT = {
-    "disclaimer": (
-        "Search results may include unofficial, duplicate, or potentially malicious tokens. "
-        "If multiple unrelated tokens share a similar name or ticker, ask the user for the exact token address. "
-        "If the correct token is not found, re-run the tool using the provided address. "
-        "Also advise the user to verify the token's legitimacy via its official social links included in the result."
-    )
-}
-
 
 class SearchTokenInput(BaseModel):
     """Input schema for the DexScreener search_token tool."""
@@ -50,13 +34,13 @@ class SearchTokenInput(BaseModel):
     query: str = Field(
         description="The search query string (e.g., token symbol 'WIF', pair address, token address '0x...', token name 'Dogwifhat', or ticker '$WIF'). Prefixing with '$' filters results to match the base token symbol exactly (case-insensitive)."
     )
-    sort_by: Optional[SortByOption] = Field(
-        default="liquidity",
+    sort_by: Optional[SortBy] = Field(
+        default=SortBy.LIQUIDITY,
         description="Sort preference for the results. Options: 'liquidity' (default) or 'volume'",
     )
-    volume_timeframe: Optional[VolumeTimeframeOption] = Field(
-        default="24_hour",
-        description=f"define which timeframe should we use if the 'sort_by' is `volume` avalable options are {VolumeTimeframeOption}",
+    volume_timeframe: Optional[VolumeTimeframe] = Field(
+        default=VolumeTimeframe.TWENTY_FOUR_HOUR,
+        description="Define which timeframe should we use if the 'sort_by' is 'volume'. Available options: '5_minutes', '1_hour', '6_hour', '24_hour'",
     )
 
 
@@ -72,7 +56,7 @@ class SearchToken(DexScreenerBaseTool):
         f"If the query starts with '$', it filters results to only include pairs where the base token symbol exactly matches the ticker (case-insensitive). "
         f"Returns a list of matching pairs with details like price, volume, liquidity, etc., "
         f"sorted by the specified criteria (via 'sort_by': 'liquidity', 'volume'; defaults to 'liquidity'), "
-        f"limited to the top {MAX_RESULTS_LIMIT}. "
+        f"limited to the top {MAX_SEARCH_RESULTS}. "
         f"Use this tool to find token information based on user queries."
     )
     args_schema: Type[BaseModel] = SearchTokenInput
@@ -80,8 +64,8 @@ class SearchToken(DexScreenerBaseTool):
     async def _arun(
         self,
         query: str,
-        sort_by: Optional[SortByOption] = "liquidity",
-        volume_timeframe: Optional[VolumeTimeframeOption] = "24_hour",
+        sort_by: Optional[SortBy] = SortBy.LIQUIDITY,
+        volume_timeframe: Optional[VolumeTimeframe] = VolumeTimeframe.TWENTY_FOUR_HOUR,
         **kwargs: Any,
     ) -> str:
         """Implementation to search token, with filtering based on query type."""
@@ -95,11 +79,11 @@ class SearchToken(DexScreenerBaseTool):
             minutes=1,
         )
 
-        sort_by = sort_by or "liquidity"
-        volume_timeframe = volume_timeframe or "24_hour"
+        sort_by = sort_by or SortBy.LIQUIDITY
+        volume_timeframe = volume_timeframe or VolumeTimeframe.TWENTY_FOUR_HOUR
 
         # Determine query type
-        query_type = self.get_query_type(query)
+        query_type = determine_query_type(query)
 
         # Process query based on type
         if query_type == QueryType.TICKER:
@@ -115,60 +99,28 @@ class SearchToken(DexScreenerBaseTool):
             f"sort_by: {sort_by}"
         )
 
-        ### --- sort functions ---
-        def get_liquidity_usd(pair: PairModel) -> float:
-            return (
-                pair.liquidity.usd
-                if pair.liquidity and pair.liquidity.usd is not None
-                else 0.0
-            )
-
-        def get_volume(pair: PairModel) -> float:
-            if not pair.volume:
-                return 0.0
-            return {
-                "24_hour": pair.volume.h24,
-                "6_hour": pair.volume.h6,
-                "1_hour": pair.volume.h1,
-                "5_minutes": pair.volume.m5,
-            }.get(volume_timeframe, 0.0) or 0.0
-
-        def get_sort_key_func() -> Callable[[PairModel], float]:
-            if sort_by == "liquidity":
-                return get_liquidity_usd
-            if sort_by == "volume":
-                return get_volume
-            logger.warning(
-                f"Invalid sort_by value '{sort_by}', defaulting to liquidity."
-            )
-            return get_liquidity_usd
-
-        ### --- END sort functions ---
-
         try:
             data, error_details = await self._get(
-                path=SEARCH_TOKEN_API_PATH, params={"q": search_query}
+                path=API_ENDPOINTS["search"], params={"q": search_query}
             )
 
             if error_details:
                 return await self._handle_error_response(error_details)
             if not data:
                 logger.error(f"No data or error details returned for query '{query}'")
-                return json.dumps(
-                    {
-                        "error": "API call returned empty success response.",
-                        "error_type": "empty_success",
-                    },
-                    indent=2,
+                return create_error_response(
+                    error_type="empty_success",
+                    message="API call returned empty success response.",
+                    additional_data={"query": query},
                 )
 
             try:
                 result = SearchTokenResponseModel.model_validate(data)
             except ValidationError as e:
-                return await self._handle_validation_error(e, query, data)
+                return handle_validation_error(e, query, len(str(data)))
 
             if not result.pairs:
-                return await self._no_pairs_found_response(
+                return create_no_results_response(
                     query, reason="returned null or empty for pairs"
                 )
 
@@ -176,83 +128,34 @@ class SearchToken(DexScreenerBaseTool):
 
             # Apply filtering based on query type
             if query_type == QueryType.TICKER and target_ticker:
-                pairs_list = [
-                    p
-                    for p in pairs_list
-                    if p.baseToken
-                    and p.baseToken.symbol
-                    and p.baseToken.symbol.upper() == target_ticker
-                ]
+                pairs_list = filter_ticker_pairs(pairs_list, target_ticker)
                 if not pairs_list:
-                    return await self._no_pairs_found_response(
+                    return create_no_results_response(
                         query, reason=f"no match for ticker '${target_ticker}'"
                     )
             elif query_type == QueryType.ADDRESS:
-                # Filter by address (checking pairAddress, baseToken.address, quoteToken.address)
-                pairs_list = [
-                    p
-                    for p in pairs_list
-                    if (p.pairAddress and p.pairAddress.lower() == search_query.lower())
-                    or (
-                        p.baseToken
-                        and p.baseToken.address
-                        and p.baseToken.address.lower() == search_query.lower()
-                    )
-                    or (
-                        p.quoteToken
-                        and p.quoteToken.address
-                        and p.quoteToken.address.lower() == search_query.lower()
-                    )
-                ]
+                pairs_list = filter_address_pairs(pairs_list, search_query)
                 if not pairs_list:
-                    return await self._no_pairs_found_response(
+                    return create_no_results_response(
                         query, reason=f"no match for address '{search_query}'"
                     )
 
-            try:
-                sort_func = get_sort_key_func()
-                pairs_list.sort(key=sort_func, reverse=True)
-            except Exception as sort_err:
-                logger.error(f"Sorting failed: {sort_err}", exc_info=True)
-                return json.dumps(
-                    {
-                        "error": "Failed to sort results.",
-                        "error_type": "sorting_error",
-                        "details": str(sort_err),
-                        "unsorted_results": [
-                            p.model_dump() for p in pairs_list[:MAX_RESULTS_LIMIT]
-                        ],
-                        **DISCLAIMER_TEXT,
-                    },
-                    indent=2,
-                )
+            # Sort pairs by specified criteria
+            pairs_list = sort_pairs_by_criteria(pairs_list, sort_by, volume_timeframe)
 
-            final_count = min(len(pairs_list), MAX_RESULTS_LIMIT)
+            # If sorting failed, pairs_list will be returned unchanged by the utility function
+
+            final_count = min(len(pairs_list), MAX_SEARCH_RESULTS)
             logger.info(f"Returning {final_count} pairs for query '{query}'")
-            return json.dumps(
+            return format_success_response(
                 {
-                    **DISCLAIMER_TEXT,
-                    "pairs": [p.model_dump() for p in pairs_list[:MAX_RESULTS_LIMIT]],
-                },
-                indent=2,
+                    **SEARCH_DISCLAIMER,
+                    "pairs": [p.model_dump() for p in pairs_list[:MAX_SEARCH_RESULTS]],
+                }
             )
         except Exception as e:
             return await self._handle_unexpected_runtime_error(e, query)
 
-    def get_query_type(self, query: str) -> QueryType:
-        """
-        Determine whether the query is a TEXT, TICKER, or ADDRESS.
-
-        TICKER: starts with '$'
-        ADDRESS: starts with '0x'.
-        TEXT: anything else.
-        """
-        if query.startswith("0x"):
-            return QueryType.ADDRESS
-        if query.startswith("$"):
-            return QueryType.TICKER
-        return QueryType.TEXT
-
     async def _handle_error_response(self, error_details: dict) -> str:
         """Formats error details (from _get) into a JSON string."""
         if error_details.get("error_type") in [
@@ -265,57 +168,17 @@ class SearchToken(DexScreenerBaseTool):
             logger.warning(f"DexScreener API returned an error: {error_details}")
 
         # Truncate potentially large fields before returning to user/LLM
-        for key in ["details", "response_body"]:
-            if (
-                isinstance(error_details.get(key), str)
-                and len(error_details[key]) > 500
-            ):
-                error_details[key] = error_details[key][:500] + "... (truncated)"
-
-        return json.dumps(error_details, indent=2)
-
-    async def _handle_validation_error(
-        self, e: ValidationError, query: str, data: Any
-    ) -> str:
-        """Formats validation error details into a JSON string."""
-        logger.error(
-            f"Failed to validate DexScreener response structure for query '{query}'. Error: {e}. Raw data length: {len(str(data))}",
-            exc_info=True,
-        )
-        # Avoid sending potentially huge raw data back
-        return json.dumps(
-            {
-                "error": "Failed to parse successful DexScreener API response",
-                "error_type": "validation_error",
-                "details": e.errors(),
-            },
-            indent=2,
-        )
+        truncated_details = truncate_large_fields(error_details)
+        return format_success_response(truncated_details)
 
     async def _handle_unexpected_runtime_error(self, e: Exception, query: str) -> str:
         """Formats unexpected runtime exception details into a JSON string."""
         logger.exception(
             f"An unexpected runtime error occurred in search_token tool _arun method for query '{query}': {e}"
         )
-        return json.dumps(
-            {
-                "error": "An unexpected internal error occurred processing the search request",
-                "error_type": "runtime_error",
-                "details": str(e),
-            },
-            indent=2,
-        )
-
-    async def _no_pairs_found_response(
-        self, query: str, reason: str = "returned no matching pairs"
-    ) -> str:
-        """Generates the standard 'no pairs found' JSON response."""
-        logger.info(f"DexScreener search for query '{query}': {reason}.")
-        return json.dumps(
-            {
-                "message": f"No matching pairs found for the query '{query}'. Reason: {reason}.",
-                "query": query,
-                "pairs": [],
-            },
-            indent=2,
+        return create_error_response(
+            error_type="runtime_error",
+            message="An unexpected internal error occurred processing the search request",
+            details=str(e),
+            additional_data={"query": query},
         )