🚀 mucch

AI-Assisted Trading Agent for Perpetuals and Futures on Hyperliquid

mucch is an intelligent trading bot that combines the power of AI (GPT-4 or Claude) with Hyperliquid's perpetual futures trading platform. It provides real-time market analysis, automated trading signals, and a beautiful terminal dashboard for monitoring your positions.

✨ Features

• 🤖 AI-Powered Analysis: Uses OpenAI GPT-4 or OpenRouter (Claude 3.5 Sonnet) for intelligent trade analysis
• 📊 Live Terminal Dashboard: Beautiful real-time charts for BTC and ETH using blessed-contrib
• 💰 PNL Tracking: Real-time profit and loss monitoring
• 🎯 Risk Management: Configurable risk percentage and position sizing
• 📈 Multiple Assets: Supports 100+ cryptocurrencies on Hyperliquid
• 🔔 AI Trading Signals: Get BUY/SELL/HOLD recommendations with confidence scores
• 🛡️ Safe by Default: Conservative AI prompting and built-in risk controls

📦 Installation

npm install mucch

🚀 Quick Start

1. Setup Environment Variables

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env with your credentials:

# Hyperliquid API Configuration
HYPERLIQUID_PRIVATE_KEY=your_private_key_here
HYPERLIQUID_ACCOUNT_ADDRESS=your_wallet_address_here

# AI Configuration (choose one)
OPENAI_API_KEY=your_openai_api_key_here
# OR
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Trading Configuration (optional)
RISK_PERCENTAGE=1.0
MAX_POSITION_SIZE=1000
ENABLE_AI_SUGGESTIONS=true

2. Run mucch

npx mucch

Or if installed globally:

mucch

🔑 Getting Your Hyperliquid Credentials

Account Address (Public Key)

Your Hyperliquid wallet address (starts with 0x...)

Private Key

⚠️ SECURITY WARNING: Never share your private key. Keep it secure.

1. Go to app.hyperliquid.xyz
2. Connect your wallet
3. Export your private key from MetaMask or your wallet provider
4. Add it to your .env file

Optional: API Wallet

For enhanced security, you can create an API wallet:

1. Visit app.hyperliquid.xyz/API
2. Generate a new API key
3. Use the API wallet's private key in your .env
4. Keep your main wallet address as HYPERLIQUID_ACCOUNT_ADDRESS

🤖 AI Configuration

mucch supports two AI providers:

OpenAI (GPT-4)

1. Get API key from platform.openai.com
2. Add to .env: OPENAI_API_KEY=sk-...

OpenRouter (Claude 3.5 Sonnet)

1. Get API key from openrouter.ai
2. Add to .env: OPENROUTER_API_KEY=sk-...

📊 Dashboard Features

When you run mucch, you'll see:

📈 Live Price Charts

• BTC/USD: Real-time Bitcoin price chart (yellow line)
• ETH/USD: Real-time Ethereum price chart (cyan line)
• Updates every 5 seconds with the latest market data

💰 Account Info

• Account Value
• Total PNL
• Unrealized PNL
• Realized PNL

🤖 AI Trading Signals

• Real-time AI analysis for BTC and ETH
• Trading recommendations (BUY/SELL/HOLD)
• Confidence scores (0-100%)
• Detailed reasoning for each signal
• Suggested position sizes
• Stop loss and take profit levels

📈 Open Positions Table

• All your active positions
• Entry prices
• Current P&L per position
• Position sizes

Controls

• Press q or ESC to quit
• Dashboard auto-refreshes every 5 seconds

⚙️ Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HYPERLIQUID_PRIVATE_KEY | ✅ | - | Your wallet's private key | | HYPERLIQUID_ACCOUNT_ADDRESS | ✅ | - | Your wallet address | | HYPERLIQUID_API_URL | ❌ | https://api.hyperliquid.xyz | API endpoint (use testnet for testing) | | OPENAI_API_KEY | ❌* | - | OpenAI API key | | OPENROUTER_API_KEY | ❌* | - | OpenRouter API key | | RISK_PERCENTAGE | ❌ | 1.0 | Risk per trade as % of account | | MAX_POSITION_SIZE | ❌ | 1000 | Maximum position size in USD | | ENABLE_AI_SUGGESTIONS | ❌ | true | Enable/disable AI analysis |

*At least one AI provider key is required

Testing with Testnet

To test mucch without risking real funds:

HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz

Get testnet tokens from the Hyperliquid Testnet Faucet.

🎯 AI Strategy Details

mucch's AI analyzes multiple factors:

1. Trend Analysis: Identifies if the market is trending up, down, or sideways
2. Volatility Assessment: Measures price volatility using 24h high/low ranges
3. Volume Confirmation: Checks if volume supports the current price action
4. Risk/Reward Calculation: Suggests optimal entry, stop loss, and take profit levels

AI Decision Logic

• BUY Signal: AI confidence >70%, positive trend, good risk/reward
• SELL Signal: AI confidence >70%, negative trend, or risk mitigation
• HOLD Signal: Uncertainty or market conditions unclear

🛡️ Safety Features

• Conservative by Default: AI uses low temperature (0.3) for consistent decisions
• Confidence Threshold: Only acts on high-confidence signals (>70%)
• Risk Limits: Configurable risk percentage per trade
• Position Limits: Maximum position size controls
• Reduce-Only Orders: Safe position closing mechanism
• Read-Only Mode: Can run in monitor-only mode with ENABLE_AI_SUGGESTIONS=false

📚 Supported Assets

mucch supports 100+ cryptocurrencies including:

Major Assets: BTC, ETH, SOL, AVAX, BNB, ADA, DOT, LINK, UNI, MATIC

Trending: TRUMP, FARTCOIN, HYPE, AI16Z, AIXBT, ZEREBRO, VIRTUAL

DeFi: AAVE, CRV, MKR, COMP, UNI, SUSHI, GMX

And many more! See assets.ts for the complete list.

🔧 Advanced Usage

Custom Risk Management

RISK_PERCENTAGE=0.5  # Risk only 0.5% per trade
MAX_POSITION_SIZE=500  # Max $500 per position

Production Deployment

For running mucch 24/7:

# Using PM2
npm install -g pm2
pm2 start "npx mucch" --name mucch

# View logs
pm2 logs mucch

# Stop
pm2 stop mucch

⚠️ Disclaimers

1. Not Financial Advice: mucch is a tool, not financial advice. DYOR.
2. Risk of Loss: Trading perpetuals is highly risky. Only trade what you can afford to lose.
3. AI Limitations: AI analysis is not perfect. Always verify signals before trading.
4. Beta Software: mucch is in active development. Use at your own risk.
5. API Costs: OpenAI/OpenRouter API usage incurs costs. Monitor your usage.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE for details

🔗 Links

• Website: mucch.dev
• GitHub: github.com/magne/
• NPM: npmjs.com/package/mucch
• Twitter: @mucch
• Creator: @magne

📞 Support

• Open an issue on GitHub
• Follow @mucch for updates

🙏 Acknowledgments

• Built on Hyperliquid - The best perps DEX
• Powered by OpenAI GPT-4 and Anthropic Claude 3.5 Sonnet
• Terminal UI by blessed and blessed-contrib

Made with ⚡ by @magne

Trade smart. Trade with mucch.