🔧Basic Usage

Quick guide to get started with the Somnia Agent Kit SDK.

Installation

npm install somnia-agent-kit

Initialize SDK

Option 1: With Manual Config

import { SomniaAgentKit, SOMNIA_NETWORKS } from 'somnia-agent-kit';

const kit = new SomniaAgentKit({
  network: SOMNIA_NETWORKS.testnet,
  contracts: {
    agentRegistry: '0xC9f3452090EEB519467DEa4a390976D38C008347',
    agentManager: '0x77F6dC5924652e32DBa0B4329De0a44a2C95691E',
    agentExecutor: '0x157C56dEdbAB6caD541109daabA4663Fc016026e',
    agentVault: '0x7cEe3142A9c6d15529C322035041af697B2B5129',
  },
  privateKey: process.env.PRIVATE_KEY, // Optional for read operations
});

await kit.initialize();

Option 2: Auto-load from .env (Recommended)

import { SomniaAgentKit } from 'somnia-agent-kit';

// Automatically loads config from environment variables
const kit = new SomniaAgentKit();

await kit.initialize();

Configuration

Environment Variables

Create a .env file:

# Network
SOMNIA_RPC_URL=https://dream-rpc.somnia.network
SOMNIA_CHAIN_ID=50312

# Private Key (optional for read-only operations)
PRIVATE_KEY=0x...

# Contract Addresses (Testnet)
AGENT_REGISTRY_ADDRESS=0xC9f3452090EEB519467DEa4a390976D38C008347
AGENT_MANAGER_ADDRESS=0x77F6dC5924652e32DBa0B4329De0a44a2C95691E
AGENT_EXECUTOR_ADDRESS=0x157C56dEdbAB6caD541109daabA4663Fc016026e
AGENT_VAULT_ADDRESS=0x7cEe3142A9c6d15529C322035041af697B2B5129

Network Configuration

import { SOMNIA_NETWORKS } from 'somnia-agent-kit';

// Testnet (default)
network: SOMNIA_NETWORKS.testnet

// Mainnet
network: SOMNIA_NETWORKS.mainnet

// Devnet
network: SOMNIA_NETWORKS.devnet

// Custom
network: {
  rpcUrl: 'https://custom-rpc.somnia.network',
  chainId: 50312,
  name: 'Custom Network',
}

Basic Operations

Get Network Info

const network = kit.getNetworkInfo();
console.log('Network:', network.name);
console.log('Chain ID:', network.chainId);
console.log('RPC URL:', network.rpcUrl);

Get Provider

const provider = kit.getProvider();
const blockNumber = await provider.getBlockNumber();
console.log('Current block:', blockNumber);

Get Signer

const signer = kit.getSigner();
if (signer) {
  const address = await signer.getAddress();
  console.log('Your address:', address);
  
  const balance = await provider.getBalance(address);
  console.log('Balance:', ethers.formatEther(balance), 'STT');
}

SDK Convenience Methods

The SDK provides convenient getter methods for accessing all managers and utilities:

Token Management

// ERC20 tokens
const erc20 = kit.getERC20Manager();
const balance = await erc20.balanceOf(tokenAddress, account);

// ERC721 NFTs
const nft = kit.getERC721Manager();
const owner = await nft.ownerOf(collectionAddress, tokenId);

// Native tokens (STT)
const native = kit.getNativeTokenManager();
const balance = await native.getBalance();

Batch Operations

// Multicall for batching RPC calls
const multicall = kit.getMultiCall();
const results = await multicall.aggregate(calls);

Storage & IPFS

// IPFS manager
const ipfs = kit.getIPFSManager();
const metadata = await ipfs.fetchNFTMetadata('ipfs://...');

Real-time Events

// WebSocket client
const ws = kit.getWebSocketClient();
await ws.connect();
await ws.subscribeToBlocks((block) => console.log(block));

Contract Deployment

// Contract deployer
const deployer = kit.getContractDeployer();
const result = await deployer.deployContract({ abi, bytecode, constructorArgs });

// Contract verifier
const verifier = kit.getContractVerifier();
await verifier.verifyContract({ address, sourceCode, contractName });

Wallet Integration

// MetaMask connector (browser only)
const metamask = kit.getMetaMaskConnector();
if (await metamask.isAvailable()) {
  const accounts = await metamask.connect();
}

Access Contracts

AgentRegistry

// Get total agents
const total = await kit.contracts.registry.getTotalAgents();
console.log('Total agents:', total.toString());

// Get agent by ID
const agent = await kit.contracts.registry.getAgent(1);
console.log('Agent:', agent.name);

AgentManager

// Get task
const task = await kit.contracts.manager.getTask(1);
console.log('Task status:', task.status);

AgentVault

// Get balance
// Get agent address first
const agent = await kit.contracts.registry.getAgent(1);
const balance = await kit.contracts.vault.getNativeBalance(agent.owner);
console.log('Vault balance:', ethers.formatEther(balance));

AgentExecutor

// Execute task
const tx = await kit.contracts.executor.execute(taskId);
await tx.wait();

Complete Example

import { SomniaAgentKit, SOMNIA_NETWORKS } from 'somnia-agent-kit';

async function main() {
  // Initialize
  const kit = new SomniaAgentKit({
    network: SOMNIA_NETWORKS.testnet,
    contracts: {
      agentRegistry: '0xC9f3452090EEB519467DEa4a390976D38C008347',
      agentManager: '0x77F6dC5924652e32DBa0B4329De0a44a2C95691E',
      agentExecutor: '0x157C56dEdbAB6caD541109daabA4663Fc016026e',
      agentVault: '0x7cEe3142A9c6d15529C322035041af697B2B5129',
    },
    privateKey: process.env.PRIVATE_KEY,
  });

  await kit.initialize();
  console.log('✅ SDK initialized');

  // Get network info
  const network = kit.getNetworkInfo();
  console.log('📡 Network:', network.name);

  // Get your address
  const signer = kit.getSigner();
  if (signer) {
    const address = await signer.getAddress();
    console.log('👤 Address:', address);
  }

  // Query agents
  const total = await kit.contracts.registry.getTotalAgents();
  console.log('🤖 Total agents:', total.toString());

  if (total > 0n) {
    const agent = await kit.contracts.registry.getAgent(1);
    console.log('📋 Agent #1:', agent.name);
  }
}

main().catch(console.error);

Error Handling

try {
  await kit.initialize();
  // Use SDK
} catch (error) {
  console.error('Failed to initialize SDK:', error);
}

Best Practices

1. Always Initialize

await kit.initialize();
// Now safe to use kit.contracts

2. Check Signer for Write Operations

const signer = kit.getSigner();
if (!signer) {
  throw new Error('Private key required for this operation');
}

3. Handle Network Errors

try {
  const agent = await kit.contracts.registry.getAgent(id);
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    console.error('Network connection failed');
  } else {
    console.error('Error:', error);
  }
}

Next Steps

Core Features

• Working with Agents - Register and manage agents

• Task Management - Create and execute tasks

• Vault Operations - Manage agent funds

• LLM Integration - Use AI with your agents

Advanced Features

• Token Management - ERC20, ERC721, native tokens

• Multicall Batching - Optimize gas costs

• Monitoring - Logging and metrics

• Autonomous Runtime - Build self-running agents

• Storage & IPFS - Upload and retrieve data

• Real-time Events - WebSocket subscriptions

• Wallet Connectors - MetaMask integration

• Contract Deployment - Deploy and verify

• RPC Load Balancer - High availability

Reference

• API Reference - Complete API documentation

• CLI Guide - Command-line interface

See Also

• Quick Start

• Installation

• Examples