intentkit 0.6.13.dev2__py3-none-any.whl → 0.8.17__py3-none-any.whl

intentkit/skills/dexscreener/get_tokens_info.py

@@ -0,0 +1,212 @@
+import logging
+from typing import Any
+
+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.global_rate_limit_by_skill(
+            limit=RATE_LIMITS["tokens"],
+            seconds=60,
+        )
+
+        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/model/search_token_response.py

@@ -1,82 +1,80 @@
-from typing import List, Optional
-
-from pydantic import BaseModel
-
-
-class TokenModel(BaseModel):
-    address: Optional[str] = None
-    name: Optional[str] = None
-    symbol: Optional[str] = None
-
-
-class TxnsDetailsModel(BaseModel):
-    buys: Optional[int] = None
-    sells: Optional[int] = None
-
-
-class TxnsModel(BaseModel):
-    m5: Optional[TxnsDetailsModel] = None
-    h1: Optional[TxnsDetailsModel] = None
-    h6: Optional[TxnsDetailsModel] = None
-    h24: Optional[TxnsDetailsModel] = None
-
-
-class VolumeModel(BaseModel):
-    h24: Optional[float] = None
-    h6: Optional[float] = None
-    h1: Optional[float] = None
-    m5: Optional[float] = None
-
-
-class PriceChangeModel(BaseModel):
-    m5: Optional[float] = None
-    h1: Optional[float] = None
-    h6: Optional[float] = None
-    h24: Optional[float] = None
-
-
-class LiquidityModel(BaseModel):
-    usd: Optional[float] = None
-    base: Optional[float] = None
-    quote: Optional[float] = None
-
-
-class WebsiteModel(BaseModel):
-    label: Optional[str] = None
-    url: Optional[str] = None
-
-
-class SocialModel(BaseModel):
-    type: Optional[str] = None
-    url: Optional[str] = None
-
-
-class InfoModel(BaseModel):
-    imageUrl: Optional[str] = None
-    websites: Optional[List[Optional[WebsiteModel]]] = None
-    socials: Optional[List[Optional[SocialModel]]] = None
-
-
-class PairModel(BaseModel):
-    chainId: Optional[str] = None
-    dexId: Optional[str] = None
-    url: Optional[str] = None
-    pairAddress: Optional[str] = None
-    labels: Optional[List[Optional[str]]] = None
-    baseToken: Optional[TokenModel] = None
-    quoteToken: Optional[TokenModel] = None
-    priceNative: Optional[str] = None
-    priceUsd: Optional[str] = None
-    txns: Optional[TxnsModel] = None
-    volume: Optional[VolumeModel] = None
-    priceChange: Optional[PriceChangeModel] = None
-    liquidity: Optional[LiquidityModel] = None
-    fdv: Optional[float] = None
-    marketCap: Optional[float] = None
-    pairCreatedAt: Optional[int] = None
-    info: Optional[InfoModel] = None
-
-
-class SearchTokenResponseModel(BaseModel):
-    schemaVersion: Optional[str] = None
-    pairs: Optional[List[Optional[PairModel]]] = None
+from pydantic import BaseModel
+
+
+class TokenModel(BaseModel):
+    address: str | None = None
+    name: str | None = None
+    symbol: str | None = None
+
+
+class TxnsDetailsModel(BaseModel):
+    buys: int | None = None
+    sells: int | None = None
+
+
+class TxnsModel(BaseModel):
+    m5: TxnsDetailsModel | None = None
+    h1: TxnsDetailsModel | None = None
+    h6: TxnsDetailsModel | None = None
+    h24: TxnsDetailsModel | None = None
+
+
+class VolumeModel(BaseModel):
+    h24: float | None = None
+    h6: float | None = None
+    h1: float | None = None
+    m5: float | None = None
+
+
+class PriceChangeModel(BaseModel):
+    m5: float | None = None
+    h1: float | None = None
+    h6: float | None = None
+    h24: float | None = None
+
+
+class LiquidityModel(BaseModel):
+    usd: float | None = None
+    base: float | None = None
+    quote: float | None = None
+
+
+class WebsiteModel(BaseModel):
+    label: str | None = None
+    url: str | None = None
+
+
+class SocialModel(BaseModel):
+    type: str | None = None
+    url: str | None = None
+
+
+class InfoModel(BaseModel):
+    imageUrl: str | None = None
+    websites: list[WebsiteModel | None] | None = None
+    socials: list[SocialModel | None] | None = None
+
+
+class PairModel(BaseModel):
+    chainId: str | None = None
+    dexId: str | None = None
+    url: str | None = None
+    pairAddress: str | None = None
+    labels: list[str | None] | None = None
+    baseToken: TokenModel | None = None
+    quoteToken: TokenModel | None = None
+    priceNative: str | None = None
+    priceUsd: str | None = None
+    txns: TxnsModel | None = None
+    volume: VolumeModel | None = None
+    priceChange: PriceChangeModel | None = None
+    liquidity: LiquidityModel | None = None
+    fdv: float | None = None
+    marketCap: float | None = None
+    pairCreatedAt: int | None = None
+    info: InfoModel | None = None
+
+
+class SearchTokenResponseModel(BaseModel):
+    schemaVersion: str | None = None
+    pairs: list[PairModel | None] | None = None

intentkit/skills/dexscreener/schema.json

@@ -1,48 +1,91 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "Dexscreener",
-    "description": "Integration with DexScreener API, enabling crypto token pair information",
-    "type": "object",
-    "x-icon": "https://ai.service.crestal.dev/skills/dexscreener/dexscreener.png",
-    "x-tags": [
-        "Crypto",
-        "Market Data",
-        "Finance",
-        "Blockchain"
-    ],
-    "properties": {
-        "enabled": {
-            "type": "boolean",
-            "title": "Enabled",
-            "description": "Enable or disable the Dexscreener skill.",
-            "default": false
-        },
-        "states": {
-            "type": "object",
-            "title": "Skill States",
-            "description": "Enable/disable specific tools. Only enable one if you want a consistent characteristic for your agent",
-            "properties": {
-                "search_token": {
-                    "type": "string",
-                    "enum": [
-                        "disabled",
-                        "public",
-                        "private"
-                    ],
-                    "x-enum-title": [
-                        "Disabled",
-                        "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.",
-                    "default": "disabled"
-                }
-            }
-        }
-    },
-    "required": [
-        "enabled",
-        "states"
-    ],
-    "additionalProperties": true
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Dexscreener",
+  "description": "Integration with DexScreener API, enabling crypto token pair information",
+  "type": "object",
+  "x-icon": "https://ai.service.crestal.dev/skills/dexscreener/dexscreener.png",
+  "x-tags": [
+    "Analytics",
+    "DeFi"
+  ],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Enable or disable the Dexscreener skill.",
+      "default": false
+    },
+    "states": {
+      "type": "object",
+      "title": "Skill States",
+      "description": "Enable/disable specific tools. Only enable one if you want a consistent characteristic for your agent",
+      "properties": {
+        "search_token": {
+          "type": "string",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "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"
+        }
+      }
+    }
+  },
+  "required": [
+    "enabled",
+    "states"
+  ],
+  "additionalProperties": true
+}