plugin-undesirables

Personality-as-Code for ElizaOS agents. Live market data from 370K+ indexed products. Zero config required.

What This Does

plugin-undesirables gives any ElizaOS agent a structured personality, live market data from multiple free APIs, and 16 specialized skills — with zero configuration required.

Install the plugin, and your agent immediately gets:

• A working personality — a demo soul loads automatically. NFT holders get their unique AI identity.
• Live market data — real product prices from 370K+ indexed TCG products, DeFi yields from DeFiLlama, on-chain balances from Etherscan.
• 16 live-data skills — market analysis, portfolio checks, entry signals, exit strategies, risk assessment, yield farming, content creation, and more. All financial skills fetch real data.
• Passive market intelligence — an evaluator that detects card/market topics and enriches the agent's context with live pricing data automatically.

Architecture

The Undesirables ecosystem has three tiers. The plugin is the free entry point.

┌─────────────────────────────────────────────────────────┐
│  PLUGIN (npm install plugin-undesirables)                │
│  Free — no keys, no wallets, no payments                 │
│                                                          │
│  ✓ Demo soul (loads automatically, zero config)          │
│  ✓ All 16 live-data skills (DeFiLlama + Etherscan)    │
│  ✓ 9 personality-driven actions                          │
│  ✓ Live Oracle data (search + daily market snapshot)     │
│  ✓ Passive market intelligence evaluator                 │
│  ✓ NFT holder souls (unique personality + memory)        │
├──────────────────────────────────────────────────────────┤
│  ORACLE API (oracle.the-undesirables.com)                │
│  Paid — x402 micropayments, USDC on Base                 │
│                                                          │
│  $0.10  AI card grading (PSA/Beckett via vision model)   │
│  $0.015 Monte Carlo price simulation (Heston/Merton/Kou) │
│  $0.05  NFT floor price oracle + forecast                │
│  $0.05  Token price simulation (CoinGecko + Monte Carlo) │
│  $1.00  Cross-platform prediction market arbitrage       │
│  $0.50  Multi-outcome basket arbitrage                   │
│  $0.25  Weather derivatives edge scanning                │
├──────────────────────────────────────────────────────────┤
│  MCP SERVER (pip install undesirables-mcp-server)        │
│  Local — runs on your machine, 35+ tools                 │
│                                                          │
│  Full tool suite for Claude, Cursor, or any MCP client.  │
│  All processing happens locally. Nothing leaves your     │
│  machine unless you configure external API access.       │
└─────────────────────────────────────────────────────────┘

The plugin provides free personality and data. The Oracle API provides paid computational intelligence. The MCP server provides local tool access. Each tier works independently.

Quick Start

Option A: Zero Config (Demo Soul)

npm install plugin-undesirables

Add to your ElizaOS character.json:

{
  "plugins": ["plugin-undesirables"]
}

That's it. Your agent loads a demo personality with all 16 skills and live Oracle data. No wallet, no API key, no workspace download needed.

For enhanced on-chain data (portfolio checks, whale tracking), set an optional Etherscan API key:

{
  "plugins": ["plugin-undesirables"],
  "settings": {
    "ETHERSCAN_API_KEY": "your-free-etherscan-key"
  }
}

Option B: NFT Holder (Unique Soul)

If you own an Undesirable NFT, download your soul workspace from the-undesirables.com and point the plugin to it:

{
  "plugins": ["plugin-undesirables"],
  "settings": {
    "UNDESIRABLES_WORKSPACE": "/path/to/your/soul_workspace"
  }
}

Your agent gets a unique personality derived from your NFT's visual traits — Big Five psychology scores, an archetype, a strategy style, persistent memory, and a predictions ledger. No two souls are alike.

What's Included

Providers (2)

| Provider | What It Does | |----------|-------------| | undesirables-oracle | Fetches live product prices from 370K+ indexed TCG products and daily market snapshots. Triggers automatically when the conversation mentions cards, prices, or market topics. | | undesirables-soul | Injects the agent's personality context into every response. Loads demo soul by default or the NFT holder's unique soul when configured. |

Evaluators (1)

| Evaluator | What It Does | |-----------|-------------| | UNDESIRABLE_MARKET_INTELLIGENCE | Runs passively on every message. When the conversation touches TCG card topics, it auto-enriches the agent's context with live pricing from the Oracle API. The agent becomes market-aware without anyone explicitly asking. |

Actions (9)

| Action | What It Does | |--------|-------------| | UNDESIRABLE_MARKET_ANALYSIS | Personality-driven market analysis with conviction scoring and risk guardrails | | UNDESIRABLE_BUSINESS_PILOT | AI business automation — phone answering, SMS, invoicing, scheduling | | UNDESIRABLE_MEME_MACHINE | Content creation — meme concepts, brand voice, content calendars | | UNDESIRABLE_LOAD_SKILL | Routes user messages to the best-matching skill from the 16 available | | UNDESIRABLE_WHALE_TRACKER | Whale wallet movement analysis via live Etherscan data | | UNDESIRABLE_ENTRY_SIGNAL | Entry evaluation — GO / WAIT / NO-GO with live DeFiLlama prices | | UNDESIRABLE_PORTFOLIO_CHECK | Portfolio health via on-chain Etherscan balance data | | UNDESIRABLE_EXIT_STRATEGY | Exit planning — TP1/TP2/TP3 levels using live prices | | UNDESIRABLE_RISK_ASSESSMENT | Risk rating 1–10 using live DeFiLlama protocol TVL data |

