kiban-agent-kit
Version:
Open-source framework connecting AI agents to Katana ecosystem protocols
268 lines (212 loc) • 6.86 kB
Markdown
<div align="center">
# Kiban Agent Kit
An open-source framework connecting defi AI agents to Katana ecosystem protocols.
</div>
## 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
```bash
npm install kiban-agent-kit
# or
yarn add kiban-agent-kit
# or
pnpm add kiban-agent-kit
```
## Quick Start
```typescript
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
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
// 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:
```env
# 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:
```bash
# Run the test suite
pnpm test
# Test the AI agent interactively
pnpm test:agent
```
### Chat Mode
Interactive mode for testing agent capabilities:
```typescript
"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:
```typescript
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](CONTRIBUTING.md) 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