A Telegram bot for Hyperliquid that monitors cryptocurrency trading positions, performs technical analysis (Wyckoff or LLM), and sends notifications for filled orders. Inspired by Freqtrade. Requires Python 3.10.

• 🔍 Monitor open positions for any wallet address
• 📊 Real-time notifications for filled orders
• 📈 Support for custom trading strategies
• ⏰ Periodic coin analysis
• 🐳 Docker support for easy deployment

1. Create a docker-compose.yml file:

services:
 hyperliquid_bot:
 image: sito/hyperliquid-telegram-bot:latest
 container_name: hyperliquid_bot
 environment:
 HTB_TOKEN: "<TELEGRAM BOT TOKEN>"
 HTB_CHAT_ID: "<TELEGRAM CHAT ID>"
 HTB_USER_WALLET: "<ADDRESS TO WATCH>"
 restart: unless-stopped

2. Run the bot:

docker compose up -d

1. Create a new bot through @BotFather:
   • Send /newbot command
   • Follow the setup procedure
   • Copy the provided bot token to HTB_TOKEN
2. Get your chat ID from @userinfobot:
   • The "Id" field is your HTB_CHAT_ID

• HTB_USER_WALLET: The wallet address to monitor (required)
• HTB_USER_VAULT: Vault address (optional, for vault monitoring)
• HTB_KEY_FILE: Path to private key file (optional, for order management)

The bot supports two different technical analysis modes that can be switched using the HTB_ANALYSIS_MODE environment variable:

The default mode uses traditional Wyckoff methodology to analyze market phases across multiple timeframes with volume pattern detection and chart generation.

You can toggle between Heikin Ashi and standard candles by setting:

environment:
 HTB_USE_HEIKIN_ASHI: "True"

When enabled, charts use Heikin Ashi candles for smoother visualization while calculations (indicators and level detection) still use the original OHLCV data.

An AI-powered mode that uses large language models to provide natural language analysis, confidence scoring, risk assessment, and price predictions with timeframes.

To use LLM mode:

1. Set HTB_ANALYSIS_MODE=llm
2. Set HTB_LLM_MAIN_MODEL (e.g., gpt-4) and HTB_LLM_FAST_MODEL (e.g., gpt-3.5-turbo)
3. Configure LiteLLM proxy settings via LITELLM_PROXY_API_BASE, LITELLM_PROXY_API_KEY, etc.
4. Optionally set HTB_ALWAYS_RUN_LLM_FILTER=True to always pre-filter before analysis

Example configuration for LLM mode:

environment:
 HTB_ANALYSIS_MODE: "llm"
 LITELLM_PROXY_API_BASE: "http://localhost:4000"
 LITELLM_PROXY_API_KEY: "sk-xxxxx"
 HTB_LLM_MAIN_MODEL: "gpt-4"
 HTB_LLM_FAST_MODEL: "gpt-3.5-turbo"

The bot supports custom trading strategies in the strategies/ directory:

• default_strategy: Basic trading strategy implementation
• etf_strategy: Strategy focused on ETF-like trading behavior that automatically allocates funds across top cryptocurrencies based on market capitalization
• fixed_token_strategy: Strategy that trades a fixed set of tokens with configurable parameters
• alpha_g_strategy: Strategy that detects strong multi-day surges/crashes and flags potential daily reversal signals

The ETF strategy can be configured using the following environment variables:

Example configuration in docker-compose.yml:

services:
 hyperliquid_bot:
 image: sito/hyperliquid-telegram-bot:latest
 container_name: hyperliquid_bot
 environment:
 HTB_TOKEN: "<TELEGRAM BOT TOKEN>"
 HTB_CHAT_ID: "<TELEGRAM CHAT ID>"
 HTB_USER_WALLET: "<ADDRESS TO WATCH>"
 HTB_ETF_STRATEGY_COINS_NUMBER: "3"
 HTB_ETF_STRATEGY_COINS_OFFSET: "2"
 HTB_ETF_STRATEGY_MIN_YEARLY_PERFORMANCE: "20.0"
 HTB_ETF_STRATEGY_LEVERAGE: "3"
 HTB_ETF_STRATEGY_EXCLUDED_SYMBOLS: "DOGE,SHIB"
 HTB_ETF_STRATEGY_CATEGORY: "layer-1"
 restart: unless-stopped

This configuration would create a portfolio that:

• Skips the top 2 coins (typically BTC and ETH)
• Includes the next 3 top layer-1 coins by market cap
• Only includes coins with >20% yearly performance
• Uses 3x leverage
• Excludes DOGE and SHIB from consideration

The Fixed Token strategy allows you to trade a specific set of tokens with configurable parameters. It can be configured using the following environment variables:

Example configuration in docker-compose.yml:

services:
 hyperliquid_bot:
 image: sito/hyperliquid-telegram-bot:latest
 container_name: hyperliquid_bot
 environment:
 HTB_TOKEN: "<TELEGRAM BOT TOKEN>"
 HTB_CHAT_ID: "<TELEGRAM CHAT ID>"
 HTB_USER_WALLET: "<ADDRESS TO WATCH>"
 HTB_FIXED_TOKEN_STRATEGY_TOKENS: "BTC,ETH,SOL"
 HTB_FIXED_TOKEN_STRATEGY_LEVERAGE: "3"
 HTB_FIXED_TOKEN_STRATEGY_MIN_YEARLY_PERFORMANCE: "20.0"
 restart: unless-stopped

This configuration would:

• Trade only BTC, ETH, and SOL
• Use 3x leverage for positions
• Only include tokens with >20% yearly performance

The AlphaG strategy analyzes top market-cap coins to detect strong multi-day moves and highlights potential intraday reversals. You can configure its sensitivity with the following environment variables:

Example configuration in docker-compose.yml:

services:
 hyperliquid_bot:
 image: sito/hyperliquid-telegram-bot:latest
 container_name: hyperliquid_bot
 environment:
 HTB_TOKEN: "<TELEGRAM BOT TOKEN>"
 HTB_CHAT_ID: "<TELEGRAM CHAT ID>"
 HTB_USER_WALLET: "<ADDRESS TO WATCH>"
 HTB_ALPHA_G_STRATEGY_LOOKBACK_DAYS: "3" # Number of full candles (days)
 HTB_ALPHA_G_STRATEGY_THRESHOLD_PCT: "20.0" # Surge/Crash threshold in % over lookback
 restart: unless-stopped

1. Clone the repository and install dependencies:

git clone <repo-url>
cd hyperliquid-telegram-bot
uv sync --frozen

2. Set environment variables:

export HTB_TOKEN="<TELEGRAM BOT TOKEN>"
export HTB_CHAT_ID="<TELEGRAM CHAT ID>"
export HTB_USER_WALLET="<ADDRESS TO WATCH>"

3. Run the bot:

uv run python hyperliquid_bot.py

4. Run tests:

uv run pytest -q

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines.

For major changes:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request