Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/justmert/icp-agent-kit


https://github.com/justmert/icp-agent-kit

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

README 

          
# 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:



```bash

# 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:



```bash

# Install via npm

npm install icp-agent-kit



# Or via yarn

yarn add icp-agent-kit

```



For local development with canisters:



```bash

# 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:



```typescript

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:



```typescript

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:



```typescript

// 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](https://icp-agent.com/api/icp-agent)** - Complete TypeScript API documentation

- **[Core Plugins](https://icp-agent.com/plugins/identity)** - Identity, Token, Canister, and Cycles plugins

- **[LangChain Integration](https://icp-agent.com/langchain/overview)** - Natural language processing features

- **[Examples & Tutorials](https://icp-agent.com/examples/langchain-examples)** - Real-world usage patterns



### Quick Examples



**Identity Management:**

```typescript

// 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:**

```typescript

// 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:**

```typescript

// 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:



```bash

# 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:



```bash

# 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



```bash

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



```bash

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](CONTRIBUTING.md) for details.



### Development Setup



```bash

# 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](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](https://internetcomputer.org) - Official ICP documentation

- [Dfinity Developer Center](https://smartcontracts.org) - ICP development resources

- [ICRC Standards](https://github.com/dfinity/ICRC-1) - Token standards documentation

- [LangChain Documentation](https://docs.langchain.com) - AI agent framework

- [OpenAI API](https://platform.openai.com/docs) - Natural language processing

- [TypeScript Documentation](https://www.typescriptlang.org/docs) - Language reference



---



**Built with ❤️ for the Internet Computer ecosystem**



For questions, support, or feature requests, please [open an issue](https://github.com/justmert/icp-agent-kit/issues)