# OpenCatz AI — Complete Technical Specifications & Architecture

## 1. Product Overview
OpenCatz AI is a production-grade Autonomous Multi-Agent DeFi Intelligence Daemon built exclusively for Robinhood Chain EVM L2 (Chain ID: #4663). It eliminates emotional trading and noisy alerts by running 5 specialist daemons, requiring a mathematically verified 3-Layer Consensus score >= 80% before any trade signal is dispatched, backed by an automated 9-Lives Risk Engine with hard stop-loss and scaling take-profit triggers.

- GitHub Repository: https://github.com/dizcorvus/opencatz-ai-robinhood-chain
- Website & TUI: https://opencatz.xyz

## 2. Network Details
- Chain: Robinhood Chain
- Type: EVM Layer 2 (Optimistic / Arbitrum Nitro Orbit stack)
- Chain ID: 4663
- Currency: Native ETH
- Canonical RPC: https://rpc.mainnet.chain.robinhood.com
- Block Explorer: https://robinhoodchain.blockscout.com
- Primary DEX: Uniswap V3 concentrated liquidity
- Security Audits: GoPlus Security REST API + GMGN Token Security API

## 3. The 5 Screening Agents Matrix
1. meme-robinhood: Monitors Robinhood Chain meme tokens via DexScreener & GMGN. Default filter: 24h Volume >= $25k, Liquidity >= $5k, 0% Buy/Sell Tax.
2. lp-robinhood: Monitors Uniswap V3 concentrated liquidity pools via Krystal Cloud (ethereum@4663). Default filter: TVL >= $10k, 24h Volume >= $100k, Fee/TVL >= 2.0%.
3. nft: Tracks OpenSea REST API v2 for Robinhood Chain NFT collections. Default filter: Floor Price >= +10% in 1h, Sales Velocity >= 3 sales/hr.
4. alpha-robinhood: Official X (Twitter) API v2 and Telegram scrapers monitoring smart money sentiment and developer commits.
5. whale-eth: Hyperliquid L1 API daemon tracking institutional derivatives positions (Perps >= $500k, Spot >= $50k) to detect macro liquidity tailwinds.

## 4. 3-Layer Agent Consensus Engine
Every prospective token or liquidity opportunity must pass through 3 independent sequential verification layers:
- Layer 1 (Quant & Liquidity): 24h volume consistency, smart money wallet flows, slippage impact < 2.5%.
- Layer 2 (Catalyst & Sentiment): Social engagement velocity, verified developer activity, organic sentiment score > 75/100.
- Layer 3 (12-Point Security Audit): GoPlus 12-point honeypot inspection, 0% buy/sell tax, ownership renounced or locked, LP locked > 90 days.
- Consensus Threshold: Overall confidence score MUST reach >= 80.0%. If score < 80%, the daemon immediately fails closed and discards the signal.

## 5. 9-Lives Risk Engine
- Hard Stop-Loss: Automatically triggers market exit at -20% drawdown.
- Take-Profit 1 (2x Milestone / +100%): Automatically liquidates 50% of the position, fully recovering initial principal.
- Take-Profit 2 (3x Milestone / +200%): Liquidates 50% of the remaining position, locking pure profit.
- Trailing Stop-Loss: Dynamic ratchet tracking the peak price with a -15% pullback trigger.
- Circuit Breaker Cutoff: Emergency halt if liquidity drops > 25% within 5 minutes or sell tax is altered by contract owner.

## 6. Complete 22 Slash Commands Reference
### Intelligence & Screening
- `/analyze <contract>`: Execute on-demand 3-layer audit for a token Contract Address (CA)
- `/screening <start|stop|status|trigger> [agent]`: Control 24/7 background screening agents
- `/price <token>`: Quick token price, 24h change & market cap lookup
- `/chart <token>`: Quick chart & DexScreener visual link
- `/holders <contract>`: Top Holders audit & insider ownership breakdown
- `/wallets <contract>`: Top Wallets & Smart Money activity scan
- `/pump <contract>`: Robinhood Chain token momentum, holder & liquidity tracker

### Wallet & Portfolio
- `/wallet <setup|list|replace|remove|balance|withdraw>`: Manage OpenCatz burner wallets & view balances
- `/swap <from> <to> <amount> [chain]`: Swap tokens instantly via Relay.link / Uniswap V3 on Robinhood Chain (#4663)
- `/send <to> <amount> [token] [chain]`: Send/transfer tokens to another wallet via Relay.link
- `/journal <summary|history|export>`: View trade journaling analytics, win-rate %, & CSV export for Excel/Notion
- `/convert <amount> <symbol>`: Quick token value & USD converter

### Risk, Strategy & Alerts
- `/config <risk|status>`: Inspect live runtime configuration, risk limits, and screening thresholds
- `/strategy <list|view|activate|rollback>`: Manage screening strategy modules (custom JavaScript .mjs strategies)
- `/alert <set|list|cancel>`: Manage real-time price alerts & trigger notifications (ABOVE / BELOW)
- `/cancel all`: Emergency stop all active screening and pending orders

### Dashboard & Operations
- `/menu`: Open the interactive OpenCatz Control Center Dashboard modal
- `/dashboard`: Open the interactive OpenCatz Control Center Dashboard
- `/health`: System health check: per-agent heartbeat (HEALTHY / DEGRADED / UNRESPONSIVE)
- `/channel <create|rearrange>`: Create custom channels or re-order OpenCatz Command Center channels neatly
- `/update`: Pull latest OpenCatz codebase from Git, re-build TypeScript, and soft-restart

## 7. Natural Language Strategy Compiler
Users can define custom screening criteria in plain English:
Example: `"Screen tokens on Robinhood Chain with >= $20k liquidity, 0% tax, and 2+ smart wallets buying in 15m"`
The engine parses the sentence into an AST (Abstract Syntax Tree) and compiles it into `strategies/custom_strategy.mjs`.

## 8. Web Dashboard REST API Endpoints
- `GET /health` or `GET /api/status`: System status, active agents, connected API keys, market regime
- `GET /api/calls`: Historical vetted signals with optional `?domain=` filter
- `GET /api/positions`: Active positions with PnL and TP/SL milestones
- `GET /api/executions`: Trade journal ledger entries and winrate metrics
- `GET /api/alerts`: Active user price alerts
- `POST /api/agents/toggle`: Toggle screening domains (`{"domain": "alpha-robinhood", "active": true}`)
- `POST /api/command`: Execute ToolRegistry actions directly from web UI