Setup your project

Install ICP Agent Kit

Install the package via npm:

npm install icp-agent-kit

Choose Your Approach

Natural Language (Recommended)
Direct API

Initialize with OpenAI for natural language:

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

const agent = new ICPAgent({
  network: 'mainnet', // or 'local' for development
  openai: {
    apiKey: process.env.OPENAI_API_KEY // Set your API key
  }
});

await agent.initialize();

Initialize for direct API usage:

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

const agent = new ICPAgent({
  network: 'mainnet' // or 'local' for development
});

await agent.initialize();

Start Building

Natural Language
Direct API

Use simple commands to interact with the blockchain:

// Check your balance
const balance = await agent.processNaturalLanguage(
  'What is my ICP balance?'
);

// Create a new identity
await agent.processNaturalLanguage(
  'Create a new identity called trading'
);

// Transfer tokens
await agent.processNaturalLanguage(
  'Transfer 5 ICP to alice.icp'
);

Use the plugin APIs directly:

// Check balance
const balance = await agent.tokenPlugin.getBalance();
console.log(`Balance: ${balance}`);

// Create identity
const seedPhrase = agent.identityPlugin.generateSeedPhrase(12);
await agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'trading');

// Transfer tokens
await agent.tokenPlugin.transfer(
  'recipient-account-id',
  BigInt(5 * 100_000_000) // 5 ICP in e8s
);

Complete Examples

Here are complete examples for both approaches:

Natural Language Example
Direct API Example

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

async function naturalLanguageExample() {
  // Initialize with OpenAI
  const agent = new ICPAgent({
    network: 'local',
    openai: {
      apiKey: process.env.OPENAI_API_KEY
    }
  });
  await agent.initialize();

  console.log('=== Natural Language Quickstart ===\n');

  // Check identity
  const identity = await agent.processNaturalLanguage(
    'Show me my current identity'
  );
  console.log('Identity:', identity);

  // Check balance
  const balance = await agent.processNaturalLanguage(
    'What is my ICP balance?'
  );
  console.log('Balance:', balance);

  // Create a canister
  const canister = await agent.processNaturalLanguage(
    'Create a new canister with 5 trillion cycles'
  );
  console.log('Canister:', canister);

  // Use specialized agents
  const devAgent = agent.createAgent('developer');
  const help = await devAgent.chat(
    'How do I deploy a WASM module?'
  );
  console.log('Developer Help:', help);

  await agent.destroy();
  console.log('\n✅ Natural language example completed!');
}

naturalLanguageExample().catch(console.error);

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

async function directAPIExample() {
  // Initialize agent
  const agent = new ICPAgent({ network: 'local' });
  await agent.initialize();

  console.log('=== Direct API Quickstart ===\n');

  // 1. Identity management
  const identity = agent.identityPlugin;
  const seedPhrase = identity.generateSeedPhrase(12);
  await identity.createFromSeedPhrase(seedPhrase, 'my-wallet');
  await identity.switch('my-wallet');
  
  const principal = identity.getPrincipal();
  console.log('Principal:', principal);

  // 2. Token operations
  const balance = await agent.tokenPlugin.getBalance();
  console.log('Balance:', agent.tokenPlugin.formatAmount(balance, 8), 'ICP');

  // 3. Canister operations
  const { canisterId } = await agent.canisterPlugin.create({
    cycles: '5T'
  });
  console.log('Created canister:', canisterId.toText());

  // 4. Cycles operations
  const cycles = await agent.cyclesPlugin.getBalance(canisterId);
  console.log('Cycles:', agent.cyclesPlugin.formatCycles(cycles.balance));

  await agent.destroy();
  console.log('\n✅ Direct API example completed!');
}

directAPIExample().catch(console.error);

Running the Example

# Save the code above as quickstart.ts
npx ts-node quickstart.ts

Environment Setup

OpenAI API Key (for Natural Language)

To use natural language features, you need an OpenAI API key:

Get your API key from OpenAI Platform
Set it as an environment variable:

export OPENAI_API_KEY='your-api-key-here'

Or pass it directly in the configuration:

const agent = new ICPAgent({
  network: 'mainnet',
  openai: { apiKey: 'your-api-key' }
});

Local Development Setup

For local development with dfx:

Install dfx: sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
Start local replica: dfx start --clean
Use network: 'local' in your agent configuration

Important: In production, store your seed phrases securely and never log them. The examples above are for demonstration only.

Next Steps

Natural Language Guide

Master natural language commands and conversations

LangChain Tools

Explore all 10 available tools

Plugin Documentation

Deep dive into each plugin’s capabilities

Examples

See real-world examples and workflows

Try Sample Applications

Want to see ICP Agent Kit in action? Check out our production-ready sample applications:

🤖 Trading Bot

AI-Powered Decentralized Trading BotSee natural language trading commands in action:

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

Features:

Real-time market analysis
AI-powered decision making
On-chain trade recording
Natural language interface

🏛️ DAO Voting

AI-Assisted DAO Governance SystemExperience AI-powered governance:

cd sample-applications/dao-voting-system
npm install
npm start

Features:

AI proposal analysis
Automated voting with reasoning
Cryptographic verification
Real-time governance metrics

Live Demonstrations: Both applications include working JavaScript demos that you can run immediately without setup. Try node simple-trading-bot.js or node simple-dao-voting.js for instant results!

Getting Help

Common Issues

Network Connection: Make sure you have internet connectivity for mainnet operations
TypeScript Errors: Ensure you have TypeScript installed: npm install -g typescript
Permission Errors: Check that your project has proper write permissions for identity storage
OpenAI API Key: For natural language features, ensure your OpenAI API key is set correctly

Need Support?

Check our troubleshooting guide
Try the sample applications for working examples
Open an issue on GitHub
Join our Discord community

​Setup your project

​Complete Examples

​Running the Example

​Environment Setup

​Next Steps

Natural Language Guide

LangChain Tools

Plugin Documentation

Examples

​Try Sample Applications

🤖 Trading Bot

🏛️ DAO Voting

​Getting Help

Setup your project

Complete Examples

Running the Example

Environment Setup

Next Steps

Try Sample Applications

Getting Help