   ▄▀▄    ▄▀▄                                              
  █   ▀▀▀▀   █    ▄▄▄▄  ▄▄▄▄▄ ▄   ▄  ▄▄▄▄  ▄▄▄  ▄▄▄▄▄ ▄▄▄▄▄
  █  ▄▄  ▄▄  █    █▄▄▄▀ █▄▄▄  █▀▄ █ █     █▄▄▄█   █     ▄▀ 
▄█    ▀   ▀   █▄  █     █▄▄▄▄ █  ▀█ ▀▄▄▄▄ █   █   █   ▄█▄▄▄

🐾 OPENCATZ AI (MULTICHAIN EDITION) · 15 SPECIALIST AGENTS · 7 BLOCKCHAINS
Solana • Robinhood #4663 • Base • Ethereum • Ink • Hyperliquid • Polymarket

OpenCatz 🐾 — Autonomous Multi-Agent Crypto Intelligence System

Name: opencatz-ai
Author: dizcorvus

OpenCatz AI is an open-source autonomous Agentic AI Crypto Intelligence System & On-Chain Ecosystem on Robinhood Chain (Chain ID: 4663). It combines a squad of 15 Specialist AI Scouts across 7 major blockchains with an on-chain Dual-Sided Deflationary Vault & NFT Liquidity Peg.

Candidate signals pass through a Collaborative Consensus Protocol requiring a ≥ 80% Confidence Score before delivering alerts, trade audits, and execution via Discord, Terminal TUI, or Telegram.

Website · Robinhood Portal · Ecosystem Whitepaper · Discord Community · Twitter (@pxidentities)

⚡ Install & Quickstart

1. Clone & Install

# Clone the repository
git clone https://github.com/dizcorvus/opencatz-ai.git
cd opencatz-ai

# Install dependencies
npm install

# Link opencatz CLI globally (one-time)
npm link

2. Interactive Onboarding Wizard

# Run the interactive configuration wizard
opencatz onboard

# Or on Windows / Linux setup scripts:
bash setup.sh       # Linux / macOS
.\setup.bat         # Windows

The interactive wizard will guide you through:

Setting up your Discord Bot Token and Client ID (Optional if using Telegram/TUI standalone).
Setting up your Telegram Bot Token & Chat ID (Optional for Telegram notifications & forum topics).
Selecting your AI LLM Provider (OpenRouter Free tier, Claude, GPT-4, Z.ai, DeepSeek, etc.).
Configuring Web3 API keys (GMGN, OpenSea, Krystal Cloud, Twex).
Verifying your RPC endpoints with automated diagnostics.

3. Launch OpenCatz

# Start in live development mode (auto-reload on edit)
opencatz run

# Or launch the interactive Terminal TUI Command Center
opencatz terminal

# Or deploy as a 24/7 background process (PM2)
opencatz deploy

📱 Telegram Command Center & Standalone Mode

OpenCatz can run 100% standalone without Discord, broadcasting all multi-chain signals and interactive controls directly into Telegram:

⚙️ Setting Up Telegram Forum Topics (Sub-Channels)

Create a Telegram Group and enable Topics (Forum Mode) in Group Settings.
Add your Telegram Bot to the group as an Admin with the permission "Manage Topics" and "Post Messages".

Set your .env:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=-1001234567890   # Group Chat ID (starts with -100)

Start OpenCatz (opencatz run or opencatz deploy).
OpenCatz will automatically provision 17 sub-channels (Forum Topics):
- #opencatz-control-room (Interactive dashboard with inline toggle buttons)
- #audit-on-demand
- #call-meme-solana, #call-meme-robinhood, #call-meme-base, #call-meme-eth, #call-meme-ink
- #call-lp-solana, #call-lp-robinhood
- #call-nft-eth, #call-nft-base, #call-nft-ink, #call-nft-robinhood, #call-nft-hyperevm
- #call-whale-tracking, #call-prediction-markets, #call-ct-alpha

Note: If you use a standard Telegram group (without Topics) or a direct 1-on-1 chat with the bot, OpenCatz will automatically fallback to broadcasting all calls directly into the main chat feed without error.

🧠 How It Fits Together

                          USER INTERFACES
              (Discord Server · Terminal TUI · Telegram Bridge)
                                    │
                                    ▼
                 ┌──────────────────────────────────────┐
                 │       OPENCATZ CORE AI HUB           │
                 │   #opencatz-control-room · Chat      │
                 │   9-Lives Risk Guard · Burner Wallet │
                 │   Strategy Compiler · Key Pool       │
                 └──────────────────┬───────────────────┘
                                    │
    ┌──────────┬──────────┬─────────┼──────────┬──────────┬──────────┐
    ▼          ▼          ▼         ▼          ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌───────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│SOLANA  │ │ROBIN-  │ │BASE L2│ │ETHEREUM│ │INK L2  │ │HYPER-  │ │POLY-   │
