Adding Crypto Superpowers to Your ElizaOS Agent with Purple Flea

ElizaOS is the framework that powers ai16z, Virtuals.io agents, and hundreds of production crypto-native AI agents running on Discord, Telegram, and Twitter. If you are already running an Eliza character — or building one — adding real financial capabilities takes a single plugin install. This tutorial shows you how to give your agent the ability to place casino bets, open perpetual trades, check wallet balances, and create escrow payments, all triggered by natural language from your users.

What Is ElizaOS?

ElizaOS (formerly the ai16z agent framework) is the most widely deployed crypto-native AI agent framework. It runs as a Node.js process, connects to multiple platforms simultaneously (Discord, Telegram, Twitter/X, Farcaster), and uses a character file to define the agent's personality, knowledge, and available actions.

Its plugin architecture is what makes it extensible. Plugins register new actions — named intents that the agent can recognize and execute. When a user sends a message that matches an action's trigger patterns, Eliza executes the corresponding handler function. Purple Flea's plugin adds five financial actions to any Eliza character in under five minutes.

Installing the Plugin

The Purple Flea Eliza plugin is published to npm as @purpleflea/eliza-plugin. Install it into your existing Eliza project:

npm install @purpleflea/eliza-plugin

# or with pnpm (recommended for Eliza projects)
pnpm add @purpleflea/eliza-plugin

Then set your Purple Flea credentials as environment variables. The plugin reads these at startup — it never asks you to hardcode them:

PURPLEFLEA_API_KEY=pf_sk_your_key_here
PURPLEFLEA_AGENT_ID=agt_your_agent_id
PURPLEFLEA_MNEMONIC=word1 word2 word3 ... word12   # BIP-39, stored in secrets manager in production

Registering in character.json

Eliza characters are defined in JSON files. Add the plugin to your character's plugins array, and optionally add configuration in the settings block:

{
  "name": "CryptoCarla",
  "modelProvider": "anthropic",
  "model": "claude-opus-4-6",
  "bio": [
    "CryptoCarla is a sharp, no-nonsense crypto trading companion.",
    "She can place trades, manage wallets, and roll dice on your behalf."
  ],
  "plugins": [
    "@elizaos/plugin-bootstrap",
    "@purpleflea/eliza-plugin"
  ],
  "settings": {
    "purpleflea": {
      "maxBetUsd": 50,
      "maxPositionUsd": 500,
      "defaultChain": "base",
      "referralEnabled": true,
      "requireConfirmation": true
    }
  },
  "clients": ["discord", "twitter"]
}

The requireConfirmation flag makes the agent ask the user to confirm before executing any financial transaction — recommended for public-facing bots. Set it to false for fully autonomous agents.

Available Actions

The plugin registers five actions. Each has a set of natural language trigger examples that Eliza uses to recognize user intent. You can extend these patterns in your character file.

Example: Discord Casino Bot

With the plugin installed and your character configured for Discord, users in your server can immediately start interacting with the casino. Here is what the plugin does behind the scenes when a user says "flip a coin for $10":

1. Eliza's runtime classifies the message as PF_CASINO_BET intent
2. The plugin parses: game = coinflip, amount = $10, side = default (heads)
3. If requireConfirmation: true, Eliza sends a confirmation prompt
4. User confirms; plugin calls POST /api/v1/casino/coinflip
5. Purple Flea returns the result with cryptographic proof
6. Plugin formats the response and sends it back to Discord

import { Action, IAgentRuntime, Memory } from "@elizaos/core";
import { purpleFlcaClient } from "@purpleflea/eliza-plugin";

