stability-toolkit 1.0.0

A production-ready LangChain toolkit for Stability blockchain interactions without gas fees

Stability Toolkit for LangChain

A production-ready toolkit that enables AI agents to interact with the Stability blockchain without gas fees or cryptocurrency requirements.

✨ Production-Ready Features (Latest Update)

• 🔑 Environment Variable Support: Set STABILITY_API_KEY for production deployments
• 🛠️ Flexible Configuration: Initialize with custom API keys or use environment variables
• 🔒 Security Enhancements: API key sanitization in logs and error messages
• ⚠️ Production Warnings: Helpful guidance for production vs. development usage
• 📚 Comprehensive Documentation: Clear examples and best practices

🚀 Quick Start

Installation

pip install langchain-core requests

Basic Usage

from stability_toolkit import StabilityToolkit

# Option 1: Using environment variable (recommended for production)
export STABILITY_API_KEY="your-api-key"
toolkit = StabilityToolkit()

# Option 2: Direct API key (for development/testing)
toolkit = StabilityToolkit(api_key="your-api-key")

# Get all tools
tools = toolkit.get_tools()

🔑 API Key Setup

Getting Your FREE API Key

1. Visit the Stability Protocol Portal: https://portal.stabilityprotocol.com/
2. Sign up for a free account
3. Generate your API key(s)

Free Tier Limits

• 🔢 API Keys: Up to 3 keys per account
• ✍️ Write Transactions: 1,000 per month
• 📖 Read Operations: 200 per minute
• 💰 Cost: Completely FREE

Setting Up Your API Key

Option 1: Environment Variable (Recommended)

# Add to your shell profile (.bashrc, .zshrc, etc.)
export STABILITY_API_KEY="your-api-key-from-portal"

# Or set for current session
export STABILITY_API_KEY="your-api-key-from-portal"

Option 2: Direct Configuration

from stability_toolkit import StabilityToolkit

toolkit = StabilityToolkit(api_key="your-api-key-from-portal")

Option 3: Development/Testing

# Uses "try-it-out" key with limited functionality
toolkit = StabilityToolkit()

🛠️ Available Tools

1. StabilityWriteTool - Send messages to blockchain
2. StabilityReadTool - Read from smart contracts
3. StabilityWriteContractTool - Write to smart contracts
4. StabilityDeployTool - Deploy Solidity contracts

🔧 API Key Configuration

Environment Variable (Recommended)

export STABILITY_API_KEY="your-api-key"

Programmatic Configuration

toolkit = StabilityToolkit(api_key="your-api-key")

Development/Testing

# Uses "try-it-out" key with limited functionality
toolkit = StabilityToolkit()

🔒 Security Features

• API Key Sanitization: Keys are automatically sanitized in logs and error messages
• Environment Variable Support: Secure configuration without hardcoding keys
• Production Warnings: Clear guidance on API key limitations and best practices

📞 Support & Contact

• Support Email: [e-mail]
• API Portal: https://portal.stabilityprotocol.com/
• Documentation: Comprehensive examples and usage patterns included

StabilityToolkit is a LangChain-compatible toolkit that enables AI agents to interact directly with the Stability Blockchain through Zero Gas Transaction (ZKT) API endpoints. It includes tools for submitting simple messages, interacting with smart contracts (read/write), and deploying contracts — all without requiring gas fees or cryptocurrency.

---

🚀 Features

• ✅ Write plain messages to Stability (ZKT)
• ✅ Read smart contract data (ZKT Simple - view)
• ✅ Call smart contract functions (ZKT Simple - write)
• ✅ Deploy new smart contracts (ZKT Contract)
• ✅ Works with public and authenticated endpoints

---

🛠 Tools Overview

Tool Name	Description
StabilityWriteTool	POSTs a string message to the blockchain
StabilityReadTool	Reads data from smart contracts via ABI & method
StabilityWriteContractTool	Calls smart contract write methods
StabilityDeployTool	Deploys Solidity smart contracts to Stability

---

🧱 Installation

pip install langchain openai requests

---

🧪 Example Usage

from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent
from stability_toolkit import StabilityToolkit

llm = ChatOpenAI(model="gpt-4o", temperature=0)
toolkit = StabilityToolkit()
agent = initialize_agent(toolkit.get_tools(), llm, agent_type="zero-shot-react-description")

response = agent.run("Deploy a contract that stores a greeting and a value")
print(response)

---

🧪 Running Tests

# Run live blockchain tests
python -m unittest test_stability_toolkit_live.py

# Run LangChain integration tests  
python -m unittest test_stability_toolkit_langchain.py

---

🔐 API Keys

• Public endpoint: https://rpc.stabilityprotocol.com/zkt/try-it-out
• Get your free personal key at portal.stabilityprotocol.com
• Replace try-it-out in URLs with your API key to sign with your own identity.

---

📄 API Docs

For full OpenAPI documentation, see: https://stabilityprotocol.github.io/stability-api-docs

---

💡 Contribution Ideas

• Add retry logic or exponential backoff
• Support transaction result polling with wait=True
• Extend Toolkit with StatusTool or VerifyTool
• Add automatic schema validation with pydantic

---

📬 Contact

For questions, feature requests, or contributions, reach out via stabilityprotocol.com