│MEME/LP │ │HOOD #4663│ │MEME/NFT│ │MEME/NFT│ │MEME/NFT│ │LIQUID  │ │MARKET/ │
│Pump/DLMM│ │Uniswap│ │Aerodrome│ │Uniswap │ │Superchain│ │Perps/Spot│ │CT-Alpha│
└───┬────┘ └───┬────┘ └───┬───┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
    └──────────┴──────────┼─────────┴──────────┴──────────┴──────────┘
                          │ Candidate Opportunities
                          ▼
        ┌────────────────────────────────────────────────┐
        │       COLLABORATIVE AGENT CONSENSUS            │
        │  Layer 1: Quant & Liquidity Metrics (40%)      │
        │  Layer 2: Social Volume & Catalysts (30%)      │
        │  Layer 3: Security & HoneyPot Audit (30%)     │
        │  ─── HARD GATE: ≥ 80% Confidence Required ───  │
        └─────────────────┬──────────────────────────────┘
                          │ Approved High-Conviction Signals
                          ▼
            MULTI-CHANNEL DISPATCH & POSITION MANAGER
      (Automated Stop-Loss -20% · Take-Profit 2x/3x · Trailing)

Core Hub & Orchestrator: The local control plane for chat, 9-Lives risk management, burner wallets, and natural-language token audits.
15 Specialist AI Scouts: 24/7 background screening agents stalking opportunities across 7 chains.
Collaborative Consensus Protocol: Multi-agent voting system requiring a strict $\ge 80%$ confidence score before delivering call cards.
9-Lives Risk Engine: Capital preservation engine enforcing stop-losses, take-profit ladders, and dynamic trailing protection.
Universal Multi-Key Pool: Automatic rotation on HTTP 429/401/403 across unlimited backup keys.

🤖 15 Specialist AI Scouts (5 Divisions)

