ICP Agent Kit

A comprehensive TypeScript library that enables natural language interaction with the Internet Computer Protocol (ICP) blockchain ecosystem. Built with LangChain integration, it provides both direct API methods and AI-powered natural language processing capabilities for ICP-related operations.

Key Features:

• 🤖 Natural Language Processing - Chat with the blockchain using OpenAI and LangChain
• 🔧 Complete Plugin System - Identity, Token, Canister, and Cycles management
• 🚀 Production Ready - Comprehensive TypeScript support with strict typing
• 📚 Extensive Documentation - Complete API reference and examples
• 🎯 Specialized Agents - Purpose-built AI agents for different blockchain tasks

Introduction

ICP Agent Kit revolutionizes how developers interact with the Internet Computer Protocol by combining traditional programmatic APIs with cutting-edge natural language processing. Instead of memorizing complex blockchain APIs, developers can simply describe what they want to accomplish in plain English.

The library provides a complete toolkit for ICP development:

• Identity Management - Secure seed phrase and anonymous identity handling
• Token Operations - Full ICP and ICRC-1/2 token support with transfers and balance queries
• Canister Management - Deploy, upgrade, and interact with canisters
• Cycles Management - Monitor, top-up, and automate cycles with AI-powered forecasting

Installation

Get started with ICP Agent Kit in minutes using npm:

Prerequisites

Ensure you have the following installed:

# Node.js (version 16 or higher)
node --version

# npm (version 7 or higher) 
npm --version

# dfx (for local development)
dfx --version

Install

Install the ICP Agent Kit package:

# Install via npm
npm install icp-agent-kit

# Or via yarn
yarn add icp-agent-kit

For local development with canisters:

# Clone the repository
git clone https://github.com/justmert/icp-agent-kit.git
cd icp-agent-kit

# Install dependencies
npm install

# Start local ICP replica
dfx start --background

# Deploy sample canisters (optional)
dfx deploy

Usage

ICP Agent Kit offers two powerful ways to interact with the ICP blockchain:

Natural Language Interface (Recommended)

Chat with the blockchain using natural language:

import { ICPAgent } from 'icp-agent-kit';

// Initialize with OpenAI for natural language processing
const agent = new ICPAgent({
  network: 'mainnet',
  openai: { apiKey: process.env.OPENAI_API_KEY }
});

await agent.initialize();

// Use natural language commands
await agent.processNaturalLanguage('Check my ICP balance');
await agent.processNaturalLanguage('Transfer 2.5 ICP to alice.icp');
await agent.processNaturalLanguage('Create a new canister with 5T cycles');

// Use specialized agents for focused tasks
const defiAgent = agent.createAgent('defi');
await defiAgent.chat('Show me all my token balances and transfer 1000 tokens to bob.icp');

Direct API Interface

Use traditional programmatic APIs:

import { ICPAgent } from 'icp-agent-kit';

// Initialize without OpenAI for direct API usage
const agent = new ICPAgent({ network: 'mainnet' });
await agent.initialize();

// Identity operations
const seedPhrase = agent.identityPlugin.generateSeedPhrase(12);
await agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'main-wallet');

// Token operations
const balance = await agent.tokenPlugin.getBalance();
console.log(`Balance: ${agent.tokenPlugin.formatAmount(balance, 8)} ICP`);

await agent.tokenPlugin.transfer('recipient-account-id', BigInt('100000000')); // 1 ICP

// Canister operations
const { canisterId } = await agent.canisterPlugin.create({ cycles: '5T' });
await agent.canisterPlugin.deploy({
  canisterId,
  wasmModule: myWasmBytes
});

// Cycles operations
const cyclesBalance = await agent.cyclesPlugin.getBalance(canisterId);
await agent.cyclesPlugin.topUp(canisterId, '2T');

Specialized Agents

Use purpose-built agents for specific tasks:

// Developer Agent - Focused on canister development
const devAgent = agent.createAgent('developer');
await devAgent.chat(`
  Deploy my hello-world application:
  1. Create a canister with 10T cycles
  2. Deploy the WASM module
  3. Test the greeting function
`);

// DeFi Agent - Optimized for token operations
const defiAgent = agent.createAgent('defi');
await defiAgent.chat('Swap 5 ICP for CHAT tokens and stake them');

// Governance Agent - For DAO and NNS operations
const govAgent = agent.createAgent('governance');
await govAgent.chat('Vote YES on proposal 12345 and check my neuron status');

Documentation

Comprehensive documentation is available:

• API Reference - Complete TypeScript API documentation
• Core Plugins - Identity, Token, Canister, and Cycles plugins
• LangChain Integration - Natural language processing features
• Examples & Tutorials - Real-world usage patterns

Quick Examples

Identity Management:

// Generate secure seed phrase
const seedPhrase = agent.identityPlugin.generateSeedPhrase(24);

