botchain-sdk-py 0.1.0__tar.gz

botchain_sdk_py-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: botchain-sdk-py
+Version: 0.1.0
+Summary: BOT Chain SDK for Python, featuring Agentic Tooling, MCP, and ALM.
+Author: Bot Chain Team
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: web3
+Requires-Dist: eth-account
+Dynamic: requires-python
+
+# BotChain Python SDK
+
+The official Python SDK for interacting with BOT Chain, an AI-focused Layer 1 ecosystem. This SDK provides complete integration pathways for managing accounts, tokens, concentrated liquidity (BDEX V3), and executing smart contract logic autonomously via our embedded AI Agent integrations.
+
+## Features
+
+- **Core Blockchain Client**: Connect to Mainnet/Testnet easily with full Web3 provider compatibility. Zero-gas transaction sponsorships natively handled.
+- **BDEX V3 Concentrated Liquidity**: Manage advanced DeFi interactions.
+
+### AI Agent & MCP Server
+This SDK natively supports Model Context Protocol (MCP) integrations for autonomous agents like OpenClaw or Claude Desktop. The embedded Agent Policy Engine ensures strict on-chain safeguards including:
+- Hourly rate limits and trade cooldowns.
+- Notional USD limits.
+- Asset Allowlists.
+
+Agents can discover tools (`get_balance`, `get_quote`, `execute_guarded_swap`) over standard JSON-RPC `stdio`. Run the server locally using the bundled entry point:
+```bash
+botchain-mcp
+```
+
+### Automated Liquidity Management (ALM)
+We support on-chain math utilities required to properly route and rebalance Concentrated Liquidity positions automatically. 
+- Exact tick conversions and boundaries.
+- Precise multi-hop math allowing the SDK to compute optimal swap ratios without trusting off-chain actors.
+- Fully atomic rebalances (with Python-level State Recovery for failing swaps).
+
+## Installation
+
+You can install the SDK from source or directly via `pip`:
+```bash
+pip install botchain-sdk-py
+```
+
+## Quick Start
+
+```python
+from botchain.client import BotChain
+from botchain.tokens import TokenManager
+
+# Initialize Client
+client = BotChain(network="mainnet")
+
+# Check token balances
+token_mgr = TokenManager(client)
+balance = token_mgr.get_balance("0xUSDT_Address", "0xUser_Address")
+print(f"USDT Balance: {balance}")
+```

botchain_sdk_py-0.1.0/README.md

@@ -0,0 +1,47 @@
+# BotChain Python SDK
+
+The official Python SDK for interacting with BOT Chain, an AI-focused Layer 1 ecosystem. This SDK provides complete integration pathways for managing accounts, tokens, concentrated liquidity (BDEX V3), and executing smart contract logic autonomously via our embedded AI Agent integrations.
+
+## Features
+
+- **Core Blockchain Client**: Connect to Mainnet/Testnet easily with full Web3 provider compatibility. Zero-gas transaction sponsorships natively handled.
+- **BDEX V3 Concentrated Liquidity**: Manage advanced DeFi interactions.
+
+### AI Agent & MCP Server
+This SDK natively supports Model Context Protocol (MCP) integrations for autonomous agents like OpenClaw or Claude Desktop. The embedded Agent Policy Engine ensures strict on-chain safeguards including:
+- Hourly rate limits and trade cooldowns.
+- Notional USD limits.
+- Asset Allowlists.
+
+Agents can discover tools (`get_balance`, `get_quote`, `execute_guarded_swap`) over standard JSON-RPC `stdio`. Run the server locally using the bundled entry point:
+```bash
+botchain-mcp
+```
+
+### Automated Liquidity Management (ALM)
+We support on-chain math utilities required to properly route and rebalance Concentrated Liquidity positions automatically. 
+- Exact tick conversions and boundaries.
+- Precise multi-hop math allowing the SDK to compute optimal swap ratios without trusting off-chain actors.
+- Fully atomic rebalances (with Python-level State Recovery for failing swaps).
+
+## Installation
+
+You can install the SDK from source or directly via `pip`:
+```bash
+pip install botchain-sdk-py
+```
+
+## Quick Start
+
+```python
+from botchain.client import BotChain
+from botchain.tokens import TokenManager
+
+# Initialize Client
+client = BotChain(network="mainnet")
+
+# Check token balances
+token_mgr = TokenManager(client)
+balance = token_mgr.get_balance("0xUSDT_Address", "0xUser_Address")
+print(f"USDT Balance: {balance}")
+```

