🚀 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:

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)
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
Close All Positions - Emergency exit all positions
- Lists all open positions
- Confirmation prompt
- Closes all positions at market price
- Shows success/failure status
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

"Insufficient margin" error
- Check your API Agent Wallet balance
- Ensure funds are transferred to API wallet
- Verify minimum order requirements ($10+)
"Account value $0.00"
- Fund your API Agent Wallet
- Check API key configuration
- Verify wallet address in .env
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

Fork the repository
Create a feature branch
Make your changes
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

📊 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

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

For detailed technical analysis, see hyperliquid_analysis.md.

⭐ Star this repository if you find it helpful!

Navigation Menu

Repository files navigation

🚀 Hyperliquid Trading Bot

✨ Features

🚀 Quick Start

1. Clone the Repository

2. Install Dependencies

3. Configure API Keys

4. Start Trading

📋 Prerequisites

🔧 Configuration

Environment Variables (.env)

Available API Functions

💡 Usage Examples

Trading Commands

Main Menu Functions

Trading Scenarios

📊 Trading Parameters

🛡️ Risk Management

🎯 Supported Assets

📈 Leverage Examples

🔧 Project Structure

🛡️ Safety Features

🚨 Troubleshooting

Common Issues

Getting Help

🤝 Contributing

How to Contribute

📄 License

⚠️ Disclaimer

🔗 Links

📊 Technical Details

Architecture Overview

Key Components

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
config.env.example		config.env.example
config.py		config.py
hyperliquid_analysis.md		hyperliquid_analysis.md
hyperliquid_client.py		hyperliquid_client.py
requirements.txt		requirements.txt
setup.py		setup.py
start_trading.py		start_trading.py
trade_usdc.py		trade_usdc.py
trading_bot.py		trading_bot.py

Latest commit

History

Folders and files

Repository files navigation

🚀 Hyperliquid Trading Bot

✨ Features

🚀 Quick Start

1. Clone the Repository

2. Install Dependencies

3. Configure API Keys

4. Start Trading

📋 Prerequisites

🔧 Configuration

Environment Variables (.env)

Available API Functions

💡 Usage Examples

Trading Commands

Main Menu Functions

Trading Scenarios

📊 Trading Parameters

🛡️ Risk Management

🎯 Supported Assets

📈 Leverage Examples

🔧 Project Structure

🛡️ Safety Features

🚨 Troubleshooting

Common Issues

Getting Help

🤝 Contributing

How to Contribute

📄 License

⚠️ Disclaimer

🔗 Links

📊 Technical Details

Architecture Overview

Key Components

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages