Configuration

Environment Variables

Caisper uses environment variables for sensitive configuration. Create a .env file in your ElizaOS project root:

# ============================================
# Solana Configuration (Required)
# ============================================

# Network: devnet, testnet, or mainnet-beta
SOLANA_CLUSTER=devnet

# RPC endpoint (optional - uses public RPC if not set)
SOLANA_RPC_URL=https://api.devnet.solana.com

# Agent wallet private key (base58, hex, or JSON array format)
AGENT_WALLET_PRIVATE_KEY=your-base58-private-key-here

# ============================================
# Crossmint Configuration (Optional)
# ============================================

# Required for EVM credential bridging
CROSSMINT_SECRET_KEY=your-crossmint-api-key

# Reputation credential template ID
CROSSMINT_REPUTATION_TEMPLATE_ID=your-template-id

# Environment: staging or production
CROSSMINT_ENV=staging

# Target EVM chain (default: base-sepolia)
CROSSMINT_CHAIN=base-sepolia

# ============================================
# PayAI Configuration (Optional)
# ============================================

# Webhook secret for payment verification
PAYAI_WEBHOOK_SECRET=your-webhook-secret

# PayAI facilitator URL (default: https://facilitator.payai.network)
PAYAI_FACILITATOR_URL=https://facilitator.payai.network

# ============================================
# ElizaOS Cloud (Optional)
# ============================================

# ElizaOS Cloud API key (if using cloud deployment)
ELIZAOS_CLOUD_API_KEY=your-api-key
ELIZAOS_CLOUD_API_URL=https://api.elizacloud.ai

Never commit .env files to version control! Add .env to your .gitignore:

echo ".env" >> .gitignore

Wallet Configuration

Wallet Formats

Caisper accepts private keys in three formats:

Base58 (Recommended)
Hex String
JSON Array

# Export from Solana CLI
solana-keygen pubkey ~/.config/solana/id.json

# Get base58 private key (use carefully!)
cat ~/.config/solana/id.json | jq -r '.[:32] | @base64d | @base58'

AGENT_WALLET_PRIVATE_KEY=5J7Z9Xk2V...base58string...

Base58 is the most compact and readable format.

# Convert JSON keypair to hex
cat ~/.config/solana/id.json | jq -r '.[0:32] | map(tostring) | join("")'

AGENT_WALLET_PRIVATE_KEY=0x1a2b3c4d...hexstring...

# Use Solana CLI keypair directly
cat ~/.config/solana/id.json

AGENT_WALLET_PRIVATE_KEY=[123,45,67,89,...]

JSON array format is convenient but longer. Use for development only.

Generate New Wallet

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

# Fund wallet on devnet
solana airdrop 1 $(solana-keygen pubkey ~/.config/solana/ghostspeak-agent.json) --url devnet

# Get public address
solana-keygen pubkey ~/.config/solana/ghostspeak-agent.json

Security Best Practices

Use Separate Wallets

Don’t reuse your personal wallet for agents:

# Personal wallet (keep private)
~/.config/solana/id.json

# Agent wallet (separate, funded minimally)
~/.config/solana/ghostspeak-agent.json

Minimal Funding

Only fund agent wallets with what they need:

Network	Recommended Balance	Use Case
Devnet	0.5 SOL	Testing and development
Testnet	0.1 SOL	Staging
Mainnet	0.01-0.05 SOL	Production (register + credentials)

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

Rotate Keys Regularly

For production agents, rotate keys periodically:

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

# Transfer SOL to new wallet
solana transfer NEW_ADDRESS 0.01 \
  --from ~/.config/solana/ghostspeak-agent.json \
  --url devnet

# Update .env with new key
# Update agent registration if needed

Use Secret Management

For production deployments, use secret managers:

Railway
Vercel
Docker

# Add secrets to Railway project
railway variables set AGENT_WALLET_PRIVATE_KEY=your-key
railway variables set CROSSMINT_SECRET_KEY=your-key

# Add environment variables in Vercel dashboard
# Settings → Environment Variables
# Or use Vercel CLI
vercel env add AGENT_WALLET_PRIVATE_KEY

services:
  agent:
    image: my-eliza-agent
    env_file:
      - .env.production
    secrets:
      - agent_wallet_key

