Hyperliquid Whale Tracker User Guide

πŸ“‘ Table of Contents

πŸ“– 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

  1. Position Detection: System detects new whale position
  2. Symbol Matching: Finds corresponding trading pair on your exchange
  3. Order Validation: Checks whale order limits and bot availability
  4. Order Placement: Places market order with your configured settings
  5. 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

  1. Position Registration: After placing copy trade, position is added to monitoring
  2. Continuous Checking: Every 5 minutes, system checks whale's current positions
  3. Close Detection: Identifies when whale position size decreases or disappears
  4. 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"

πŸ“Ž Related Topics