0.1.2 • Published 5 months ago
kiban-agent-kit v0.1.2
Kiban Agent Kit
An open-source framework connecting defi AI agents to Katana ecosystem protocols.
Features
Core Wallet Operations
- Wallet address management
- Chain information and network state
- Native token (ETH) balance tracking
- Transaction history tracking
- Gas price estimation
- Multi-chain support foundation
Token Operations
- ERC20 token interactions
- Token metadata retrieval
- Balance checking
- Token transfers
- Allowance management
- Transaction handling and receipt tracking
DeFi Operations
- Uniswap V3 integration
- Token swaps (ETH <-> ERC20, ERC20 <-> ERC20)
- Swap quotes and price impact estimation
- Slippage protection
- Transaction execution
Market Data Integration
- DexScreener integration
- Token price lookup by address
- Token search by ticker symbol
- Market data (volume, liquidity)
- Trading pair analysis
AI Agent Integration
- LangChain structured tools
- Seamless integration with LLM agents
- Comprehensive agent prompt templates
- Interactive and autonomous modes
Installation
npm install kiban-agent-kit
# or
yarn add kiban-agent-kit
# or
pnpm add kiban-agent-kit
Quick Start
import { KibanAgentKit } from 'kiban-agent-kit';
import { mainnet } from 'viem/chains';
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
// Initialize the agent
const agent = new KibanAgentKit({
privateKey: process.env.WALLET_PRIVATE_KEY as `0x${string}`,
rpcUrl: process.env.MAINNET_RPC_URL,
chain: mainnet
});
// Create AI agent with tools
const llm = new ChatOpenAI({
apiKey: process.env.OPENAI_API_KEY,
modelName: "gpt-4-turbo-preview",
temperature: 0.3,
});
const aiAgent = await createReactAgent({
llm,
tools: createKibanTools(agent),
messageModifier: AGENT_PROMPT,
});
// Start interactive mode
await runChatMode(aiAgent);
Usage Examples
Core Wallet Operations
// Get wallet information
const walletInfo = await agent.getWalletInfo();
console.log("Wallet Info:", walletInfo);
// Get transaction history
const history = await agent.getTransactionHistory();
console.log("Transaction History:", history);
// Estimate gas for a transaction
const gasEstimate = await agent.estimateGasForTransaction("0x...", "0.1");
console.log("Gas Estimate:", gasEstimate);
Token Operations
// Get token information
const tokenInfo = await agent.getTokenInfo("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
console.log("USDC Info:", tokenInfo);
// Send tokens
const txHash = await agent.sendTokens({
token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
to: "0x...",
amount: "100"
});
console.log("Transaction Hash:", txHash);
Swap Operations
// Get a swap quote
const quote = await agent.getSwapQuote({
tokenIn: "ETH",
tokenOut: "USDC",
amount: "0.0001",
slippagePercentage: 0.5
});
console.log("Expected output:", quote.tokenOut.amount);
console.log("Execution price:", quote.executionPrice);
// Execute a swap
const swapResult = await agent.swapTokens({
tokenIn: "ETH",
tokenOut: "USDC",
amount: "0.0001",
slippagePercentage: 0.5
});
console.log("Transaction hash:", swapResult.hash);
console.log("Swapped:", swapResult.amountIn, swapResult.tokenIn);
console.log("Received approximately:", swapResult.expectedAmountOut, swapResult.tokenOut);
Market Data
// Get token price data
const tokenData = await agent.getTokenData("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
console.log("USDC Price:", tokenData.priceUsd);
console.log("24h Volume:", tokenData.volume24h);
// Search for tokens by ticker
const searchResults = await agent.searchTokenByTicker("ETH");
console.log("Search Results:", searchResults);
Environment Setup
Create a .env
file in your project root:
# Required for blockchain interactions
WALLET_PRIVATE_KEY=0x... # Your wallet's private key
MAINNET_RPC_URL=... # Ethereum RPC URL (e.g., from Alchemy/Infura)
# Required for AI agent
OPENAI_API_KEY=... # Your OpenAI API key
# Optional configurations
SUBMIT_TRANSACTIONS=false # Safety flag for testing
Testing the Agent
The agent can be tested in two modes:
# Run the test suite
pnpm test
# Test the AI agent interactively
pnpm test:agent
Chat Mode
Interactive mode for testing agent capabilities:
"What's the current price of USDC?"
"Show me the top trading pairs for WETH"
"Check my ETH balance"
"Transfer 0.1 ETH to 0x..."
"Swap 0.0001 ETH to USDC"
Autonomous Mode
Automated testing of agent capabilities:
await runAutonomousMode(agent, 10); // Run with 10-second intervals
Project Structure
kiban-agent-kit/
├── src/
│ ├── agent/ # Core agent implementation
│ ├── tools/ # Core blockchain tools
│ │ ├── wallet/ # Wallet operations
│ │ ├── token/ # Token operations
│ │ └── dexscreener/ # Market data tools
│ ├── langchain/ # LangChain integration
│ │ ├── wallet.ts # Wallet LangChain tools
│ │ ├── token.ts # Token LangChain tools
│ │ ├── swap.ts # Swap LangChain tools
│ │ └── dexscreener.ts # Market data LangChain tools
│ ├── types/ # TypeScript types
│ └── constants/ # Chain configs
├── test/
│ ├── tools/ # Tool unit tests
│ └── examples/ # Usage examples
└── docs/
├── agent-actions.md # Available actions
├── tool-integration.md # Tool development guide
└── examples.md # Usage tutorials
Dependencies
- @langchain/core: ^0.1.27
- @langchain/langgraph: ^0.0.8
- @langchain/openai: ^0.0.14
- viem: ^2.7.9
- TypeScript: ^5.3.3
- Node.js >=22.0.0
Contributing
Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Add your changes 4. Add tests for new functionality 5. Submit a pull request
See our contribution guidelines for more details.
License
MIT
Security
This toolkit handles private keys and transactions. Always:
- Use secure environment variables
- Never commit private keys
- Test with small amounts first
- Enable safety flags during testing