Agents API Reference

Agent packages enable AI-powered autonomous trading and on-chain operations.

Packages

Package	Description
@nirholas/agent-wallet	CDP-based agent wallets
@nirholas/agents-ai	AI agent framework
@nirholas/agents-autonomous	Autonomous trading agents
@nirholas/agents-plugins	Agent plugin system

---

Agent Wallet (CDP)

The Agent Wallet package provides Coinbase Developer Platform (CDP) integration for AI agents.

Installation

pnpm add @nirholas/agent-wallet

Configuration

import { AgentWallet } from '@nirholas/agent-wallet'

const wallet = new AgentWallet({
  cdpApiKeyName: process.env.CDP_API_KEY_NAME!,
  cdpApiKeyPrivate: process.env.CDP_API_KEY_PRIVATE!,
  network: 'base-mainnet', // or 'base-sepolia' for testnet
})

Wallet Management

createWallet

Create a new agent wallet.

async function createWallet(options?: CreateWalletOptions): Promise<Wallet>

interface CreateWalletOptions {
  name?: string
  network?: NetworkId
}

interface Wallet {
  id: string
  address: string
  network: NetworkId
  createdAt: Date
}

type NetworkId = 
  | 'base-mainnet'
  | 'base-sepolia'
  | 'ethereum-mainnet'
  | 'ethereum-sepolia'
  | 'polygon-mainnet'
  | 'arbitrum-mainnet'

Example:

const wallet = await agentWallet.createWallet({
  name: 'trading-agent-1',
  network: 'base-mainnet',
})
console.log(`Created wallet: ${wallet.address}`)

getWallet

Get wallet by ID.

async function getWallet(walletId: string): Promise<Wallet>

listWallets

List all wallets.

async function listWallets(): Promise<Wallet[]>

exportWallet

Export wallet for backup.

async function exportWallet(walletId: string): Promise<ExportedWallet>

interface ExportedWallet {
  walletId: string
  seed: string
  networkId: string
}

importWallet

Import a previously exported wallet.

async function importWallet(data: ExportedWallet): Promise<Wallet>

---

Balance & Transfers

getBalance

Get wallet balance.

async function getBalance(
  walletId: string,
  asset?: string
): Promise<Balance>

interface Balance {
  asset: string
  amount: string
  decimals: number
}

transfer

Transfer assets between addresses.

async function transfer(params: TransferParams): Promise<TransferResult>

interface TransferParams {
  walletId: string
  to: string
  amount: string
  asset: string  // 'eth', 'usdc', or token address
  gasless?: boolean
}

interface TransferResult {
  transactionHash: string
  status: 'pending' | 'confirmed' | 'failed'
  explorerUrl: string
}

Example:

// Send ETH
const tx = await wallet.transfer({
  walletId: wallet.id,
  to: '0x...',
  amount: '0.1',
  asset: 'eth',
})

// Send USDC (gasless)
const usdcTx = await wallet.transfer({
  walletId: wallet.id,
  to: '0x...',
  amount: '100',
  asset: 'usdc',
  gasless: true,
})

---

Trading Operations

trade

Execute a token trade.

async function trade(params: TradeParams): Promise<TradeResult>

interface TradeParams {
  walletId: string
  fromAsset: string
  toAsset: string
  amount: string
  slippage?: number  // Default: 0.5%
}

interface TradeResult {
  transactionHash: string
  fromAmount: string
  toAmount: string
  price: string
  fee: string
  explorerUrl: string
}

Example:

// Swap ETH for USDC
const trade = await wallet.trade({
  walletId: wallet.id,
  fromAsset: 'eth',
  toAsset: 'usdc',
  amount: '0.5',
  slippage: 0.01,
})

console.log(`Received ${trade.toAmount} USDC`)

---

Smart Contract Interaction

deployContract

Deploy a smart contract.

async function deployContract(params: DeployParams): Promise<DeployResult>

interface DeployParams {
  walletId: string
  abi: object[]
  bytecode: string
  constructorArgs?: unknown[]
}

interface DeployResult {
  contractAddress: string
  transactionHash: string
  explorerUrl: string
}

invokeContract

Call a smart contract method.

async function invokeContract(params: InvokeParams): Promise<InvokeResult>

interface InvokeParams {
  walletId: string
  contractAddress: string
  abi: object[]
  method: string
  args?: unknown[]
  value?: string  // ETH to send
}

interface InvokeResult {
  transactionHash: string
  result?: unknown
  explorerUrl: string
}

readContract

Read data from a smart contract (no transaction).

async function readContract(params: ReadParams): Promise<unknown>

interface ReadParams {
  contractAddress: string
  abi: object[]
  method: string
  args?: unknown[]
  network: NetworkId
}

---

AI Agent Framework

Installation

pnpm add @nirholas/agents-ai

Creating an Agent

import { createAgent, AgentConfig } from '@nirholas/agents-ai'

const config: AgentConfig = {
  name: 'trading-agent',
  model: 'gpt-4o',
  personality: 'You are a professional crypto trader...',
  tools: ['market-data', 'trading', 'portfolio'],
  wallet: agentWallet,
}

const agent = await createAgent(config)

Agent Configuration

interface AgentConfig {
  name: string
  model: 'gpt-4o' | 'gpt-4' | 'claude-3-opus' | 'claude-3-sonnet'
  personality: string
  tools: AgentTool[]
  wallet?: AgentWallet
  memory?: MemoryConfig
  maxIterations?: number
  timeout?: number
}