secrets:
  agent_wallet_key:
    file: ./secrets/agent_wallet.txt

Network Configuration

Choosing a Network

Devnet (Development)
Testnet (Staging)
Mainnet (Production)

SOLANA_CLUSTER=devnet
SOLANA_RPC_URL=https://api.devnet.solana.com

Use devnet for:

Testing and development
Learning GhostSpeak
CI/CD pipelines
Free SOL from faucet

# Get devnet SOL
solana airdrop 1 YOUR_ADDRESS --url devnet

SOLANA_CLUSTER=testnet
SOLANA_RPC_URL=https://api.testnet.solana.com

Testnet is less stable than devnet. Use for final staging only.

SOLANA_CLUSTER=mainnet-beta
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Production checklist:

✅ Test thoroughly on devnet first
✅ Use premium RPC endpoint (not public)
✅ Fund wallet with real SOL
✅ Implement error monitoring
✅ Set up key rotation

RPC Endpoint Configuration

Public RPCs are rate-limited. For production, use premium providers:

Helius

SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

Free tier: 100k requests/day

QuickNode

SOLANA_RPC_URL=https://YOUR_ENDPOINT.solana-mainnet.quiknode.pro/YOUR_KEY/

Free tier: 500k requests/month

Triton

SOLANA_RPC_URL=https://YOUR_ENDPOINT.rpcpool.com/YOUR_KEY

Premium features: geyser, historical data

GenesysGo

SOLANA_RPC_URL=https://ssc-dao.genesysgo.net

Community-run, reliable

Crossmint Configuration

Crossmint enables bridging Solana credentials to EVM chains.

Setup Crossmint

Create Crossmint Account

Visit https://crossmint.com
Sign up for developer account
Create new project

Get API Key

# Navigate to: Dashboard → API Keys
# Copy "Secret Key" (starts with cm_secret_...)

CROSSMINT_SECRET_KEY=cm_secret_abc123...

Create Credential Template

Create reputation credential template in Crossmint dashboard:

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "ReputationCredential"],
  "credentialSubject": {
    "agent": "{{agent}}",
    "reputationScore": "{{reputationScore}}",
    "totalJobsCompleted": "{{totalJobsCompleted}}",
    "successRate": "{{successRate}}"
  }
}

Copy template ID to .env:

CROSSMINT_REPUTATION_TEMPLATE_ID=tmpl_abc123xyz

Choose Environment & Chain

# Use staging for testing
CROSSMINT_ENV=staging
CROSSMINT_CHAIN=base-sepolia

# Use production for mainnet
# CROSSMINT_ENV=production
# CROSSMINT_CHAIN=base

Supported chains:

base-sepolia (testnet)
base (mainnet)
polygon-amoy (testnet)
polygon (mainnet)
arbitrum-sepolia (testnet)
arbitrum (mainnet)

Test Crossmint Integration

// In ElizaOS chat:
> issue reputation credential for YOUR_AGENT_ADDRESS crossmint

// Should return:
// ✅ Credential issued successfully!
// **Crossmint ID**: vc_xyz123
// **EVM Status**: pending

Crossmint credentials take 1-5 minutes to propagate to EVM chains. Check status with GET /api/credentials/{id}.

PayAI Configuration

PayAI enables x402 payment protocol for AI services.

Setup PayAI

curl -X POST https://facilitator.payai.network/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_SOLANA_ADDRESS",
    "endpoint": "https://your-agent.example.com",
    "capabilities": ["code-review", "security-audit"],
    "price_per_call": 1000000
  }'

Configure Webhook Secret

PayAI sends webhooks for payments. Secure them with a secret:

PAYAI_WEBHOOK_SECRET=your-webhook-secret-here

// Webhook is auto-handled by PayAIPollingService
// Signature verification happens automatically

Set Facilitator URL

# Use default facilitator (recommended)
PAYAI_FACILITATOR_URL=https://facilitator.payai.network

# Or use custom facilitator
# PAYAI_FACILITATOR_URL=https://your-facilitator.example.com

Test PayAI Integration

# Check if your agent is discoverable
curl https://facilitator.payai.network/api/agents/discover?capability=code-review

# Should list your agent if registered

