​
Overview

The Identity Plugin provides comprehensive identity management for ICP applications, handling seed phrases, anonymous identities, and identity switching. It’s the foundation for all authenticated operations in the ICP Agent Kit.

​
Core Features

Seed Phrase Management

Generate and manage identities using BIP39 seed phrases (12 or 24 words)

Anonymous Identities

Create anonymous identities for testing and privacy-focused applications

Identity Switching

Seamlessly switch between multiple identities within your application

Principal & Account ID

Automatic generation of ICP principals and account identifiers

​
Quick Start

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

// Initialize agent
const agent = new ICPAgent({ network: 'mainnet' });
await agent.initialize();

const identity = agent.identityPlugin;

// Generate a seed phrase and create identity
const seedPhrase = identity.generateSeedPhrase(12);
await identity.createFromSeedPhrase(seedPhrase, 'my-wallet');

// Switch to the new identity
await identity.switch('my-wallet');

// Get principal and account ID
const principal = identity.getPrincipal();
const accountId = identity.getAccountId();

​
How It Works with ICP Agent Kit

​
Architecture Integration

The Identity Plugin is tightly integrated with the core ICPAgent class and provides the foundation for all other plugins:
1

Automatic Loading

The Identity Plugin is automatically loaded when the ICPAgent is initialized
2

Shared Identity State

All other plugins (Token, Canister, Cycles) use the current active identity
3

Dynamic Switching

Identity changes are immediately reflected across all agent operations
4

Secure Storage

Identities are managed securely in memory with proper cleanup

​
Integration with ICP Network

// The Identity Plugin handles all ICP network authentication
const agent = new ICPAgent({ network: 'mainnet' });
await agent.initialize();

// Identity state affects all network operations
await identity.switch('trading-wallet');
// Now all canister calls, token transfers use 'trading-wallet' identity

await identity.switch('governance-wallet');
// Now all operations use 'governance-wallet' identity

​
Identity Types

​
1. Seed Phrase Identities

Create recoverable identities from BIP39 mnemonic phrases: 
// Generate a new seed phrase
const seedPhrase = identity.generateSeedPhrase(12); // or 24
console.log('Seed:', seedPhrase);
// "abandon ability able about above absent absorb abstract absurd abuse access accident"

// Create identity from seed phrase
const newIdentity = await identity.createFromSeedPhrase(seedPhrase, 'my-wallet');
console.log('Principal:', newIdentity.info.principal.toText());
console.log('Account ID:', newIdentity.info.accountId);

​
2. Anonymous Identities

Perfect for testing and privacy-focused applications: 
// Create anonymous identity
const anonIdentity = await identity.createAnonymous('test-mode');
console.log('Anonymous Principal:', anonIdentity.info.principal.toText());
console.log('Is Anonymous:', anonIdentity.info.isAnonymous); // true

​
Identity Management

​
Creating and Switching

// Create multiple identities for different purposes
await identity.createFromSeedPhrase(tradingSeed, 'trading');
await identity.createFromSeedPhrase(savingsSeed, 'savings');
await identity.createAnonymous('development');

// List all available identities
const allIdentities = identity.list();
console.log('Available:', allIdentities); // ['anonymous', 'trading', 'savings', 'development']

// Switch between identities
await identity.switch('trading');
console.log('Current:', identity.getCurrentKey()); // 'trading'

// Get current identity information
const info = await identity.getInfo();
console.log({
  type: info.type,
  principal: info.principal.toText(),
  accountId: info.accountId,
  isAnonymous: info.isAnonymous,
});

​
Best Practices

​
Security

Critical Security Guidelines: - Store seed phrases offline in secure locations - Never log seed phrases in production - Use 24-word phrases for high-value accounts - Implement proper key rotation policies - Use anonymous identities only for testing

​
Development

// ✅ Good: Descriptive identity names
await identity.createFromSeedPhrase(seed, 'trading-wallet');
await identity.createFromSeedPhrase(seed, 'governance-voting');

// ❌ Bad: Generic names
await identity.createFromSeedPhrase(seed, 'wallet1');
await identity.createFromSeedPhrase(seed, 'test');

// ✅ Good: Proper cleanup
await agent.destroy(); // Always cleanup when done

​
LangChain Integration

The Identity Plugin is integrated with LangChain tools for natural language operations:

​
Available Tools

get_current_identity

Shows current identity information including principal and account ID

create_identity

Creates new identities from seed phrases or anonymous

​
Natural Language Examples

// With natural language processing
const agent = new ICPAgent({
  network: 'mainnet',
  openai: { apiKey: process.env.OPENAI_API_KEY }
});
await agent.initialize();

// Check current identity
await agent.processNaturalLanguage("Show me my current identity");
// Output: "Current identity: anonymous, Principal: 2vxsx-fae..."

// Create new identity
await agent.processNaturalLanguage("Create a new identity called trading");
// Output: "Created identity 'trading' with principal: tcf25-..."

// Switch identities
await agent.processNaturalLanguage("Switch to my trading identity");
// Output: "Switched to identity 'trading'"

​
Direct Tool Usage

import { createGetCurrentIdentityTool, createIdentityTool } from 'icp-agent-kit/tools';

// Use tools directly
const identityTool = createGetCurrentIdentityTool(agent);
const result = await identityTool.invoke({}, { configurable: { agent } });

​
API Reference

​
Core Methods

// Identity creation
generateSeedPhrase(wordCount?: 12 | 24): string
createFromSeedPhrase(seedPhrase: string, key: string): Promise<IIdentityCreationResult>
createAnonymous(key: string): Promise<IIdentityCreationResult>

// Identity management
switch(key: string): Promise<void>
remove(key: string): void
list(): string[]
getCurrentKey(): string

// Identity information
getInfo(): Promise<IIdentityInfo>
getPrincipal(): string
getAccountId(): string

​
Next Steps

Token Plugin

Learn about ICP token operations and transfers

Canister Plugin

Explore canister deployment and management

API Reference

Complete API documentation

Examples

Real-world usage examples and patterns