interface MemoryConfig {
  type: 'short-term' | 'long-term' | 'both'
  maxTokens?: number
  persistPath?: string
}

type AgentTool = 
  | 'market-data'
  | 'trading'
  | 'portfolio'
  | 'social'
  | 'news'
  | 'technical-analysis'
  | 'on-chain'

Running the Agent

// Execute a single task
const result = await agent.run('Analyze BTC market conditions')

// Stream responses
for await (const chunk of agent.stream('Explain current ETH trends')) {
  process.stdout.write(chunk)
}

// Chat interface
const response = await agent.chat([
  { role: 'user', content: 'Should I buy LINK right now?' }
])

Agent Actions

interface AgentAction {
  type: 'trade' | 'analyze' | 'alert' | 'report'
  params: Record<string, unknown>
  reasoning: string
  confidence: number
}

// Listen for actions
agent.on('action', async (action: AgentAction) => {
  if (action.confidence > 0.8) {
    await executeAction(action)
  }
})

---

Autonomous Agents

Installation

pnpm add @nirholas/agents-autonomous

Autonomous Trading Agent

import { AutonomousTrader } from '@nirholas/agents-autonomous'

const trader = new AutonomousTrader({
  wallet: agentWallet,
  strategy: 'momentum',
  riskProfile: 'moderate',
  maxTradeSize: '1000',      // USDC
  maxDailyTrades: 10,
  allowedTokens: ['WETH', 'WBTC', 'LINK', 'UNI'],
  excludedTokens: ['SHIB', 'DOGE'],
})

// Start autonomous trading
await trader.start()

// Monitor performance
trader.on('trade', (trade) => {
  console.log(`Executed: ${trade.side} ${trade.amount} ${trade.token}`)
})

trader.on('decision', (decision) => {
  console.log(`Decision: ${decision.action} - ${decision.reasoning}`)
})

// Get stats
const stats = trader.getStats()
console.log(`Win rate: ${stats.winRate}%`)
console.log(`Total PnL: $${stats.totalPnL}`)

// Stop trading
await trader.stop()

Strategy Configuration

interface StrategyConfig {
  type: 'momentum' | 'mean-reversion' | 'arbitrage' | 'sentiment' | 'custom'
  timeframe: '1m' | '5m' | '15m' | '1h' | '4h' | '1d'
  indicators: IndicatorConfig[]
  entryConditions: Condition[]
  exitConditions: Condition[]
  positionSizing: 'fixed' | 'kelly' | 'volatility-adjusted'
}

interface IndicatorConfig {
  name: string
  params: Record<string, number>
  weight?: number
}

interface Condition {
  indicator: string
  operator: '>' | '<' | '>=' | '<=' | '==' | 'crosses_above' | 'crosses_below'
  value: number | string
}

---

Agent Plugins

Installation

pnpm add @nirholas/agents-plugins

Available Plugins

import {
  MarketDataPlugin,
  TechnicalAnalysisPlugin,
  NewsPlugin,
  SocialSentimentPlugin,
  OnChainDataPlugin,
  PortfolioPlugin,
} from '@nirholas/agents-plugins'

// Add plugins to agent
agent.use(MarketDataPlugin({ providers: ['coingecko', 'dexscreener'] }))
agent.use(TechnicalAnalysisPlugin())
agent.use(NewsPlugin({ sources: ['coindesk', 'cointelegraph'] }))
agent.use(SocialSentimentPlugin({ platforms: ['twitter', 'reddit'] }))
agent.use(OnChainDataPlugin({ chains: ['ethereum', 'base'] }))
agent.use(PortfolioPlugin())

Creating Custom Plugins

import { AgentPlugin, PluginContext } from '@nirholas/agents-plugins'

const myPlugin: AgentPlugin = {
  name: 'my-plugin',
  version: '1.0.0',

  tools: [
    {
      name: 'my_custom_tool',
      description: 'Does something useful',
      parameters: {
        type: 'object',
        properties: {
          input: { type: 'string', description: 'Input value' }
        },
        required: ['input']
      },
      handler: async (params, context: PluginContext) => {
        // Plugin implementation
        return { result: `Processed: ${params.input}` }
      }
    }
  ],

  onLoad: async (context) => {
    console.log('Plugin loaded')
  },

  onUnload: async (context) => {
    console.log('Plugin unloaded')
  }
}

agent.use(myPlugin)

---

Error Types

class AgentError extends Error {
  code: string
}

// Wallet errors
class WalletNotFoundError extends AgentError {}
class InsufficientFundsError extends AgentError {}
class TransactionFailedError extends AgentError {}
class NetworkError extends AgentError {}

// Agent errors
class AgentConfigError extends AgentError {}
class ToolExecutionError extends AgentError {}
class ModelError extends AgentError {}
class MemoryError extends AgentError {}

// Plugin errors
class PluginLoadError extends AgentError {}
class PluginNotFoundError extends AgentError {}

---

Type Exports

// Re-export all types
export type {
  AgentConfig,
  AgentAction,
  AgentPlugin,
  PluginContext,
  Wallet,
  Balance,
  TransferParams,
  TransferResult,
  TradeParams,
  TradeResult,
  StrategyConfig,
  IndicatorConfig,
  NetworkId,
}