Hyperliquid Whale Tracker User Guide

📑 Table of Contents

Overview
Configuration
How It Works
Broadcasting Signals
Automatic Copy Trading
Position Monitoring
Safety Features
Troubleshooting

📖 Overview

The Hyperliquid Whale Tracker is an advanced feature that monitors whale wallet activities on the Hyperliquid exchange and enables automated copy trading. When a tracked whale opens a new position, the system can automatically broadcast signals to Discord/Telegram and/or place mirrored trades on your account.

🔍 Real-Time Detection

Monitors whale positions every 5 minutes and detects new positions instantly.

📢 Multi-Platform Alerts

Broadcasts signals to Discord, Telegram, and WhatsApp with rich formatting.

🤖 Auto Copy Trading

Automatically mirrors whale positions with your custom settings and risk parameters.

🎯 Smart Close Tracking

Automatically closes your position when the whale closes theirs.

⚙️ Configuration

Basic Settings

Located in your configuration file under HyperLiquidWhaleTracker:

HyperLiquidWhaleTracker:
  is_enabled: true                 # Enable/disable whale tracking
  tracking_addresses:              # List of whale wallet addresses
    - "0x2ea18c23f72a4b6172c55b411823cdc5335923f4"
    - "0xb317d2bc2d3d2df5fa441b5bae0ab9d8b07283ae"
    - "0x9458f423df6569f053358ee9906613cd69c1ec04"
    # Add more addresses...
  
  place_order: false               # Auto-place mirrored orders
  broadcast_signals: true          # Broadcast to messaging platforms
  max_orders_per_whale: 2          # Max concurrent orders per whale
                

Messaging Platform Configuration

broadcast:
  # Discord
  discord_webhook_url: "https://discord.com/api/webhooks/YOUR_WEBHOOK"
  
  # Telegram
  telegram_bot_token: "YOUR_BOT_TOKEN"
  telegram_chat_id: "YOUR_CHAT_ID"
  
  # WhatsApp (optional)
  whatsapp_token: "YOUR_TOKEN"
  whatsapp_phone_id: "YOUR_PHONE_ID"
                

Trade Settings

general:
  initial_trade_amount: 100        # USD amount per trade
  leverage: 10                     # Leverage multiplier
  demo_mode: false                 # Test without real trades

sltp_settings:
  take_profit_percent: 5.0         # Take profit %
  stop_loss_percent: 2.0           # Stop loss %
                

🔧 How It Works

Detection Process

1Initial Scan

On first run, the system registers all existing whale positions without broadcasting (prevents spam).

2Continuous Monitoring

Every 5 minutes, the system:

Fetches current positions for each tracked whale
Compares with previously seen positions
Detects NEW positions that weren't there before

3Position Identification

A position is considered NEW when:

The coin wasn't in the whale's portfolio during the last check
The system hasn't broadcast this position before

4Action Execution

For each new position:

Broadcasts signal to configured platforms (if enabled)
Places copy trade order (if enabled)
Adds position to monitoring for auto-close tracking

Whale Position Data Tracked

Data Point	Description
Coin	Trading pair (e.g., BTC, ETH, SOL)
Side	Long or Short position
Size	Position size in contracts
Entry Price	Whale's entry price
Leverage	Position leverage
Unrealized PnL	Current profit/loss
Liquidation Price	Risk threshold

📢 Broadcasting Signals

Enabling Broadcasts

Set broadcast_signals: true in your configuration to receive notifications when whales open positions.

Discord Notifications

Rich Embed Format

Color-coded (Green for LONG, Red for SHORT)
Organized fields with all position details
Clickable link to whale's portfolio
Timestamp for tracking

🐋 Whale Alert: Whale #1 Whale #1 opened a LONG position on BTC 📊 Position Details Coin: BTC Side: LONG 📈 Size: 50.5 Leverage: 20x 💰 Price Info Entry Price: $65,432.10 Unrealized PnL: $-125.50 ⏰ Timing Position Opened: 2025-01-15 14:30:00 UTC Detected: 14:35:00

Telegram Notifications

Markdown Format

Clean, readable text format
Monospace code blocks for data
Direct tracking link
Mobile-friendly layout

🐋 *WHALE ALERT* 🟢 *Whale #1* opened *LONG* position *Position Details:* ``` Coin : BTC Side : LONG Size : 50.5 Entry Price : $65,432.10 Leverage : 20x Unreal. PnL : $-125.50 Liquidation : $60,123.45 ``` *Timing:* ``` Opened : 2025-01-15 14:30:00 UTC Detected : 2025-01-15 14:35:00 ``` 🔗 [Track on CoinGlass] _Whale: 0x2ea18c23..._