Division	AI Scout	Channel	Scope & Web3 Data Sources
🐱 Meme Scouts	Solana Meme Scout	`#call-meme-solana`	Pump.fun, Raydium, Meteora DLMM (GMGN + RugCheck)
	Robinhood Meme Scout	`#call-meme-robinhood`	Robinhood Chain EVM L2 (#4663) tokens (GMGN + GoPlus)
	Base Meme Scout	`#call-meme-base`	Base L2 DEX tokens & Smart Money Flow (GMGN + GoPlus)
	Ethereum Meme Scout	`#call-meme-eth`	Ethereum Mainnet DEX tokens & Whale Accumulation
	Ink Meme Scout	`#call-meme-ink`	Ink Chain / Kraken L2 Superchain DEX momentum
💧 LP Yield Scouts	Solana LP Scout	`#call-lp-solana`	Meteora DLMM Concentrated Liquidity pools (Fee APR & Vol/TVL)
	Robinhood LP Scout	`#call-lp-robinhood`	Robinhood Chain Uniswap V3 concentrated pools (Krystal Cloud)
🖼️ NFT Floor Scouts	Ethereum NFT Scout	`#call-nft-eth`	OpenSea Bluechips sweeps & 1h floor surges $\ge +20%$
	Base NFT Scout	`#call-nft-base`	Base L2 creator mints, Zora drops & trending volume breakouts
	Ink NFT Scout	`#call-nft-ink`	Ink Chain / Kraken L2 collections & trending mint momentum
	Robinhood NFT Scout	`#call-nft-robinhood`	Robinhood Chain NFT collection sweeps & floor spikes
	HyperEVM NFT Scout	`#call-nft-hyperevm`	Hyperliquid HyperEVM L1 native collections & volume breakouts
🐋 Whale & Perps	Whale & Perps Scout	`#call-whale-tracking`	Hyperliquid L1 institutional positioning, funding & spot flows
🔮 Alpha Scouts	Prediction Scout	`#call-prediction-markets`	Polymarket odds mispricing, arbitrage & whale bets
	Smart CT Alpha Scout	`#call-ct-alpha`	Twitter/X smart money KOL calls, AI narratives & airdrops

🎮 Master CLI (`opencatz` Command Suite)

Command	Aliases	Description
`opencatz onboard`	`wizard`, `setup`	🧙‍♂️ Launch interactive setup wizard (`.env` & API keys)
`opencatz terminal`	`tui`	🐾 Open standalone interactive Terminal TUI Command Center
`opencatz run`	`dev`, `start`	🚀 Start autonomous multi-agent engine in live development mode
`opencatz deploy`	`pm2`	🌐 Build & deploy 24/7 background daemon process via PM2
`opencatz doctor`	`check`	🩺 Check API key pools, RPC network latencies, & diagnostics
`opencatz update`	-	🔄 Pull latest updates from Git, rebuild, & hot-restart daemon
`opencatz test`	-	🧪 Run full automated test suite (Vitest, 43 test suites)
`opencatz build`	-	⚙️ Compile strict TypeScript codebase to production `/dist`
`opencatz uninstall`	`purge`, `clean`	🧹 Cleanly stop PM2 daemon, clear build artifacts, & reset DB

💬 Discord Slash Commands (Full Suite)

🕹️ Control Center & Core

Command	Subcommands / Options	Description
`/dashboard` or `/menu`	Direct	Opens the interactive Master Control Center dashboard with action buttons
`/health`	Direct	Real-time agent heartbeat & RPC connectivity diagnostics
`/config`	`risk` / `status`	Inspect live runtime parameters, drawdown limits, and model settings
`/update`	Direct	Trigger git pull, hot-rebuild, and seamless PM2 daemon restart

🔎 Intelligence, Audits & Screening

Command	Subcommands / Options	Description
`/screening`	`start` / `stop` / `status` / `trigger`	Control 24/7 background AI scouts across all 15 specialist channels
`/analyze`	`contract:<address>`	Forces an on-demand 12-point security, rug-check, and liquidity audit
`/pump`	`contract:<address>`	Pump.fun bonding curve progress & Raydium graduation tracker
`/holders`	`contract:<address>`	Top token holders audit, cluster detection & insider ownership
`/wallets`	`contract:<address>`	Smart money inflows & top trader wallet accumulation tracker
`/strategy`	`list` / `view` / `activate` / `rollback`	Manage modular AI screening strategies & custom logic filters

📈 Market & On-Chain Trading

Command	Subcommands / Options	Description
`/price`	`token:<symbol/CA>`	Real-time token price, 24h change & market capitalization
`/chart`	`token:<symbol/CA>`	Instant candlestick chart visual link via DexScreener
`/convert`	`amount:<n>` `symbol:<token>`	Rapid USD / Native token unit currency converter
`/alert`	`set` / `list` / `cancel`	Set real-time price alerts (triggers when price goes ABOVE/BELOW)
`/swap`	`from:` `to:` `amount:` `[chain:]`	Execute instant on-chain token swaps via Relay.link / DEX routers
`/bridge`	`origin:` `destination:` `amount:`	Real-time cross-chain bridge quote with 1-click execution link
`/send`	`to:<address>` `amount:` `[token:]`	Transfer native or ERC-20/SPL tokens to another wallet address

💼 Portfolio, Risk & Channels

Command	Subcommands / Options	Description
`/wallet`	`setup` / `list` / `replace` / `remove` / `balance` / `withdraw`	Manage encrypted burner wallets and transfer funds
`/journal`	`summary` / `history` / `export`	View Win-Rate %, PnL analytics, and export trade journal CSV
`/cancel`	`all`	Emergency circuit breaker to halt all active orders and screening
`/channel`	`create` / `rearrange`	Create custom tracking channels or automatically reorganize layout

🏛️ OpenCatz Ecosystem & Smart Contracts

The OpenCatz on-chain smart contracts (NFT Collection, Liquidity Peg Vault, and Whitepaper) are maintained in the dedicated official repository:
👉 github.com/dizcorvus/opencatz-nft

🛡️ 9-Lives Automated Risk Guard

Every trade candidate is governed by the automated 9-Lives Risk Engine:

Hard Stop-Loss (-20%): Automated capital protection cutoff to eliminate catastrophic drawdowns.
Tiered Take-Profit Ladder: Automated partial profit locking at +100% (2x) and +200% (3x).
Dynamic Trailing Stop: Activates once a position reaches +50% profit to protect unrealized gains.
Fail-Closed Security: If security checks (GoPlus/RugCheck) encounter timeouts or warnings, candidate tokens are automatically discarded.
Universal Multi-Key Pool: Stacks unlimited backup API keys (KEY_1..KEY_20) with instant auto-rotation on HTTP 429 (Rate Limit) or 401/403 errors.

🧪 Testing & Verification

OpenCatz AI includes a comprehensive test suite covering all 15 sub-agents, Web3 adapters, risk managers, and consensus logic:

# Run full Vitest suite
npm test

 Test Files  44 passed (44)
      Tests  368 passed (368)
   Duration  ~11s

🤝 Contributing

Contributions, bug reports, and feature proposals are warmly welcome!
Please review our Contributing Guidelines and Code of Conduct before submitting pull requests.

Fork the repository
Create your feature branch (git checkout -b feat/amazing-agent)
Commit your changes (git commit -m 'feat: add amazing agent')
Push to the branch (git push origin feat/amazing-agent)
Open a Pull Request on GitHub

⚖️ License & Intellectual Property

Codebase & Smart Contracts: Licensed under the open-source MIT License.

⚠️ Disclaimer (NFA & DYOR): OpenCatz AI is an open-source research and trading intelligence tool. Cryptocurrency markets carry inherent financial risks. Past performance does not guarantee future results. Not financial advice. Always do your own research.