Installation

Prerequisites

Before installing Caisper, ensure you have:

ElizaOS v1.7.0+

# Check ElizaOS version
elizaos --version
# Should be >= 1.7.0

# Install ElizaOS CLI if needed
npm install -g @elizaos/[email protected]

Bun Runtime

# Install Bun (recommended over npm/yarn)
curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version

GhostSpeak uses Bun as the primary package manager. While npm/yarn work, Bun provides faster installs and better ESM support.

Solana Wallet

You’ll need a Solana wallet with:

Devnet: ~0.5 SOL (free from faucet)
Mainnet: ~0.01 SOL for agent registration

Generate New Wallet
Use Existing Wallet

# Generate new keypair
solana-keygen new --outfile ~/.config/solana/ghostspeak-agent.json

# Save the seed phrase safely!

# Export from Phantom/Backpack to JSON
# Or use existing Solana CLI keypair
cp ~/.config/solana/id.json ~/.config/solana/ghostspeak-agent.json

RPC Endpoint (Optional)

While GhostSpeak works with public RPCs, premium endpoints provide better performance:

Helius

Free tier: 100k requests/day

QuickNode

Free tier: 500k requests/month

Installation Methods

ElizaOS CLI (Recommended)
Manual Installation
Development Mode

Using ElizaOS Plugin Manager

The fastest way to add Caisper to your agent:

# Navigate to your ElizaOS project
cd my-eliza-agent

# Add Caisper plugin
elizaos plugin add @ghostspeak/plugin-elizaos

# Install dependencies
bun install

The CLI automatically:

Adds plugin to package.json
Updates agent character file
Creates environment variable template

Verify Installation

# Check if plugin is registered
elizaos plugin list

# Should show:
# ✓ @ghostspeak/plugin-elizaos v0.1.0

Install Package

# Using Bun (recommended)
bun add @ghostspeak/plugin-elizaos

# Or using npm
npm install @ghostspeak/plugin-elizaos

# Or using pnpm
pnpm add @ghostspeak/plugin-elizaos

Update Character File

Add Caisper to your agent’s character configuration:

{
  "name": "My Agent",
  "plugins": [
    "@ghostspeak/plugin-elizaos"
  ],
  "settings": {
    "secrets": {
      "AGENT_WALLET_PRIVATE_KEY": "your-base58-key-here"
    }
  }
}

Import in Code

import { starterPlugin } from '@ghostspeak/plugin-elizaos'

const agent = await createAgent({
  character: myCharacter,
  plugins: [starterPlugin],
  // ... other config
})

Clone from Source

For plugin development or contributing:

# Clone GhostSpeak monorepo
git clone https://github.com/ghostspeak/ghostspeak.git
cd ghostspeak

# Install dependencies
bun install

# Navigate to plugin
cd packages/plugin-ghostspeak

# Build plugin
bun run build

# Link to your ElizaOS project
cd ~/my-eliza-agent
bun link @ghostspeak/plugin-elizaos

Watch Mode

# In plugin directory
bun run build:watch

# In another terminal (ElizaOS project)
elizaos dev

Development mode links the local package. Changes to plugin source will rebuild automatically.

Add to ElizaOS Agent

Method 1: Character File (Recommended)

The declarative approach using ElizaOS character configuration:

{
  "name": "GhostSpeak Agent",
  "description": "AI agent with on-chain reputation",
  "modelProvider": "anthropic",
  "plugins": [
    "@ghostspeak/plugin-elizaos"
  ],
  "settings": {
    "secrets": {
      "AGENT_WALLET_PRIVATE_KEY": "base58-encoded-private-key",
      "SOLANA_CLUSTER": "devnet",
      "SOLANA_RPC_URL": "https://api.devnet.solana.com"
    }
  },
  "bio": [
    "I track my reputation on GhostSpeak blockchain",
    "I can issue and verify W3C credentials",
    "I accept x402 payments for my services"
  ]
}

Store sensitive values in .env and reference them with ${VARIABLE_NAME} syntax in character files.

Method 2: Programmatic Registration

The code-first approach for custom agent setup:

import { createAgent } from '@elizaos/core'
import { starterPlugin } from '@ghostspeak/plugin-elizaos'

// Create agent with GhostSpeak plugin
const agent = await createAgent({
  character: {
    name: "My GhostSpeak Agent",
    modelProvider: "anthropic",
    plugins: ["@ghostspeak/plugin-elizaos"],
    settings: {
      secrets: {
        AGENT_WALLET_PRIVATE_KEY: process.env.AGENT_WALLET_PRIVATE_KEY,
        SOLANA_CLUSTER: process.env.SOLANA_CLUSTER || "devnet",
      }
    }
  },
  plugins: [starterPlugin],
  modelProvider: anthropicProvider,
})

// Start agent
await agent.start()

console.log('Agent running with GhostSpeak integration!')

Method 3: Dynamic Plugin Loading

Load plugins at runtime based on conditions:

import { createAgent } from '@elizaos/core'

const agent = await createAgent({
  character: myCharacter,
  plugins: [], // Start with no plugins
})

// Load GhostSpeak plugin conditionally
if (process.env.ENABLE_GHOSTSPEAK === 'true') {
  const { starterPlugin } = await import('@ghostspeak/plugin-elizaos')
  await agent.registerPlugin(starterPlugin)
  console.log('GhostSpeak plugin loaded dynamically')
}