Skills (16)

All 16 skills are available to every user — demo and NFT holder alike. Financial skills fetch live data from free APIs.

| Category | Skills | Data Source | |----------|--------|------------| | Market | Market Analysis, Entry Signal, Exit Strategy, Conviction Score | Oracle API, DeFiLlama prices | | Portfolio | Portfolio Check, Rebalance Check | Etherscan V2 (on-chain) | | DeFi | Farm Yield, Compound Strategy, Risk Assessment | DeFiLlama yields + protocol TVL | | On-Chain | Whale Tracker | Etherscan V2 (transactions) | | Content | Content Creation, Image Generation, Music Generation, Meme Machine | LLM + MCP tools | | Business | Business Pilot | 23-module setup system | | Logging | Prediction Log | Local JSON ledger |

Data Sources

| API | Auth | What It Provides | Skills Powered | |-----|------|-----------------|----------------| | Oracle API | None (free) | 370K+ TCG product prices, daily market snapshots | Market Analysis | | DeFiLlama | None (free) | Yield pool APYs, protocol TVL, token prices | Entry Signal, Exit Strategy, Farm Yield, Risk Assessment, Conviction Score, Compound Strategy | | Etherscan V2 | Free API key | On-chain wallet balances, transaction history | Portfolio Check, Whale Tracker, Rebalance Check |

No user data is stored. All API calls are stateless — data is fetched, displayed, and discarded. No wallets, addresses, or personal information is saved to disk or transmitted to third parties.

Access Model

| Feature | Demo (Free) | NFT Holder | |---------|:-----------:|:----------:| | All 16 skills | ✓ | ✓ | | Live Oracle data | ✓ | ✓ | | Live DeFiLlama + Etherscan data | ✓ | ✓ | | Market intelligence evaluator | ✓ | ✓ | | All 9 actions | ✓ | ✓ | | Unique personality | — | ✓ | | Persistent memory | — | ✓ | | Predictions ledger | — | ✓ | | Custom voice & archetype | — | ✓ |

Skills are the distribution. Personality is the NFT value.

• 4,444 total souls on Ethereum
• 273 minted
• 4,171 unclaimed at scatter.art/the-undesirables

How Personality Works

Each soul workspace contains a SOUL.md with structured personality data:

name: "Doña Crypto"
archetype: "The Oracle"
strategy: "Long-term accumulation with high conviction"
adjectives: ["analytical", "patient", "contrarian"]
openness: 82
conscientiousness: 91
extraversion: 34
agreeableness: 45
neuroticism: 28

The undesirables-soul provider injects this context into every agent response. Two different Undesirable agents will give completely different takes on the same question, filtered through their individual psychology.

Workspaces are keyed by runtime.agentId. Multiple Undesirable agents can run in the same ElizaOS instance without personality collision.

Security

| Measure | Implementation | |---------|---------------| | Path traversal protection | getSafePath() validates boundaries + resolves symlinks via fs.realpathSync | | YAML injection | Parsed with js-yaml JSON_SCHEMA (no function execution). __proto__, constructor, prototype keys stripped. | | Prompt isolation | Skill content wrapped with security warning — treated as inert reference material | | Oracle fetch | 8-second timeout via AbortSignal, redirect: "error" prevents SSRF | | Error handling | LLM failures return safe user-facing message — no prompt context leaked | | Multi-agent safety | Workspace state keyed by agentId — no cross-agent state leakage |

Troubleshooting

| Issue | Solution | |-------|----------| | Workspace /path/ does not exist | Check the path in your character.json. Must be an absolute path. Windows: use double backslashes \\. | | No personality detected | If no UNDESIRABLES_WORKSPACE is set, the demo soul loads automatically. Check the console for 🐸 log messages. | | Oracle data not appearing | The Oracle provider triggers on TCG-related keywords. Try asking about a specific card by name. |

Ecosystem

Plugins & SDKs

• plugin-undesirables — ElizaOS personality + market data (this package)
• undesirables-mcp-server — 35+ tool MCP server (GitHub · Glama · Official MCP Registry)
• tcg-oracle-tools — Python SDK for the Oracle API

APIs

• Oracle API — x402 pay-per-request intelligence (Swagger Docs)

Apps

• TCG Oracle Desktop — macOS, Linux, Windows installer with AI card grading UI

Data & Research

• Kaggle Dataset — 370K+ TCG products across 25 games
• Dev.to Tutorial — Build guide

Collection

• The Undesirables — 4,444 AI agents on Ethereum
• Scatter.art — Mint page
• Etherscan — Contract

Disclaimer

⚠️ This plugin provides AI-generated analysis using live market data. It is NOT financial, investment, or trading advice. The developers of this plugin assume NO liability for any financial decisions or losses resulting from the use of this software. Users are solely responsible for their own research and investment decisions. Past performance does not guarantee future results. All financial skills include automated disclaimers in their output.

License

BUSL-1.1 — Business Source License 1.1. Copyright © 2026 The Undesirables LLC.