🚀 Hyperliquid Trading Bot

A powerful, user-friendly trading bot for Hyperliquid with USDC-based trading, leverage support, and comprehensive risk management.

✨ Features

• 🎯 USDC-based Trading: Trade with easy-to-understand USDC amounts
• ⚡ Leverage Support: 1x to 10x leverage with automatic position sizing
• 🖥️ Interactive Interface: User-friendly parameter configuration
• 🛡️ Risk Management: Built-in stop loss, take profit, and position limits
• 🚀 Market Orders: Fast execution with market price orders
• 📊 Position Management: Open, close, and monitor positions
• 🔄 Real-time Updates: Live position monitoring and PnL tracking

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/your-username/hyperliquid_trader.git
cd hyperliquid_trader

2. Install Dependencies

# Option 1: Use setup script (recommended)
python setup.py

# Option 2: Manual installation
pip install -r requirements.txt

3. Configure API Keys

# Copy environment template
cp config.env.example .env

# Edit .env with your API keys
# Get API keys from: https://app.hyperliquid.xyz/API

4. Start Trading

# Quick start (recommended)
python start_trading.py

# Direct trading interface
python trade_usdc.py

📋 Prerequisites

• Python 3.8 or higher
• Hyperliquid account
• API Agent Wallet (get from Hyperliquid API)
• Minimum $10 in your API wallet

🔧 Configuration

Environment Variables (.env)

# Hyperliquid API Configuration
HYPERLIQUID_API_KEY=your_api_key_here
HYPERLIQUID_SECRET_KEY=your_secret_key_here
HYPERLIQUID_BASE_URL=https://api.hyperliquid.xyz

# Trading Configuration
DEFAULT_SYMBOL=ETH
DEFAULT_SIDE=long
DEFAULT_SIZE=0.1
DEFAULT_LEVERAGE=1.0

# Risk Management
MAX_POSITION_SIZE=1.0
STOP_LOSS_PERCENTAGE=5.0
TAKE_PROFIT_PERCENTAGE=10.0

# Monitoring
MONITORING_INTERVAL=5
ENABLE_WEBSOCKET=true

# Advanced Risk Management
MAX_DAILY_LOSS=100.0
MAX_POSITION_PERCENTAGE=0.1
MAX_LEVERAGE=10.0
EMERGENCY_STOP_LOSS=20.0

Available API Functions

The bot provides comprehensive API access:

Account Information:

• get_account_value() - Get total account value in USD
• get_user_state() - Get complete user account state
• get_position(coin) - Get position for specific coin
• get_available_balance() - Get available trading balance

Market Data:

• get_l2_book(coin) - Get order book data
• get_candles(coin, interval, start_time, end_time) - Historical price data
• get_trades(coin) - Recent trades for a coin
• get_meta() - Exchange metadata and asset information

Trading Operations:

• place_market_order(coin, is_buy, sz, leverage) - Execute market orders
• place_order(coin, is_buy, sz, limit_px, leverage) - Place limit orders
• update_leverage(coin, leverage) - Update position leverage
• cancel_order(oid) - Cancel specific order
• cancel_all_orders(coin) - Cancel all orders

Position Management:

• buy(usdc_amount, use_usdc) - Buy with USDC amount
• sell(usdc_amount, use_usdc) - Sell with USDC amount
• close_position() - Close specific position
• close_all_positions() - Emergency close all positions

💡 Usage Examples

Trading Commands

# Interactive trading interface
python trade_usdc.py

# Show help and options
python trade_usdc.py help

# Quick start launcher
python start_trading.py

Main Menu Functions

The trading interface provides 4 main options:

1. Check Positions - View all open positions and PnL

   • Shows account value and balance
   • Displays position details (symbol, side, size, entry price, leverage)
   • Shows unrealized PnL for each position
   • Overall account status (profit/loss)

2. Place Trade - Execute new trades

   • Interactive parameter configuration
   • Symbol selection (ETH, BTC, SOL, AVAX)
   • Position side (long/short/close)
   • USDC amount input
   • Leverage setting (1x-10x)
   • Risk management parameters

3. Close All Positions - Emergency exit all positions

   • Lists all open positions
   • Confirmation prompt
   • Closes all positions at market price
   • Shows success/failure status

4. Exit - Close the interface

Trading Scenarios