// Extend the casino action with a custom high-roller mode
export const highRollerAction: Action = {
  name: "PF_HIGH_ROLLER_BET",
  description: "Place a high-stakes casino bet (>$100)",
  similes: [
    "HIGH_ROLLER", "BIG_BET", "WHALE_BET"
  ],
  examples: [[
    {
      user: "{{user1}}",
      content: { text: "I want to bet $500 on heads" }
    },
    {
      user: "{{agentName}}",
      content: {
        text: "That's a big one. $500 on heads — let's see what fate says.",
        action: "PF_HIGH_ROLLER_BET"
      }
    }
  ]],
  validate: async (runtime: IAgentRuntime, message: Memory) => {
    // Only allow in designated high-roller channels
    const channelId = message.content?.channelId;
    return channelId === process.env.HIGH_ROLLER_CHANNEL_ID;
  },
  handler: async (runtime: IAgentRuntime, message: Memory) => {
    const client = purpleFlcaClient.fromRuntime(runtime);
    const parsed = await client.parseCasinoBet(message.content.text);
    const result = await client.casino.play(parsed);
    return {
      text: client.formatCasinoResult(result),
      action: "PF_HIGH_ROLLER_BET"
    };
  }
};

Example: Twitter Trading Agent

A Twitter/X agent powered by ElizaOS and Purple Flea can take automated trades based on market sentiment from its feed. The agent monitors mentions, extracts sentiment signals, and executes perpetual positions proportional to signal strength.

import { Action, IAgentRuntime, Memory, State } from "@elizaos/core";
import { purpleFlcaClient } from "@purpleflea/eliza-plugin";

export const sentimentTradeAction: Action = {
  name: "PF_SENTIMENT_TRADE",
  description: "Open a trade based on Twitter sentiment analysis",
  similes: ["SENTIMENT_TRADE", "SENTIMENT_SIGNAL"],
  validate: async (runtime: IAgentRuntime) => {
    // Only trigger on scheduled sentiment sweeps, not user messages
    return runtime.getSetting("SENTIMENT_AUTO_TRADE") === "true";
  },
  handler: async (runtime: IAgentRuntime, message: Memory, state?: State) => {
    const client = purpleFlcaClient.fromRuntime(runtime);

    // Score the current context window sentiment
    const context = await runtime.composeState(message);
    const sentimentScore = context.recentMessages
      .filter(m => m.content.text.toLowerCase().includes("eth"))
      .reduce((acc, m) => acc + (m.sentiment ?? 0), 0);

    if (Math.abs(sentimentScore) < 0.3) {
      return { text: "Sentiment signal too weak. Holding current position." };
    }

    const side = sentimentScore > 0 ? "long" : "short";
    const sizeUsd = Math.min(Math.abs(sentimentScore) * 100, 200);

    const result = await client.trading.openPosition({
      symbol: "ETH-PERP",
      side,
      sizeUsd,
      leverage: 2,
      stopLossPct: 0.03,
    });

    return {
      text: `Opened ${side} ETH-PERP $${sizeUsd} (sentiment: ${sentimentScore.toFixed(2)}). Tx: ${result.orderId}`,
      action: "PF_SENTIMENT_TRADE"
    };
  }
};

Earning Referral Commissions

Every transaction facilitated through your ElizaOS agent generates referral revenue for you. When your agent introduces a user to Purple Flea — whether through a casino bet, a trade, or a faucet claim — Purple Flea records your agent as the referrer and credits your account with a percentage of all fees that user generates, indefinitely.

The plugin handles referral attribution automatically. When a user interacts with your agent and is new to Purple Flea, the plugin registers them under your agent's referral code. No special configuration required — it is on by default.

To check your current referral earnings and withdraw commissions, use the built-in PF_REFERRAL_STATUS action (registered automatically by the plugin):

# User in your Discord:
User: "How much have you earned in referrals?"

# Agent response (PF_REFERRAL_STATUS action):
Agent: "I've earned $127.43 in referral commissions this month from 34 users
        I've introduced to Purple Flea. $89.20 of that came from casino
        activity, $38.23 from trading fees. Want me to withdraw to my wallet?"

The combination of ElizaOS's reach (Discord, Twitter, Telegram, Farcaster) and Purple Flea's financial primitives makes your agent more than a chatbot. It becomes an economic participant: earning commissions on every trade it facilitates, building a user base that compounds over time, and operating autonomously without any human management overhead.

For more advanced configurations — including multi-character agent networks where one Eliza character refers users to another — see the full Purple Flea for Eliza documentation.