// Create and switch between identities
await agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'trading-wallet');
await agent.identityPlugin.createAnonymous('test-wallet');
await agent.identityPlugin.switch('trading-wallet');

Token Operations:

// ICP transfers with memo
await agent.tokenPlugin.transfer(
  'recipient-account',
  BigInt('150000000'), // 1.5 ICP
  { memo: 'Payment for services' }
);

// ICRC-1 token operations
await agent.tokenPlugin.icrc1Transfer(
  'token-canister-id',
  { owner: recipientPrincipal, subaccount: undefined },
  BigInt('1000000') // Amount in token's smallest unit
);

Canister Lifecycle:

// Complete canister deployment
const { canisterId } = await agent.canisterPlugin.create({ cycles: '10T' });
await agent.canisterPlugin.deploy({
  canisterId,
  wasmModule: wasmBytes,
  mode: 'install'
});

// Interact with deployed canister
const result = await agent.canisterPlugin.call({
  canisterId,
  methodName: 'greet',
  args: ['World'],
  idlFactory: myIdlFactory
});

Testing

Run the comprehensive test suite:

# Run all tests
npm test

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:coverage      # Generate coverage report

# Test specific plugins
npm test -- --testNamePattern="Identity"
npm test -- --testNamePattern="Token"
npm test -- --testNamePattern="Canister"
npm test -- --testNamePattern="Cycles"

Test with local dfx replica:

# Start local replica
dfx start --background

# Run integration tests
npm run test:integration

# Test sample applications
cd sample-applications/decentralized-trading-bot
npm test

Roadmap

✅ Completed Features:

• [x] Complete plugin system (Identity, Token, Canister, Cycles)
• [x] LangChain integration with 10 specialized tools
• [x] Natural language processing with OpenAI GPT-4
• [x] 4 specialized AI agents (Developer, DeFi, Governance, General)
• [x] Production-ready sample applications
• [x] Comprehensive TypeScript documentation
• [x] Extensive test coverage (100+ tests)
• [x] Live canister deployments for testing

🚀 Upcoming Features:

• [ ] Enhanced governance plugin with NNS integration
• [ ] Internet Identity authentication support
• [ ] Multi-signature transaction support
• [ ] Cross-chain bridge integrations

Sample Applications

The repository includes production-ready sample applications:

1. Decentralized Trading Bot

Location: /sample-applications/decentralized-trading-bot/

AI-powered trading bot with:

• OpenAI GPT-4 market analysis
• On-chain trade execution
• Risk management algorithms
• Real-time portfolio tracking

cd sample-applications/decentralized-trading-bot
npm install
npm start

2. DAO Voting System

Location: /sample-applications/dao-voting-system/

Governance system featuring:

• Secure cryptographic voting
• Multi-signature proposal execution
• Member management
• Immutable audit trails

cd sample-applications/dao-voting-system
npm install
npm run dev

Architecture

ICP Agent Kit follows a modular plugin architecture:

icp-agent-kit/
├── src/
│   ├── agent/              # Main ICPAgent class
│   ├── plugins/            # Core plugin system
│   │   ├── identity/       # Identity management
│   │   ├── token/          # Token operations
│   │   ├── canister/       # Canister management
│   │   └── cycles/         # Cycles management
│   ├── langchain/          # AI integration
│   │   ├── tools/          # 10 specialized tools
│   │   ├── agents/         # 4 AI agents
│   │   └── processors/     # NLP processing
│   ├── types/              # TypeScript definitions
│   └── utils/              # Shared utilities
├── sample-applications/    # Production examples
├── tests/                  # Comprehensive test suite
└── docs/                   # Mintlify documentation

Live Infrastructure

The project includes deployed production canisters:

• Agent Connector: rrkah-fqaaa-aaaaa-aaaaq-cai - Communication hub
• Persistent Storage: ryjl3-tyaaa-aaaaa-aaaba-cai - Data persistence
• Governance CrossChain: rdmx6-jaaaa-aaaaa-aaadq-cai - DAO operations

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/icp-agent-kit.git
cd icp-agent-kit

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

# Build for production
npm run build

Code Standards

• TypeScript: Strict mode enabled with comprehensive typing
• Testing: Minimum 90% coverage required
• Documentation: JSDoc comments for all public APIs
• Linting: ESLint + Prettier configuration enforced

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• Internet Computer Foundation - For the revolutionary blockchain platform
• OpenAI - For providing the GPT models that power our natural language features
• LangChain - For the excellent AI agent framework
• Dfinity Team - For the comprehensive ICP development tools and libraries
• Community Contributors - For testing, feedback, and contributions

References

• Internet Computer Protocol - Official ICP documentation
• Dfinity Developer Center - ICP development resources
• ICRC Standards - Token standards documentation
• LangChain Documentation - AI agent framework
• OpenAI API - Natural language processing
• TypeScript Documentation - Language reference

Built with ❤️ for the Internet Computer ecosystem

For questions, support, or feature requests, please open an issue