• Long ETH: $100 with 3x leverage = $300 position
• Short BTC: $50 with 2x leverage = $100 position
• Close Position: Market price exit
• Close All: Emergency exit all positions

📊 Trading Parameters

Parameter	Description	Example
Symbol	Trading pair	ETH, BTC, SOL, AVAX
Side	Position direction	long, short, close
USDC Amount	Investment amount	$100
Leverage	Position multiplier	3x = 3x position size
Stop Loss	Risk management	5% below entry
Take Profit	Profit target	10% above entry

🛡️ Risk Management

• Stop Loss: Automatic exit at specified loss percentage
• Take Profit: Automatic exit at specified profit percentage
• Position Limits: Maximum position size controls
• Daily Limits: Maximum daily loss protection
• Emergency Stop: Circuit breaker for extreme losses

🎯 Supported Assets

• ETH (Ethereum)
• BTC (Bitcoin)
• SOL (Solana)
• AVAX (Avalanche)
• And more...

📈 Leverage Examples

Investment	Leverage	Position Value
$100	1x	$100
$100	3x	$300
$100	5x	$500
$100	10x	$1,000

🔧 Project Structure

hyperliquid_trader/
├── 📁 .github/                 # GitHub workflows and templates
├── 📄 trade_usdc.py            # Main trading interface
├── 📄 hyperliquid_client.py   # API client (hybrid SDK + direct API)
├── 📄 trading_bot.py          # Trading logic and risk management
├── 📄 config.py               # Configuration management
├── 📄 start_trading.py        # Quick start launcher
├── 📄 setup.py               # Setup and installation script
├── 📄 requirements.txt       # Python dependencies
├── 📄 config.env.example     # Environment template
├── 📄 .gitignore            # Git ignore rules
├── 📄 LICENSE               # MIT License
├── 📄 CONTRIBUTING.md       # Contribution guidelines
├── 📄 QUICK_START.md        # Quick start guide
├── 📄 hyperliquid_analysis.md # Technical analysis
└── 📄 README.md             # This file

🛡️ Safety Features

• ✅ Input Validation: All parameters validated
• ✅ Balance Checks: Prevents over-trading
• ✅ Error Handling: Graceful error recovery
• ✅ Position Limits: Maximum position controls
• ✅ Risk Controls: Stop loss and take profit
• ✅ Account Value Monitoring: Real-time account value tracking
• ✅ Position Size Validation: Prevents oversized positions
• ✅ Leverage Limits: Maximum leverage controls (1x-10x)
• ✅ Emergency Stop: Circuit breaker for extreme losses
• ✅ Confirmation Prompts: Trade confirmation before execution

🚨 Troubleshooting

Common Issues

1. "Insufficient margin" error

   • Check your API Agent Wallet balance
   • Ensure funds are transferred to API wallet
   • Verify minimum order requirements ($10+)

2. "Account value $0.00"

   • Fund your API Agent Wallet
   • Check API key configuration
   • Verify wallet address in .env

3. Leverage not working

   • Fixed in latest version
   • Position size now correctly calculated with leverage

Getting Help

• Check your .env configuration
• Verify API keys are correct
• Ensure sufficient account balance
• Check minimum order requirements

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

Trading cryptocurrencies involves substantial risk of loss. This software is provided as-is without warranty. Use responsibly and never risk more than you can afford to lose.

🔗 Links

• Hyperliquid Exchange
• Hyperliquid API Documentation
• Get API Keys

📊 Technical Details

This bot uses a hybrid approach:

• Official Hyperliquid Python SDK for trading operations
• Direct API calls for market data and account information
• Comprehensive risk management with stop loss and take profit
• Real-time position monitoring and PnL tracking

Architecture Overview

• Hybrid API Client: Combines SDK and direct API calls
• Trading Bot: Handles trading logic and risk management
• Interactive Interface: User-friendly parameter configuration
• Configuration Management: Environment-based settings
• Setup Automation: Automated dependency installation

Key Components

1. HyperliquidClient: API client with hybrid approach
2. TradingBot: Core trading logic and risk management
3. TradingConfig: Configuration management
4. Interactive Interface: User-friendly trading interface
5. Setup Scripts: Automated installation and configuration

For detailed technical analysis, see hyperliquid_analysis.md.

---

⭐ Star this repository if you find it helpful!