Platform Selection

The system broadcasts to all configured platforms with valid credentials. Platforms without credentials are automatically skipped:

Discord: Requires discord_webhook_url
Telegram: Requires both telegram_bot_token and telegram_chat_id
WhatsApp: Requires whatsapp_token and whatsapp_phone_id

🤖 Automatic Copy Trading

Enabling Auto-Trading

Set place_order: true to automatically mirror whale positions.

How Copy Trading Works

Position Detection: System detects new whale position
Symbol Matching: Finds corresponding trading pair on your exchange
Order Validation: Checks whale order limits and bot availability
Order Placement: Places market order with your configured settings
Monitoring: Adds position to close-monitoring system

⚠️ Important: Your Settings, Not Whale's

Your copy trades use YOUR settings, not the whale's:

Your position size (not whale's)
Your leverage (not whale's)
Your TP/SL percentages
Your risk management rules

Example: Whale opens 100 BTC LONG at 20x leverage → Your copy trade: $100 BTC LONG at 10x leverage (your settings)

Exchange Compatibility

The system automatically adapts symbols for your exchange:

Exchange	Whale Symbol	Your Symbol
Binance	BTC	BTCUSDT
OKX	BTC	BTC-USDT-SWAP
Bybit	BTC	BTCUSDT
Bitget	BTC	BTCUSDT
HyperLiquid	BTC	BTC (no change)

Order Placement Logic

IF new whale position detected:
  → Check if broadcast_signals enabled → Send notifications
  → Check if place_order enabled:
    → Verify whale order limit not exceeded
    → Find matching active trading pair
    → Check bot has no running orders (avoid conflicts)
    → Calculate order size from YOUR settings
    → Place market order with YOUR TP/SL
    → Save to opentrades.yaml
    → Add to monitoring for auto-close
                

👁️ Position Monitoring & Auto-Close

Automatic Close Tracking

When you copy a whale trade, the system monitors the whale's position continuously. If the whale closes their position, your copy trade automatically closes too.

How It Works

Position Registration: After placing copy trade, position is added to monitoring
Continuous Checking: Every 5 minutes, system checks whale's current positions
Close Detection: Identifies when whale position size decreases or disappears
Auto-Close Execution: Immediately closes your corresponding position

Close Scenarios

Full Close (100%)

Whale: Closes entire position

Your Trade: Automatically closes 100% of position

Result: Trade moved to completed, running_orders cleared

Partial Close

Whale: Reduces position size (e.g., 50% close)

Your Trade: Closes matching percentage

Result: Trade updated with new quantities

State Management

# Before Close
running_orders:
  - order_id: "12345"
    symbol: "BTCUSDT"
    status: "Active"
    whale_address: "0x2ea..."

# After Close
running_orders: null  # Cleared, ready for next trade
completed_trades:
  - order_id: "12345"
    status: "Closed"
    realized_pnl: 45.30
    close_reason: "Whale Whale #1 closed BTC position"
                

🛡️ Safety Features

Order Limits

Per-Whale Limit (`max_orders_per_whale`)

Default: 2 concurrent orders per whale
Configurable: Set any number (1-10 recommended)
Purpose: Prevents overexposure to single whale

Example: Whale #1 has 2 active positions → New position detected → System checks: 2/2 limit reached → Order skipped: "Whale order limit reached"

Demo Mode

Test the system without risking real capital:

general:
  demo_mode: true  # Simulates orders without execution
                    

In Demo Mode:

✅ Detects whale positions
✅ Broadcasts signals
✅ Logs order details
❌ No real orders placed
❌ No exchange API calls

Bot Conflict Prevention

Before placing copy trade:

Checks if target bot has running orders
Skips order if bot is already trading
Prevents multiple simultaneous positions on same symbol

Position Validation

Every order is validated for:

Valid Symbol: Must exist on your exchange
Current Price: Must be retrievable (> 0)
Quantity Calculation: Must meet exchange minimums
Leverage Limits: Within exchange-allowed range

🔧 Troubleshooting

Common Issues

❌ "No whale addresses configured"

Problem: tracking_addresses list is empty

Solution:

HyperLiquidWhaleTracker:
  tracking_addresses:
    - "0xYOUR_WHALE_ADDRESS_HERE" 