intentkit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

intentkit/skills/token/README.md

@@ -0,0 +1,89 @@
+# Token Skills
+
+The Token skills provide blockchain token analytics capabilities powered by Moralis. These skills allow you to search, analyze, and track token information across multiple blockchains.
+
+## Available Skills
+
+| Skill | Description | Endpoint | Example Prompts |
+|-------|-------------|----------|----------------|
+| `token_price` | Get token price and information | `GET /erc20/:address/price` | "What's the current price of PEPE token?" "Get the price of USDT on Ethereum." |
+| `token_erc20_transfers` | Get ERC20 token transfers for a wallet | `GET /:address/erc20/transfers` | "Show me all the USDT transfers for my wallet." "What are the recent token transactions for 0x123?" |
+| `token_search` * | Search for tokens by name, symbol, or address | `GET /tokens/search` | "Find tokens with 'pepe' in the name." "Search for tokens with high market cap on Ethereum." |
+| `token_analytics` | Get detailed analytics for a token | `GET /tokens/:address/analytics` | "Show me analytics for the PEPE token." "What are the buy/sell volumes for USDT in the last 24 hours?" |
+
+\* Premium Endpoint: To use the `token_search` API, you will need an API key associated with a Moralis account on the Business plan or a custom Enterprise plan.
+
+## Configuration
+
+The token skills require a Moralis API key to function. You can configure this in your agent's configuration file:
+
+```yaml
+skills:
+  token:
+    api_key: "your_moralis_api_key_here"
+    states:
+      token_price: "public"
+      token_erc20_transfers: "public"
+      token_search: "public"
+      token_analytics: "public"
+```
+
+## Responses
+
+All token skills return structured data from the Moralis API. Here are the typical response formats:
+
+### Token Price
+
+```json
+{
+  "tokenName": "Pepe",
+  "tokenSymbol": "PEPE",
+  "tokenLogo": "https://cdn.moralis.io/eth/0x6982508145454ce325ddbe47a25d4ec3d2311933.png",
+  "tokenDecimals": "18",
+  "usdPrice": 0.000012302426023896,
+  "usdPriceFormatted": "0.000012302426023896",
+  "24hrPercentChange": "-3.7369101031758394",
+  "exchangeName": "Uniswap v3",
+  "tokenAddress": "0x6982508145454ce325ddbe47a25d4ec3d2311933"
+}
+```
+
+### Token Analytics
+
+```json
+{
+  "tokenAddress": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
+  "totalBuyVolume": {
+    "5m": "",
+    "1h": 43678.642005116264,
+    "6h": 129974.13379912674,
+    "24h": 4583254.969119737
+  },
+  "totalSellVolume": {
+    "5m": 147.69184595604904,
+    "1h": 393.0296489666009,
+    "6h": 257421.35479601548,
+    "24h": 4735908.689740969
+  },
+  "totalBuyers": {
+    "5m": "",
+    "1h": 33,
+    "6h": 115,
+    "24h": 547
+  },
+  "totalSellers": {
+    "5m": 1,
+    "1h": 2,
+    "6h": 78,
+    "24h": 587
+  }
+}
+```
+
+## Usage Tips
+
+- For the best performance, always specify the chain parameter when querying across multiple blockchains.
+- When using the token_search endpoint, be aware of your Moralis plan limitations.
+- The token analytics skill provides valuable trading data that can be used for token analysis and market assessment.
+
+For more detailed information on each endpoint, refer to the [Moralis API documentation](https://docs.moralis.io/web3-data-api/evm). 

intentkit/skills/token/__init__.py

@@ -0,0 +1,107 @@
+"""Token skills for blockchain token analysis."""
+
+import logging
+from typing import TypedDict
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import SkillConfig, SkillState
+from intentkit.skills.token.base import TokenBaseTool
+from intentkit.skills.token.erc20_transfers import ERC20Transfers
+from intentkit.skills.token.token_analytics import TokenAnalytics
+from intentkit.skills.token.token_price import TokenPrice
+from intentkit.skills.token.token_search import TokenSearch
+
+# Cache skills at the system level, because they are stateless
+_cache: dict[str, TokenBaseTool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+class SkillStates(TypedDict):
+    """State configurations for Token skills."""
+
+    token_price: SkillState
+    token_erc20_transfers: SkillState
+    token_search: SkillState
+    token_analytics: SkillState
+
+
+class Config(SkillConfig):
+    """Configuration for Token blockchain analysis skills."""
+
+    states: SkillStates
+    api_key: str
+
+
+async def get_skills(
+    config: "Config",
+    is_private: bool,
+    store: SkillStoreABC,
+    **_,
+) -> list[TokenBaseTool]:
+    """Get all Token blockchain analysis skills.
+
+    Args:
+        config: The configuration for Token skills.
+        is_private: Whether to include private skills.
+        store: The skill store for persisting data.
+
+    Returns:
+        A list of Token blockchain analysis skills.
+    """
+    if "states" not in config:
+        logger.error("No 'states' field in config")
+        return []
+
+    available_skills = []
+
+    # Include skills based on their state
+    for skill_name, state in config["states"].items():
+        if state == "disabled":
+            continue
+        elif state == "public" or (state == "private" and is_private):
+            available_skills.append(skill_name)
+
+    # Get each skill using the cached getter
+    result = []
+    for name in available_skills:
+        skill = get_token_skill(name, store)
+        if skill:
+            result.append(skill)
+
+    return result
+
+
+def get_token_skill(
+    name: str,
+    store: SkillStoreABC,
+) -> TokenBaseTool:
+    """Get a Token blockchain analysis skill by name.
+
+    Args:
+        name: The name of the skill to get
+        store: The skill store for persisting data
+
+    Returns:
+        The requested Token blockchain analysis skill
+    """
+    if name in _cache:
+        return _cache[name]
+
+    skill = None
+    if name == "token_price":
+        skill = TokenPrice(skill_store=store)
+    elif name == "token_erc20_transfers":
+        skill = ERC20Transfers(skill_store=store)
+    elif name == "token_search":
+        skill = TokenSearch(skill_store=store)
+    elif name == "token_analytics":
+        skill = TokenAnalytics(skill_store=store)
+    else:
+        logger.warning(f"Unknown Token skill: {name}")
+        return None
+
+    if skill:
+        _cache[name] = skill
+
+    return skill

intentkit/skills/token/base.py

@@ -0,0 +1,154 @@
+"""Base class for token-related skills."""
+
+import logging
+from typing import Any, Dict, Optional
+
+import aiohttp
+from langchain_core.runnables import RunnableConfig
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import IntentKitSkill, SkillContext
+from intentkit.skills.token.constants import MORALIS_API_BASE_URL
+
+logger = logging.getLogger(__name__)
+
+
+class TokenBaseTool(IntentKitSkill):
+    """Base class for all token-related skills.
+
+    This base class provides common functionality for token API interactions,
+    including making HTTP requests to the Moralis API.
+    """
+
+    def __init__(self, skill_store: SkillStoreABC = None):
+        """Initialize the token tool with a skill store."""
+        super().__init__(skill_store=skill_store)
+
+    @property
+    def category(self) -> str:
+        return "token"
+
+    def get_api_key(self, context: SkillContext) -> str:
+        """Get API key from agent config or system config.
+
+        Args:
+            context: The skill context containing the agent config
+
+        Returns:
+            The API key to use for API requests
+        """
+        skill_config = context.config
+        if skill_config.get("api_key_provider") == "agent_owner":
+            return skill_config.get("api_key")
+        return self.skill_store.get_system_config("moralis_api_key")
+
+    def context_from_config(self, config: Optional[RunnableConfig] = None) -> Any:
+        """Extract context from the runnable config."""
+        if not config:
+            logger.error("No config provided to context_from_config")
+            return None
+
+        if "configurable" not in config:
+            logger.error("'configurable' not in config")
+            return None
+
+        if "agent" not in config["configurable"]:
+            logger.error("'agent' not in config['configurable']")
+            return None
+
+        agent = config["configurable"].get("agent")
+        category_config = None
+
+        if agent.skills:
+            category_config = agent.skills.get(self.category)
+
+        if not category_config:
+            category_config = getattr(agent, self.category + "_config", {})
+
+        if not category_config:
+            category_config = {}
+
+        from intentkit.skills.base import SkillContext
+
+        context = SkillContext(
+            agent=agent,
+            config=category_config,
+            user_id=config["configurable"].get("user_id"),
+            entrypoint=config["configurable"].get("entrypoint"),
+        )
+
+        return context
+
+    def _prepare_params(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Convert boolean values to lowercase strings for API compatibility.
+
+        Args:
+            params: Dictionary with query parameters that may contain boolean values
+
+        Returns:
+            Dictionary with boolean values converted to lowercase strings
+        """
+        if not params:
+            return params
+
+        result = {}
+        for key, value in params.items():
+            if isinstance(value, bool):
+                result[key] = str(value).lower()
+            else:
+                result[key] = value
+        return result
+
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        api_key: str,
+        params: Dict[str, Any] = None,
+        data: Dict[str, Any] = None,
+    ) -> Dict[str, Any]:
+        """Make a request to the Moralis API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint (without base URL)
+            api_key: Moralis API key
+            params: Query parameters
+            data: Request body data for POST requests
+
+        Returns:
+            Response data as dictionary
+        """
+        url = f"{MORALIS_API_BASE_URL}{endpoint}"
+
+        if not api_key:
+            logger.error("API key is missing")
+            return {"error": "API key is missing"}
+
+        headers = {"accept": "application/json", "X-API-Key": api_key}
+        processed_params = self._prepare_params(params) if params else None
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    params=processed_params,
+                    json=data,
+                ) as response:
+                    if response.status >= 400:
+                        error_text = await response.text()
+                        logger.error(f"API error {response.status}: {error_text}")
+                        return {
+                            "error": f"API error: {response.status}",
+                            "details": error_text,
+                        }
+
+                    return await response.json()
+        except aiohttp.ClientError as e:
+            logger.error(f"HTTP error making request: {str(e)}")
+            return {"error": f"HTTP error: {str(e)}"}
+        except Exception as e:
+            logger.error(f"Unexpected error making request: {str(e)}")
+            return {"error": f"Unexpected error: {str(e)}"}

intentkit/skills/token/constants.py

@@ -0,0 +1,9 @@
+"""Constants for the token skills module."""
+
+# Base URLs
+MORALIS_API_BASE_URL = "https://deep-index.moralis.io/api/v2.2"
+
+# Default parameters
+DEFAULT_CHAIN = "eth"
+DEFAULT_LIMIT = 100
+DEFAULT_ORDER = "DESC"

intentkit/skills/token/erc20_transfers.py

@@ -0,0 +1,145 @@
+import logging
+from typing import Any, Dict, List, Optional, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.token.base import TokenBaseTool
+from intentkit.skills.token.constants import DEFAULT_CHAIN, DEFAULT_LIMIT, DEFAULT_ORDER
+
+logger = logging.getLogger(__name__)
+
+
+class ERC20TransfersInput(BaseModel):
+    """Input for ERC20 transfers tool."""
+
+    address: str = Field(
+        description="The address of the wallet to get ERC20 token transfers for."
+    )
+    chain: str = Field(
+        description="The chain to query (e.g., 'eth', 'bsc', 'polygon').",
+        default=DEFAULT_CHAIN,
+    )
+    contract_addresses: Optional[List[str]] = Field(
+        description="List of contract addresses of transfers to filter by.",
+        default=None,
+    )
+    from_block: Optional[int] = Field(
+        description="The minimum block number from which to get the transactions.",
+        default=None,
+    )
+    to_block: Optional[int] = Field(
+        description="The maximum block number from which to get the transactions.",
+        default=None,
+    )
+    from_date: Optional[str] = Field(
+        description="The start date from which to get the transactions (any format accepted by momentjs).",
+        default=None,
+    )
+    to_date: Optional[str] = Field(
+        description="Get the transactions up to this date (any format accepted by momentjs).",
+        default=None,
+    )
+    limit: Optional[int] = Field(
+        description="The desired page size of the result.",
+        default=DEFAULT_LIMIT,
+    )
+    order: Optional[str] = Field(
+        description="The order of the result, in ascending (ASC) or descending (DESC).",
+        default=DEFAULT_ORDER,
+    )
+    cursor: Optional[str] = Field(
+        description="The cursor returned in the previous response (for pagination).",
+        default=None,
+    )
+
+
+class ERC20Transfers(TokenBaseTool):
+    """Tool for retrieving ERC20 token transfers by wallet using Moralis.
+
+    This tool uses Moralis' API to fetch ERC20 token transactions ordered by
+    block number in descending order for a specific wallet address.
+    """
+
+    name: str = "token_erc20_transfers"
+    description: str = (
+        "Get ERC20 token transactions for a wallet address, ordered by block number. "
+        "Returns transaction details, token information, and wallet interactions."
+    )
+    args_schema: Type[BaseModel] = ERC20TransfersInput
+
+    async def _arun(
+        self,
+        address: str,
+        chain: str = DEFAULT_CHAIN,
+        contract_addresses: Optional[List[str]] = None,
+        from_block: Optional[int] = None,
+        to_block: Optional[int] = None,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        limit: Optional[int] = DEFAULT_LIMIT,
+        order: Optional[str] = DEFAULT_ORDER,
+        cursor: Optional[str] = None,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """Fetch ERC20 token transfers for a wallet from Moralis.
+
+        Args:
+            address: The wallet address
+            chain: The blockchain to query
+            contract_addresses: List of contract addresses to filter by
+            from_block: Minimum block number
+            to_block: Maximum block number
+            from_date: Start date for transfers
+            to_date: End date for transfers
+            limit: Number of results per page
+            order: Order of results (ASC/DESC)
+            cursor: Pagination cursor
+            config: The configuration for the tool call
+
+        Returns:
+            Dict containing ERC20 transfer data
+        """
+        context = self.context_from_config(config)
+        if context is None:
+            logger.error("Context is None, cannot retrieve API key")
+            return {
+                "error": "Cannot retrieve API key. Please check agent configuration."
+            }
+
+        # Get the API key
+        api_key = self.get_api_key(context)
+
+        if not api_key:
+            logger.error("No Moralis API key available")
+            return {"error": "No Moralis API key provided in the configuration."}
+
+        # Build query parameters
+        params = {"chain": chain, "limit": limit, "order": order}
+
+        # Add optional parameters if they exist
+        if contract_addresses:
+            params["contract_addresses"] = contract_addresses
+        if from_block:
+            params["from_block"] = from_block
+        if to_block:
+            params["to_block"] = to_block
+        if from_date:
+            params["from_date"] = from_date
+        if to_date:
+            params["to_date"] = to_date
+        if cursor:
+            params["cursor"] = cursor
+
+        # Call Moralis API
+        try:
+            endpoint = f"/{address}/erc20/transfers"
+            return await self._make_request(
+                method="GET", endpoint=endpoint, api_key=api_key, params=params
+            )
+        except Exception as e:
+            logger.error(f"Error fetching ERC20 transfers: {e}")
+            return {
+                "error": f"An error occurred while fetching ERC20 transfers: {str(e)}. Please try again later."
+            }

intentkit/skills/token/schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Token Skills",
+  "description": "Token analysis skills powered by Moralis API",
+  "type": "object",
+  "x-icon": "https://ai.service.crestal.dev/skills/portfolio/moralis.png",
+  "x-tags": [
+    "Blockchain",
+    "Web3",
+    "Crypto",
+    "Token",
+    "DeFi"
+  ],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill is enabled",
+      "default": true
+    },
+    "states": {
+      "type": "object",
+      "properties": {
+        "token_price": {
+          "type": "string",
+          "title": "ERC20 Token Price",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Get the token price denominated in the blockchain's native token and USD",
+          "default": "public"
+        },
+        "token_erc20_transfers": {
+          "type": "string",
+          "title": "ERC20 Token Transfers",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Get ERC20 token transactions ordered by block number",
+          "default": "public"
+        },
+        "token_search": {
+          "type": "string",
+          "title": "Token Search (Premium)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Search for tokens based on contract address, token name or token symbol. Premium endpoint available as an add-on. Requires a Moralis Business plan or Enterprise plan.",
+          "default": "public"
+        },
+        "token_analytics": {
+          "type": "string",
+          "title": "Token Analytics",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Get analytics for a token by token address",
+          "default": "public"
+        }
+      },
+      "description": "States for each token analysis skill (disabled, public, or private)"
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Provider of the API key",
+      "enum": [
+        "platform",
+        "agent_owner"
+      ],
+      "x-enum-title": [
+        "Nation Hosted",
+        "Owner Provided"
+      ],
+      "default": "platform"
+    }
+  },
+  "required": [
+    "states",
+    "enabled"
+  ],
+  "if": {
+    "properties": {
+      "api_key_provider": {
+        "const": "agent_owner"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "api_key": {
+        "type": "string",
+        "title": "Moralis API Key",
+        "description": "API key for Moralis API service",
+        "x-link": "[Get your API key](https://moralis.io/)",
+        "x-sensitive": true
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_key"
+      ]
+    }
+  },
+  "additionalProperties": true
+}