botchain_sdk_py-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "botchain-sdk-py"
+version = "0.1.0"
+description = "BOT Chain SDK for Python, featuring Agentic Tooling, MCP, and ALM."
+authors = [
+    {name = "Bot Chain Team"}
+]
+dependencies = [
+    "web3",
+    "eth-account"
+]
+readme = "README.md"
+requires-python = ">=3.8"
+
+[project.scripts]
+botchain-mcp = "botchain.agents.mcp_server:main"

botchain_sdk_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

botchain_sdk_py-0.1.0/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="botchain-sdk",
+    version="0.1.0",
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    install_requires=[
+        "web3>=6.0.0",
+        "eth-account>=0.8.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.0.0",
+        ],
+    },
+    python_requires=">=3.8",
+)

botchain_sdk_py-0.1.0/src/botchain/__init__.py

@@ -0,0 +1,18 @@
+from .client import BotChain
+from .exceptions import BotChainLogsDisabledError
+from .dex import BDexManager
+from .tokens import TokenManager
+from .middleware import botchain_paymaster_middleware, check_and_apply_sponsorship
+from .agents import AgentTradePolicy, AgentExecutor
+
+__all__ = [
+    "BotChain",
+    "BotChainLogsDisabledError",
+    "BDexManager",
+    "TokenManager",
+    "botchain_paymaster_middleware",
+    "check_and_apply_sponsorship",
+    "AgentTradePolicy",
+    "AgentExecutor"
+]
+

botchain_sdk_py-0.1.0/src/botchain/agents/__init__.py

@@ -0,0 +1,4 @@
+from .policy import AgentTradePolicy
+from .executor import AgentExecutor
+
+__all__ = ["AgentTradePolicy", "AgentExecutor"]

botchain_sdk_py-0.1.0/src/botchain/agents/executor.py

