{"id":29913126,"url":"https://github.com/justmert/icp-agent-kit","last_synced_at":"2025-08-08T05:49:07.113Z","repository":{"id":307753402,"uuid":"1026233904","full_name":"justmert/icp-agent-kit","owner":"justmert","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-25T15:01:08.000Z","size":345,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-02T02:24:50.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://icp-agent.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justmert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T14:30:09.000Z","updated_at":"2025-07-30T13:18:47.000Z","dependencies_parsed_at":"2025-08-02T02:36:07.997Z","dependency_job_id":null,"html_url":"https://github.com/justmert/icp-agent-kit","commit_stats":null,"previous_names":["justmert/icp-agent-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/justmert/icp-agent-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justmert%2Ficp-agent-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justmert%2Ficp-agent-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justmert%2Ficp-agent-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justmert%2Ficp-agent-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justmert","download_url":"https://codeload.github.com/justmert/icp-agent-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justmert%2Ficp-agent-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269373037,"owners_count":24406311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-02T02:02:19.061Z","updated_at":"2025-08-08T05:49:07.084Z","avatar_url":"https://github.com/justmert.png","language":"TypeScript","funding_links":[],"categories":["Decentralized AI"],"sub_categories":["TON"],"readme":"# ICP Agent Kit\n\nA 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.\n\n**Key Features:**\n- 🤖 **Natural Language Processing** - Chat with the blockchain using OpenAI and LangChain\n- 🔧 **Complete Plugin System** - Identity, Token, Canister, and Cycles management\n- 🚀 **Production Ready** - Comprehensive TypeScript support with strict typing\n- 📚 **Extensive Documentation** - Complete API reference and examples\n- 🎯 **Specialized Agents** - Purpose-built AI agents for different blockchain tasks\n\n## Introduction\n\nICP 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.\n\nThe library provides a complete toolkit for ICP development:\n- **Identity Management** - Secure seed phrase and anonymous identity handling\n- **Token Operations** - Full ICP and ICRC-1/2 token support with transfers and balance queries  \n- **Canister Management** - Deploy, upgrade, and interact with canisters\n- **Cycles Management** - Monitor, top-up, and automate cycles with AI-powered forecasting\n\n## Installation\n\nGet started with ICP Agent Kit in minutes using npm:\n\n### Prerequisites\n\nEnsure you have the following installed:\n\n```bash\n# Node.js (version 16 or higher)\nnode --version\n\n# npm (version 7 or higher) \nnpm --version\n\n# dfx (for local development)\ndfx --version\n```\n\n### Install\n\nInstall the ICP Agent Kit package:\n\n```bash\n# Install via npm\nnpm install icp-agent-kit\n\n# Or via yarn\nyarn add icp-agent-kit\n```\n\nFor local development with canisters:\n\n```bash\n# Clone the repository\ngit clone https://github.com/justmert/icp-agent-kit.git\ncd icp-agent-kit\n\n# Install dependencies\nnpm install\n\n# Start local ICP replica\ndfx start --background\n\n# Deploy sample canisters (optional)\ndfx deploy\n```\n\n## Usage\n\nICP Agent Kit offers two powerful ways to interact with the ICP blockchain:\n\n### Natural Language Interface (Recommended)\n\nChat with the blockchain using natural language:\n\n```typescript\nimport { ICPAgent } from 'icp-agent-kit';\n\n// Initialize with OpenAI for natural language processing\nconst agent = new ICPAgent({\n  network: 'mainnet',\n  openai: { apiKey: process.env.OPENAI_API_KEY }\n});\n\nawait agent.initialize();\n\n// Use natural language commands\nawait agent.processNaturalLanguage('Check my ICP balance');\nawait agent.processNaturalLanguage('Transfer 2.5 ICP to alice.icp');\nawait agent.processNaturalLanguage('Create a new canister with 5T cycles');\n\n// Use specialized agents for focused tasks\nconst defiAgent = agent.createAgent('defi');\nawait defiAgent.chat('Show me all my token balances and transfer 1000 tokens to bob.icp');\n```\n\n### Direct API Interface\n\nUse traditional programmatic APIs:\n\n```typescript\nimport { ICPAgent } from 'icp-agent-kit';\n\n// Initialize without OpenAI for direct API usage\nconst agent = new ICPAgent({ network: 'mainnet' });\nawait agent.initialize();\n\n// Identity operations\nconst seedPhrase = agent.identityPlugin.generateSeedPhrase(12);\nawait agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'main-wallet');\n\n// Token operations\nconst balance = await agent.tokenPlugin.getBalance();\nconsole.log(`Balance: ${agent.tokenPlugin.formatAmount(balance, 8)} ICP`);\n\nawait agent.tokenPlugin.transfer('recipient-account-id', BigInt('100000000')); // 1 ICP\n\n// Canister operations\nconst { canisterId } = await agent.canisterPlugin.create({ cycles: '5T' });\nawait agent.canisterPlugin.deploy({\n  canisterId,\n  wasmModule: myWasmBytes\n});\n\n// Cycles operations\nconst cyclesBalance = await agent.cyclesPlugin.getBalance(canisterId);\nawait agent.cyclesPlugin.topUp(canisterId, '2T');\n```\n\n### Specialized Agents\n\nUse purpose-built agents for specific tasks:\n\n```typescript\n// Developer Agent - Focused on canister development\nconst devAgent = agent.createAgent('developer');\nawait devAgent.chat(`\n  Deploy my hello-world application:\n  1. Create a canister with 10T cycles\n  2. Deploy the WASM module\n  3. Test the greeting function\n`);\n\n// DeFi Agent - Optimized for token operations\nconst defiAgent = agent.createAgent('defi');\nawait defiAgent.chat('Swap 5 ICP for CHAT tokens and stake them');\n\n// Governance Agent - For DAO and NNS operations\nconst govAgent = agent.createAgent('governance');\nawait govAgent.chat('Vote YES on proposal 12345 and check my neuron status');\n```\n\n## Documentation\n\nComprehensive documentation is available:\n\n- **[API Reference](https://icp-agent.com/api/icp-agent)** - Complete TypeScript API documentation\n- **[Core Plugins](https://icp-agent.com/plugins/identity)** - Identity, Token, Canister, and Cycles plugins\n- **[LangChain Integration](https://icp-agent.com/langchain/overview)** - Natural language processing features\n- **[Examples \u0026 Tutorials](https://icp-agent.com/examples/langchain-examples)** - Real-world usage patterns\n\n### Quick Examples\n\n**Identity Management:**\n```typescript\n// Generate secure seed phrase\nconst seedPhrase = agent.identityPlugin.generateSeedPhrase(24);\n\n// Create and switch between identities\nawait agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'trading-wallet');\nawait agent.identityPlugin.createAnonymous('test-wallet');\nawait agent.identityPlugin.switch('trading-wallet');\n```\n\n**Token Operations:**\n```typescript\n// ICP transfers with memo\nawait agent.tokenPlugin.transfer(\n  'recipient-account',\n  BigInt('150000000'), // 1.5 ICP\n  { memo: 'Payment for services' }\n);\n\n// ICRC-1 token operations\nawait agent.tokenPlugin.icrc1Transfer(\n  'token-canister-id',\n  { owner: recipientPrincipal, subaccount: undefined },\n  BigInt('1000000') // Amount in token's smallest unit\n);\n```\n\n**Canister Lifecycle:**\n```typescript\n// Complete canister deployment\nconst { canisterId } = await agent.canisterPlugin.create({ cycles: '10T' });\nawait agent.canisterPlugin.deploy({\n  canisterId,\n  wasmModule: wasmBytes,\n  mode: 'install'\n});\n\n// Interact with deployed canister\nconst result = await agent.canisterPlugin.call({\n  canisterId,\n  methodName: 'greet',\n  args: ['World'],\n  idlFactory: myIdlFactory\n});\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suites\nnpm run test:unit          # Unit tests only\nnpm run test:integration   # Integration tests only\nnpm run test:coverage      # Generate coverage report\n\n# Test specific plugins\nnpm test -- --testNamePattern=\"Identity\"\nnpm test -- --testNamePattern=\"Token\"\nnpm test -- --testNamePattern=\"Canister\"\nnpm test -- --testNamePattern=\"Cycles\"\n```\n\nTest with local dfx replica:\n\n```bash\n# Start local replica\ndfx start --background\n\n# Run integration tests\nnpm run test:integration\n\n# Test sample applications\ncd sample-applications/decentralized-trading-bot\nnpm test\n```\n\n## Roadmap\n\n**✅ Completed Features:**\n- [x] Complete plugin system (Identity, Token, Canister, Cycles)\n- [x] LangChain integration with 10 specialized tools\n- [x] Natural language processing with OpenAI GPT-4\n- [x] 4 specialized AI agents (Developer, DeFi, Governance, General)\n- [x] Production-ready sample applications\n- [x] Comprehensive TypeScript documentation\n- [x] Extensive test coverage (100+ tests)\n- [x] Live canister deployments for testing\n\n**🚀 Upcoming Features:**\n- [ ] Enhanced governance plugin with NNS integration\n- [ ] Internet Identity authentication support\n- [ ] Multi-signature transaction support\n- [ ] Cross-chain bridge integrations\n\n## Sample Applications\n\nThe repository includes production-ready sample applications:\n\n### 1. Decentralized Trading Bot\n**Location:** `/sample-applications/decentralized-trading-bot/`\n\nAI-powered trading bot with:\n- OpenAI GPT-4 market analysis\n- On-chain trade execution\n- Risk management algorithms\n- Real-time portfolio tracking\n\n```bash\ncd sample-applications/decentralized-trading-bot\nnpm install\nnpm start\n```\n\n### 2. DAO Voting System\n**Location:** `/sample-applications/dao-voting-system/`\n\nGovernance system featuring:\n- Secure cryptographic voting\n- Multi-signature proposal execution\n- Member management\n- Immutable audit trails\n\n```bash\ncd sample-applications/dao-voting-system\nnpm install\nnpm run dev\n```\n\n## Architecture\n\nICP Agent Kit follows a modular plugin architecture:\n\n```\nicp-agent-kit/\n├── src/\n│   ├── agent/              # Main ICPAgent class\n│   ├── plugins/            # Core plugin system\n│   │   ├── identity/       # Identity management\n│   │   ├── token/          # Token operations\n│   │   ├── canister/       # Canister management\n│   │   └── cycles/         # Cycles management\n│   ├── langchain/          # AI integration\n│   │   ├── tools/          # 10 specialized tools\n│   │   ├── agents/         # 4 AI agents\n│   │   └── processors/     # NLP processing\n│   ├── types/              # TypeScript definitions\n│   └── utils/              # Shared utilities\n├── sample-applications/    # Production examples\n├── tests/                  # Comprehensive test suite\n└── docs/                   # Mintlify documentation\n```\n\n## Live Infrastructure\n\nThe project includes deployed production canisters:\n\n- **Agent Connector**: `rrkah-fqaaa-aaaaa-aaaaq-cai` - Communication hub\n- **Persistent Storage**: `ryjl3-tyaaa-aaaaa-aaaba-cai` - Data persistence  \n- **Governance CrossChain**: `rdmx6-jaaaa-aaaaa-aaadq-cai` - DAO operations\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Fork and clone the repository\ngit clone https://github.com/your-username/icp-agent-kit.git\ncd icp-agent-kit\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n### Code Standards\n\n- **TypeScript**: Strict mode enabled with comprehensive typing\n- **Testing**: Minimum 90% coverage required\n- **Documentation**: JSDoc comments for all public APIs\n- **Linting**: ESLint + Prettier configuration enforced\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgements\n\n- **Internet Computer Foundation** - For the revolutionary blockchain platform\n- **OpenAI** - For providing the GPT models that power our natural language features\n- **LangChain** - For the excellent AI agent framework\n- **Dfinity Team** - For the comprehensive ICP development tools and libraries\n- **Community Contributors** - For testing, feedback, and contributions\n\n## References\n\n- [Internet Computer Protocol](https://internetcomputer.org) - Official ICP documentation\n- [Dfinity Developer Center](https://smartcontracts.org) - ICP development resources\n- [ICRC Standards](https://github.com/dfinity/ICRC-1) - Token standards documentation\n- [LangChain Documentation](https://docs.langchain.com) - AI agent framework\n- [OpenAI API](https://platform.openai.com/docs) - Natural language processing\n- [TypeScript Documentation](https://www.typescriptlang.org/docs) - Language reference\n\n---\n\n**Built with ❤️ for the Internet Computer ecosystem**\n\nFor questions, support, or feature requests, please [open an issue](https://github.com/justmert/icp-agent-kit/issues)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustmert%2Ficp-agent-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustmert%2Ficp-agent-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustmert%2Ficp-agent-kit/lists"}