ElizaOS Plugin Development Guide

ElizaOS is the leading framework for autonomous AI agents in Web3. This guide covers plugin development, architecture, and DeFi integration patterns.

ElizaOS Architecture

ElizaOS Runtime
├── Core
│   ├── Memory Manager     # Persistent conversation memory
│   ├── Action System      # Tool execution
│   ├── Evaluator System   # Response quality evaluation
│   └── Provider System    # Context injection
├── Plugins
│   ├── @elizaos/plugin-solana    # Solana tools
│   ├── @elizaos/plugin-evm       # EVM chain tools
│   ├── @elizaos/plugin-twitter   # X/Twitter integration
│   └── Your custom plugin        # ← This guide
└── Clients
    ├── Discord
    ├── Telegram
    ├── Twitter/X
    └── Direct (REST API)

Plugin Structure

my-eliza-plugin/
├── src/
│   ├── index.ts          # Plugin entry point
│   ├── actions/          # Actions (tools) the agent can execute
│   │   ├── swap.ts
│   │   └── portfolio.ts
│   ├── evaluators/       # Evaluate responses and context
│   │   └── riskCheck.ts
│   ├── providers/        # Inject context into prompts
│   │   └── priceData.ts
│   └── types.ts          # TypeScript types
├── package.json
└── tsconfig.json

Entry Point

import { Plugin } from '@elizaos/core';
import { swapAction } from './actions/swap';
import { portfolioAction } from './actions/portfolio';
import { riskEvaluator } from './evaluators/riskCheck';
import { priceProvider } from './providers/priceData';

export const speraxPlugin: Plugin = {
  name: 'sperax',
  description: 'Sperax DeFi tools — USDs yield, SPA staking, Farms',
  actions: [swapAction, portfolioAction],
  evaluators: [riskEvaluator],
  providers: [priceProvider],
};

export default speraxPlugin;

Actions (Tools)

Actions are things the agent can do:

import { Action, IAgentRuntime, Memory } from '@elizaos/core';

export const swapAction: Action = {
  name: 'SWAP_TOKENS',
  description: 'Swap tokens on a DEX',

  // Determines if this action should be triggered
  validate: async (runtime: IAgentRuntime, message: Memory) => {
    return message.content.text.toLowerCase().includes('swap');
  },

  // Executes the action
  handler: async (runtime: IAgentRuntime, message: Memory) => {
    const { tokenIn, tokenOut, amount } = parseSwapIntent(message.content.text);

    // Execute swap via DEX aggregator
    const result = await executeSwap({
      tokenIn,
      tokenOut,
      amount,
      chain: 'arbitrum',
    });

    return {
      text: `Swapped ${amount} ${tokenIn} for ${result.amountOut} ${tokenOut}`,
      action: 'SWAP_TOKENS',
    };
  },

  // Example conversations for the LLM
  examples: [
    [
      { user: 'user1', content: { text: 'Swap 100 USDC for SPA' } },
      { user: 'agent', content: { text: 'Swapping 100 USDC for SPA on Arbitrum...' } },
    ],
  ],
};

Evaluators

Evaluators assess context and trigger behaviors:

import { Evaluator, IAgentRuntime, Memory } from '@elizaos/core';

export const riskEvaluator: Evaluator = {
  name: 'RISK_CHECK',
  description: 'Evaluates DeFi actions for risk',

  validate: async (runtime: IAgentRuntime, message: Memory) => {
    return message.content.action === 'SWAP_TOKENS' ||
           message.content.action === 'DEPOSIT';
  },

  handler: async (runtime: IAgentRuntime, message: Memory) => {
    const riskScore = await calculateRisk(message.content);

    if (riskScore > 0.8) {
      await runtime.messageManager.createMemory({
        content: { text: '⚠️ High risk detected. Please review before confirming.' },
      });
    }
  },
};

Providers

Providers inject context into the agent's prompt:

import { Provider, IAgentRuntime } from '@elizaos/core';

export const priceProvider: Provider = {
  name: 'PRICE_DATA',
  description: 'Provides current crypto prices',

  get: async (runtime: IAgentRuntime) => {
    const prices = await fetchPrices(['SPA', 'ETH', 'BTC', 'USDs']);

    return `Current prices:\n${prices of the tokens listed}`;
  },
};

Memory System

ElizaOS has a powerful memory system:

// Store data in agent memory
await runtime.messageManager.createMemory({
  content: { text: 'User prefers SPA staking over LP farming' },
  roomId: message.roomId,
  userId: message.userId,
});

// Retrieve memories
const memories = await runtime.messageManager.getMemories({
  roomId: message.roomId,
  count: 10,
});

DeFi Plugin Patterns

Sperax Plugin Example

export const speraxPlugin: Plugin = {
  name: 'sperax',
  actions: [
    mintUSDs,       // Mint USDs from collateral
    redeemUSDs,     // Redeem USDs for collateral
    stakeSPA,       // Stake SPA for veSPA
    farmDeposit,    // Deposit into Sperax Farms
    portfolioView,  // View Sperax portfolio
  ],
  evaluators: [
    slippageCheck,  // Check slippage before swaps
    gasCheck,       // Check gas before transactions
  ],
  providers: [
    speraxPrices,   // SPA, USDs prices
    farmAPYs,       // Current farm APY data
    veSPAStats,     // veSPA governance stats
  ],
};

Links

• ElizaOS: https://elizaos.ai
• Docs: https://docs.elizaos.ai
• GitHub: https://github.com/elizaos/eliza
• Plugin: https://github.com/nirholas/elizaos-plugin
• SperaxOS: https://app.sperax.io