@@ -0,0 +1,92 @@
+import logging
+import time
+from typing import Optional
+from web3 import Web3
+from .policy import AgentTradePolicy
+from ..middleware import check_and_apply_sponsorship
+
+logger = logging.getLogger(__name__)
+
+class AgentExecutor:
+    """
+    Guarded transaction execution engine for AI Agents.
+    Validates trade intents against AgentTradePolicy, performs pre-flight eth_call simulations,
+    and handles zero-gas Paymaster sponsorship before signing & broadcasting.
+    """
+    def __init__(self, botclient, policy: AgentTradePolicy):
+        self.client = botclient
+        self.w3 = botclient.w3
+        self.policy = policy
+
+    def execute_trade(
+        self,
+        dex_manager,
+        token_in: str,
+        token_out: str,
+        amount_in: int,
+        fee: int = 3000,
+        slippage_tolerance: float = 0.01,
+        recipient: Optional[str] = None,
+        notional_usd: Optional[float] = None
+    ) -> str:
+        """
+        Validates, simulates, sponsors, and executes a single-hop BDEX trade.
+        """
+        if not self.client.account:
+            raise ValueError("Local account required to execute agent trades.")
+
+        target_recipient = recipient or self.client.account.address
+        router_address = dex_manager.router_contract.address
+
+        # 1. Policy Validation
+        self.policy.validate_trade(
+            token_in=token_in,
+            token_out=token_out,
+            router=router_address,
+            amount_in=amount_in,
+            slippage=slippage_tolerance,
+            notional_usd=notional_usd
+        )
+
+        # 2. Get Quote & Calculate minimum output
+        expected_out = dex_manager.get_quote(token_in, token_out, amount_in, fee)
+        amount_out_minimum = int(expected_out * (1 - slippage_tolerance))
+
+        # 3. Build Transaction Dictionary
+        params = {
+            "tokenIn": self.w3.to_checksum_address(token_in),
+            "tokenOut": self.w3.to_checksum_address(token_out),
+            "fee": fee,
+            "recipient": self.w3.to_checksum_address(target_recipient),
+            "deadline": int(time.time()) + 600,
+            "amountIn": amount_in,
+            "amountOutMinimum": amount_out_minimum,
+            "sqrtPriceLimitX96": 0
+        }
+
+        tx_dict = dex_manager.router_contract.functions.exactInputSingle(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+
+        # 4. Pre-Flight Simulation (eth_call)
+        try:
+            logger.info("Executing pre-flight transaction simulation via eth_call...")
+            self.w3.eth.call(tx_dict)
+            logger.info("Pre-flight simulation successful.")
+        except Exception as e:
+            logger.error(f"Pre-flight simulation failed: {e}")
+            raise RuntimeError(f"Transaction pre-flight simulation failed: {e}") from e
+
+        # 5. Zero-Gas Paymaster Sponsorship Check
+        tx_dict = check_and_apply_sponsorship(self.w3, tx_dict)
+
+        # 6. Sign and Broadcast Transaction
+        signed_tx = self.w3.eth.account.sign_transaction(tx_dict, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+
+        # 7. Record trade in policy state upon success
+        self.policy.record_trade()
+
+        return self.w3.to_hex(tx_hash)

botchain_sdk_py-0.1.0/src/botchain/agents/mcp.py

@@ -0,0 +1,3 @@
+from .tools.mcp_server import BotChainMCPServer
+
+__all__ = ["BotChainMCPServer"]

botchain_sdk_py-0.1.0/src/botchain/agents/mcp_server.py

@@ -0,0 +1,18 @@
+import sys
+from botchain.client import BotChain
+from botchain.agents.executor import AgentExecutor
+from botchain.agents.policy import AgentTradePolicy
+from botchain.agents.tools.mcp_server import BotChainMCPServer
+
+def main():
+    """Entry point for botchain-mcp server."""
+    # Simple setup for MCP
+    client = BotChain()
+    policy = AgentTradePolicy()
+    executor = AgentExecutor(policy)
+    
+    server = BotChainMCPServer(client, executor)
+    server.run_stdio()
+
+if __name__ == "__main__":
+    main()

botchain_sdk_py-0.1.0/src/botchain/agents/policy.py

@@ -0,0 +1,102 @@
+import time
+from typing import List, Optional, Set
+from web3 import Web3
+
+class AgentTradePolicy:
+    """
+    Safety Policy Engine for AI Agents executing trades on BOT Chain.
+    Enforces spending caps, rate limits, cooldowns, and asset allowlists.
+    """
+    def __init__(
+        self,
+        allowed_tokens: Optional[List[str]] = None,
+        allowed_routers: Optional[List[str]] = None,
+        max_slippage_tolerance: float = 0.05,
+        max_notional_usd: Optional[float] = 1000.0,
+        cooldown_seconds: float = 10.0,
+        max_trades_per_hour: int = 10
+    ):
+        self.allowed_tokens: Optional[Set[str]] = (
+            {Web3.to_checksum_address(t) for t in allowed_tokens} if allowed_tokens else None
+        )
+        self.allowed_routers: Optional[Set[str]] = (
+            {Web3.to_checksum_address(r) for r in allowed_routers} if allowed_routers else None
+        )
+        self.max_slippage_tolerance = max_slippage_tolerance
+        self.max_notional_usd = max_notional_usd
+        self.cooldown_seconds = cooldown_seconds
+        self.max_trades_per_hour = max_trades_per_hour
+
+        # Internal tracking state
+        self.last_trade_time: Optional[float] = None
+        self.trade_timestamps: List[float] = []
+
+    def validate_trade(
+        self,
+        token_in: str,
+        token_out: str,
+        router: Optional[str] = None,
+        amount_in: int = 0,
+        slippage: float = 0.01,
+        notional_usd: Optional[float] = None,
+        current_time: Optional[float] = None
+    ) -> None:
+        """
+        Validates trade parameters against policy rules.
+        Raises ValueError if any rule is violated.
+        """
+        now = current_time if current_time is not None else time.time()
+
+        # 1. Token Allowlist Verification
+        checksum_in = Web3.to_checksum_address(token_in)
+        checksum_out = Web3.to_checksum_address(token_out)
+
+        if self.allowed_tokens is not None:
+            if checksum_in not in self.allowed_tokens:
+                raise ValueError(f"Token IN ({token_in}) is not in the allowed tokens list.")
+            if checksum_out not in self.allowed_tokens:
+                raise ValueError(f"Token OUT ({token_out}) is not in the allowed tokens list.")
+
+        # 2. Router Allowlist Verification
+        if router and self.allowed_routers is not None:
+            checksum_router = Web3.to_checksum_address(router)
+            if checksum_router not in self.allowed_routers:
+                raise ValueError(f"Router ({router}) is not in the allowed routers list.")
+
+        # 3. Slippage Limit Verification
+        if slippage > self.max_slippage_tolerance:
+            raise ValueError(
+                f"Requested slippage ({slippage:.4f}) exceeds maximum allowed tolerance ({self.max_slippage_tolerance:.4f})."
+            )
+
+        # 4. Notional USD Cap Verification
+        if self.max_notional_usd is not None and notional_usd is not None:
+            if notional_usd > self.max_notional_usd:
+                raise ValueError(
+                    f"Trade value (${notional_usd:.2f}) exceeds maximum notional USD cap (${self.max_notional_usd:.2f})."
+                )
+
+        # 5. Cooldown Verification
+        if self.last_trade_time is not None:
+            elapsed = now - self.last_trade_time
+            if elapsed < self.cooldown_seconds:
+                remaining = self.cooldown_seconds - elapsed
+                raise ValueError(
+                    f"Trade cooldown active. Please wait {remaining:.2f} seconds before trading again."
+                )
+
+        # 6. Hourly Rate Limit Verification
+        # Filter timestamps to only keep trades within the last 3600 seconds (1 hour)
+        self.trade_timestamps = [t for t in self.trade_timestamps if now - t < 3600]
+        if len(self.trade_timestamps) >= self.max_trades_per_hour:
+            raise ValueError(
+                f"Hourly trade limit reached ({self.max_trades_per_hour} trades/hour)."
+            )
+
+    def record_trade(self, timestamp: Optional[float] = None) -> None:
+        """
+        Records a successfully executed trade timestamp.
+        """
+        now = timestamp if timestamp is not None else time.time()
+        self.last_trade_time = now
+        self.trade_timestamps.append(now)

botchain_sdk_py-0.1.0/src/botchain/agents/tools/__init__.py

@@ -0,0 +1,3 @@
+from .schemas import BOTCHAIN_TOOL_SCHEMAS, get_openai_tool_definitions
+
+__all__ = ["BOTCHAIN_TOOL_SCHEMAS", "get_openai_tool_definitions"]

botchain_sdk_py-0.1.0/src/botchain/agents/tools/base.py

@@ -0,0 +1,32 @@
+from botchain.tokens import TokenManager
+from botchain.dex import BDexManager
+from botchain.agents.executor import AgentExecutor
+
+def botchain_get_balance(client, token_address: str, account_address: str = None) -> int:
+    token_manager = TokenManager(client)
+    return token_manager.get_balance(token_address, account_address)
+
+def botchain_get_quote(client, token_in: str, token_out: str, amount_in: int, fee: int = 3000) -> int:
+    dex_manager = BDexManager(client)
+    return dex_manager.get_quote(token_in, token_out, amount_in, fee)
+
+def botchain_execute_swap(
+    client, 
+    executor: AgentExecutor, 
+    token_in: str, 
+    token_out: str, 
+    amount_in: int, 
+    fee: int = 3000, 
+    slippage_tolerance: float = 0.01,
+    notional_usd: float = None
+) -> str:
+    dex_manager = BDexManager(client)
+    return executor.execute_trade(
+        dex_manager=dex_manager,
+        token_in=token_in,
+        token_out=token_out,
+        amount_in=amount_in,
+        fee=fee,
+        slippage_tolerance=slippage_tolerance,
+        notional_usd=notional_usd
+    )

botchain_sdk_py-0.1.0/src/botchain/agents/tools/mcp_server.py

@@ -0,0 +1,115 @@
+import sys
+import json
+import logging
+from botchain.agents.tools.base import botchain_get_balance, botchain_get_quote, botchain_execute_swap
+from botchain.agents.tools.schemas import BOTCHAIN_TOOL_SCHEMAS
+
+logger = logging.getLogger(__name__)
+
+class BotChainMCPServer:
+    """
+    Model Context Protocol (MCP) Server for BOT Chain Tools.
+    Listens on stdio for JSON-RPC 2.0 requests.
+    """
+    def __init__(self, client, executor):
+        self.client = client
+        self.executor = executor
+        
+        # Tools map
+        self.tools = {
+            "botchain_get_balance": self.handle_get_balance,
+            "botchain_get_quote": self.handle_get_quote,
+            "botchain_execute_swap": self.handle_execute_swap
+        }
+
+    def handle_get_balance(self, params):
+        return botchain_get_balance(
+            self.client, 
+            params.get("token_address"), 
+            params.get("account_address")
+        )
+
+    def handle_get_quote(self, params):
+        return botchain_get_quote(
+            self.client,
+            params.get("token_in"),
+            params.get("token_out"),
+            params.get("amount_in"),
+            params.get("fee", 3000)
+        )
+
+    def handle_execute_swap(self, params):
+        return botchain_execute_swap(
+            self.client,
+            self.executor,
+            params.get("token_in"),
+            params.get("token_out"),
+            params.get("amount_in"),
+            params.get("fee", 3000),
+            params.get("slippage_tolerance", 0.01),
+            params.get("notional_usd")
+        )
+
+    def process_request(self, request_str: str) -> str:
+        try:
+            req = json.loads(request_str)
+            if not isinstance(req, dict) or "jsonrpc" not in req:
+                return json.dumps({"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": None})
+            
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params", {})
+            
+            # MCP Tool Discovery
+            if method == "tools/list":
+                return json.dumps({
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "tools": BOTCHAIN_TOOL_SCHEMAS
+                    }
+                })
+            
+            # MCP Tool Call
+            if method == "tools/call":
+                tool_name = params.get("name")
+                tool_args = params.get("arguments", {})
+                
+                if tool_name not in self.tools:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32601, "message": f"Method not found: {tool_name}"}
+                    })
+                
+                try:
+                    result = self.tools[tool_name](tool_args)
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": str(result)}]
+                        }
+                    })
+                except Exception as e:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32000, "message": str(e)}
+                    })
+            
+            return json.dumps({
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {"code": -32601, "message": "Method not found"}
+            })
+
+        except json.JSONDecodeError:
+            return json.dumps({"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": None})
+
+    def run_stdio(self):
+        """Runs the MCP server over standard input/output."""
+        for line in sys.stdin:
+            response = self.process_request(line)
+            sys.stdout.write(response + "\n")
+            sys.stdout.flush()