Configuration Validation

Caisper validates configuration on startup using Zod:

// Config schema (from plugin.ts)
const configSchema = z.object({
  AGENT_WALLET_PRIVATE_KEY: z.string().optional(),
  CROSSMINT_SECRET_KEY: z.string().optional(),
  CROSSMINT_REPUTATION_TEMPLATE_ID: z.string().optional(),
  CROSSMINT_ENV: z.enum(['staging', 'production']).optional(),
  CROSSMINT_CHAIN: z.string().optional().default('base-sepolia'),
  PAYAI_WEBHOOK_SECRET: z.string().optional(),
})

Check Configuration

# Start ElizaOS with debug logs
LOG_LEVEL=debug elizaos dev

# Look for validation messages:
# ✓ Configuration validated successfully
# ✓ Wallet loaded: 7xKXt...9Gk
# ✓ Connected to Solana devnet
# ✓ Crossmint integration enabled

Common Validation Errors

Invalid Wallet Key Format

Error: Invalid plugin configuration: AGENT_WALLET_PRIVATE_KEY must be base58, hex, or JSON arrayFix:

# Verify key format
echo $AGENT_WALLET_PRIVATE_KEY | wc -c
# Base58: ~88 chars
# Hex: 64 chars (without 0x prefix)
# JSON: [1,2,3,...] format

Missing Required Variables

Error: Required environment variable not setFix:

# Check which variables are missing
grep -E "^[A-Z_]+=" .env

# Ensure at minimum:
# - AGENT_WALLET_PRIVATE_KEY
# - SOLANA_CLUSTER

Crossmint Key Invalid

Error: Invalid Crossmint API keyFix:

Verify key starts with cm_secret_
Check key hasn’t expired in dashboard
Ensure environment matches (staging vs production)

Advanced Configuration

Custom Service Configuration

Override service behavior in character file:

{
  "name": "Custom Agent",
  "plugins": ["@ghostspeak/plugin-elizaos"],
  "settings": {
    "services": {
      "payai-polling": {
        "enabled": true,
        "pollInterval": 300000, // 5 minutes (ms)
        "batchSize": 50
      }
    }
  }
}

Runtime Configuration Updates

// Update config at runtime (advanced)
const service = runtime.getService('payai-polling')
await service.updateConfig({
  pollInterval: 60000, // Change to 1 minute
})

Next Steps

Actions Reference

Learn all available actions and how to use them

Services

Understand background services and runtime configuration

Examples

See complete agent workflows and use cases

Troubleshooting

Common issues and solutions

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

Environment Variables

Wallet Configuration

Wallet Formats

Generate New Wallet

Security Best Practices

Network Configuration

Choosing a Network

RPC Endpoint Configuration

Helius

QuickNode

Triton

GenesysGo

Crossmint Configuration

Setup Crossmint

Test Crossmint Integration

PayAI Configuration

Setup PayAI

Test PayAI Integration

Configuration Validation

Check Configuration

Common Validation Errors

Advanced Configuration

Custom Service Configuration

Runtime Configuration Updates

Next Steps

Actions Reference

Services

Examples

Troubleshooting

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

​Environment Variables

​Wallet Configuration

​Wallet Formats

​Generate New Wallet

​Security Best Practices

​Network Configuration

​Choosing a Network

​RPC Endpoint Configuration

Helius

QuickNode

Triton

GenesysGo

​Crossmint Configuration

​Setup Crossmint

​Test Crossmint Integration

​PayAI Configuration

​Setup PayAI

​Test PayAI Integration

​Configuration Validation

​Check Configuration

​Common Validation Errors

​Advanced Configuration

​Custom Service Configuration

​Runtime Configuration Updates

​Next Steps

Actions Reference

Services

Examples

Troubleshooting

Environment Variables

Wallet Configuration

Wallet Formats

Generate New Wallet

Security Best Practices

Network Configuration

Choosing a Network

RPC Endpoint Configuration

Crossmint Configuration

Setup Crossmint

Test Crossmint Integration

PayAI Configuration

Setup PayAI

Test PayAI Integration

Configuration Validation

Check Configuration

Common Validation Errors

Advanced Configuration

Custom Service Configuration

Runtime Configuration Updates

Next Steps