await agent.start()

Verify Installation

Quick Health Check

# Start ElizaOS in dev mode
elizaos dev

# In agent chat, test actions:
# 1. Hello world test
> hello

# 2. Check Ghost Score (will fail gracefully if no agent registered)
> check ghost score

# 3. Test credential action
> issue credential for test

Expected output:

✅ Caisper plugin loaded
✅ Actions registered: 5
✅ Services started: 2
✅ Providers active: 2

Test Actions Available

// In ElizaOS console
agent.getActions().filter(a => a.name.includes('GHOST'))

// Should return:
// - CHECK_GHOST_SCORE
// - REGISTER_AGENT
// - ISSUE_CREDENTIAL

Test Service Health

# Check plugin services
curl http://localhost:3000/api/ghost-score/YOUR_AGENT_ADDRESS

# Should return JSON with Ghost Score data

Troubleshooting

Plugin Not Loading

Symptoms: Plugin doesn’t appear in elizaos plugin listSolutions:

Check package.json includes @ghostspeak/plugin-elizaos
Run bun install to ensure dependencies are installed
Verify character file has plugin in plugins array
Check ElizaOS version is >= 1.7.0

# Reinstall plugin
bun remove @ghostspeak/plugin-elizaos
bun add @ghostspeak/plugin-elizaos
elizaos dev

Wallet Issues

Symptoms: “Insufficient SOL balance” or “Invalid wallet”Solutions:

Verify wallet file exists and is readable
Check wallet has SOL on correct network (devnet vs mainnet)
Request devnet SOL from faucet

# Check wallet balance
solana balance ~/.config/solana/ghostspeak-agent.json --url devnet

# Request devnet SOL
solana airdrop 1 $(solana-keygen pubkey ~/.config/solana/ghostspeak-agent.json) --url devnet

RPC Connection Errors

Symptoms: “Failed to connect to RPC” or timeoutsSolutions:

Check SOLANA_RPC_URL is set correctly
Verify network is reachable (curl the RPC endpoint)
Try different RPC provider (Helius, QuickNode)
Check firewall/proxy settings

# Test RPC connectivity
curl -X POST https://api.devnet.solana.com \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# Should return: {"jsonrpc":"2.0","result":"ok","id":1}

Action Not Triggering

Symptoms: Actions don’t respond to commandsSolutions:

Check action validation logic (see validate function)
Verify command syntax matches examples
Enable debug logging to see action matching

# Enable debug logs
LOG_LEVEL=debug elizaos dev

# Watch for action validation logs

Upgrade Guide

Minor Version Updates (0.1.x → 0.1.y)

# Update plugin
bun update @ghostspeak/plugin-elizaos

# Restart agent
elizaos restart

Major Version Updates (0.x → 1.x)

Major version updates may include breaking changes. Always check the CHANGELOG before upgrading.

# Check for breaking changes
cat node_modules/@ghostspeak/plugin-elizaos/CHANGELOG.md

# Update with caution
bun update @ghostspeak/plugin-elizaos@latest

# Review migration guide if provided

Next Steps

Configuration

Set up environment variables and wallet configuration

Actions Reference

Learn all available actions and commands

Examples

See complete agent workflows

SDK Docs

Dive deeper into GhostSpeak SDK

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

Prerequisites

Helius

QuickNode

Installation Methods

Using ElizaOS Plugin Manager

Verify Installation

Install Package

Update Character File

Import in Code

Clone from Source

Watch Mode

Add to ElizaOS Agent

Method 1: Character File (Recommended)

Method 2: Programmatic Registration

Method 3: Dynamic Plugin Loading

Verify Installation

Quick Health Check

Test Actions Available

Test Service Health

Troubleshooting

Upgrade Guide

Minor Version Updates (0.1.x → 0.1.y)

Major Version Updates (0.x → 1.x)

Next Steps

Configuration

Actions Reference

Examples

SDK Docs

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

​Prerequisites

Helius

QuickNode

​Installation Methods

​Using ElizaOS Plugin Manager

​Verify Installation

​Install Package

​Update Character File

​Import in Code

​Clone from Source

​Watch Mode

​Add to ElizaOS Agent

​Method 1: Character File (Recommended)

​Method 2: Programmatic Registration

​Method 3: Dynamic Plugin Loading

​Verify Installation

​Quick Health Check

​Test Actions Available

​Test Service Health

​Troubleshooting

​Upgrade Guide

​Minor Version Updates (0.1.x → 0.1.y)

​Major Version Updates (0.x → 1.x)

​Next Steps

Configuration

Actions Reference

Examples

SDK Docs

Prerequisites

Installation Methods

Using ElizaOS Plugin Manager

Verify Installation

Install Package

Update Character File

Import in Code

Clone from Source

Watch Mode

Add to ElizaOS Agent

Method 1: Character File (Recommended)

Method 2: Programmatic Registration

Method 3: Dynamic Plugin Loading

Verify Installation

Quick Health Check

Test Actions Available

Test Service Health

Troubleshooting

Upgrade Guide

Minor Version Updates (0.1.x → 0.1.y)

Major Version Updates (0.x → 1.x)

Next Steps