botchain_sdk_py-0.1.0/src/botchain/agents/tools/schemas.py

@@ -0,0 +1,97 @@
+"""
+Standardized JSON schemas for LLM Function Calling (OpenAI, Gemini, Anthropic, MCP).
+"""
+
+BOTCHAIN_TOOL_SCHEMAS = [
+    {
+        "name": "botchain_get_balance",
+        "description": "Get the token balance (native BOT or ERC20/WBOT) for a given account address on BOT Chain.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_address": {
+                    "type": "string",
+                    "description": "The contract address of the ERC20 token, or 'NATIVE' / 'WBOT' for BOT Chain native assets."
+                },
+                "account_address": {
+                    "type": "string",
+                    "description": "Optional 0x-prefixed account address. Defaults to the connected agent wallet."
+                }
+            },
+            "required": ["token_address"]
+        }
+    },
+    {
+        "name": "botchain_get_quote",
+        "description": "Query BDEX V3 for the expected output amount for a single-hop token swap.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_in": {
+                    "type": "string",
+                    "description": "The checksummed contract address of the input token."
+                },
+                "token_out": {
+                    "type": "string",
+                    "description": "The checksummed contract address of the output token."
+                },
+                "amount_in": {
+                    "type": "integer",
+                    "description": "Amount of token_in in base units (wei)."
+                },
+                "fee": {
+                    "type": "integer",
+                    "description": "Pool fee tier in hundredths of a bip (default 3000 for 0.3%).",
+                    "default": 3000
+                }
+            },
+            "required": ["token_in", "token_out", "amount_in"]
+        }
+    },
+    {
+        "name": "botchain_execute_swap",
+        "description": "Executes a policy-guarded single-hop token swap on BDEX with pre-flight simulation and optional zero-gas Paymaster sponsorship.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_in": {
+                    "type": "string",
+                    "description": "Checksummed address of the token to sell."
+                },
+                "token_out": {
+                    "type": "string",
+                    "description": "Checksummed address of the token to buy."
+                },
+                "amount_in": {
+                    "type": "integer",
+                    "description": "Amount of token_in to sell in base units."
+                },
+                "fee": {
+                    "type": "integer",
+                    "description": "Pool fee tier (e.g. 3000 for 0.3%).",
+                    "default": 3000
+                },
+                "slippage_tolerance": {
+                    "type": "number",
+                    "description": "Maximum allowed price slippage (e.g., 0.01 for 1%).",
+                    "default": 0.01
+                },
+                "notional_usd": {
+                    "type": "number",
+                    "description": "Estimated USD value of the trade for policy cap verification."
+                }
+            },
+            "required": ["token_in", "token_out", "amount_in"]
+        }
+    }
+]
+
+def get_openai_tool_definitions():
+    """Returns schemas wrapped in OpenAI function tool format."""
+    return [
+        {
+            "type": "function",
+            "function": schema
+        }
+        for schema in BOTCHAIN_TOOL_SCHEMAS
+    ]