Hyperliquid Whale Copy Trading — Mirror Pro Trades Instantly

MagicTradeBot's Hyperliquid Whale Tracker lets you follow wallet-level activity on Hyperliquid and other wallet-based exchanges. Track any wallet address, receive notifications, and optionally mirror (place/close) trades automatically with flexible safety and filtering controls.

Overview

The Hyperliquid Whale Tracker watches wallet addresses (whales) and reacts when those wallets open or close positions. It supports two primary modes:

  • Signal-only mode — broadcast whale events to your notification channels (Telegram, Discord, WhatsApp, etc.).
  • Mirror mode — automatically place mirrored orders and close them when the whale closes its position.

The feature is entirely configurable from tradesettings.yaml and can be enabled per-bot instance. By default it is disabled.

Configuration

Add or update the HyperLiquidWhaleTracker section inside your tradesettings.yaml (or appsettings.yaml variant if you centralize settings). Example: 

HyperLiquidWhaleTracker:
  is_enabled: false
  tracking_addresses:
    - "0x2aB3...Ff12"            # Add one or more whale wallet addresses
    - "0x1cD4...Aa77"
  place_order: false             # true = auto-place mirrored orders, false = signal-only
  order_amount: 100.0            # Amount in BaseCurrency per mirrored trade
  leverage: 3                    # Leverage to use for mirrored trades (if applicable)
  broadcast_signals: true        # true = send notifications when whale opens/closes trades
  max_open_per_whale: 2          # Max mirrored open trades per tracked whale (safety)
  slippage_tolerance_percent: 0.5 # Max acceptable slippage when placing mirrored orders
  follow_partial_fills: true     # If true, bot mirrors partial fills proportionally
  close_on_whale_close: true     # Close mirrored order when whale closes its position
  include_liquidations: false    # If true, will mirror liquidations (not recommended)
  only_follow_buy: false         # If true, follow buys only
  only_follow_sell: false        # If true, follow sells only
  min_whale_order_value: 50.0    # Min order value (BaseCurrency) for tracking/mirroring
  cooldown_seconds: 30           # Seconds to wait between processing events for same whale

Field descriptions

  • is_enabled — Enable/disable the whale tracker (default: false).
  • tracking_addresses — List of wallet addresses to follow. No hard limit; add as many as you want but mind resource usage.
  • place_order — When true, the bot will attempt to place mirrored orders automatically. When false, it only broadcasts signals.
  • order_amount — Size of the mirrored order in your base currency (e.g., USDT) per trade. Consider using money-management sizing for production.
  • leverage — Leverage to open mirrored futures positions (only if the exchange supports leverage).
  • broadcast_signals — Send formatted messages to the configured broadcast channels.
  • max_open_per_whale — Safety limit to avoid over-exposure to a single whale.
  • slippage_tolerance_percent — Maximum acceptable slippage when placing orders.
  • follow_partial_fills — If a whale's order partially fills, the bot mirrors the same filled ratio.
  • close_on_whale_close — Close mirrored orders when the whale closes its position.
  • include_liquidations — Mirror liquidations only if you understand the extreme risks.
  • only_follow_buy / only_follow_sell — Filters to follow only buys or only sells.
  • min_whale_order_value — Ignore tiny whale orders below this threshold.
  • cooldown_seconds — Prevents event spam by spacing processing per whale.

How it works (technical flow)

  1. Event Source: Bot subscribes to Hyperliquid wallet events (or polls the blockchain/API) for the configured addresses.
  2. Event Detection: On detection of a new open/close order event, bot validates it against filters (min value, action type, cooldown).
  3. Decision: If place_order = true, the bot creates a mirrored order request using your configured exchange credentials, including leverage and size rules. If false, it builds a broadcast message only.
  4. Execution: Attempts to place the order, accounting for slippage tolerance and available balance. If follow_partial_fills = true, the bot adjusts mirrored order quantities accordingly.
  5. Lifecycle: The bot monitors the mirrored order status and, if close_on_whale_close = true, will close the mirrored order when the whale closes theirs.
  6. Logging & Alerts: All events and actions are logged (see Logging & Monitoring). Notifications are broadcast if configured.

Prerequisites & Permissions

  • Working MagicTradeBot instance with valid license and tradesettings.yaml configured.
  • Exchange API keys with trade permissions (if place_order is enabled). For Hyperliquid wallet-based actions you may also need a private key — never store private keys in plain text (use environment variables).
  • Stable internet connection and adequate rate-limit settings in appsettings.yaml to avoid API bans.

Security considerations

  • Never hardcode private keys or API secrets in repository files. Use environment variables or OS-level secrets management.
  • Limit API key permissions to only what is required (trading, no withdrawals ideally).
  • Test thoroughly in DemoMode before enabling live mirrored orders.
  • Set conservative defaults: max_open_per_whale, slippage_tolerance_percent, and min_whale_order_value.
  • Enable logging and incident alerting (Sentry, PagerDuty) to be notified of execution errors or unexpected behavior.

Notification & Broadcast Examples

When broadcast_signals is true, the bot sends a formatted message. Example templates below:

Telegram / Discord (text)


[Hyperliquid Whale] NEW ORDER
Whale: 0x2aB3...Ff12
Action: BUY (Long)
Symbol: BTCUSDT
Size: 0.5 BTC (~25000 USDT)
Leverage: 3x
Time: 2025-10-16T12:34:56Z
Mirrored: yes (order id: M-123456)   # or "Mirrored: no" if place_order=false

WhatsApp / Webhook (JSON payload)

{
  "type": "hyperliquid.whale.event",
  "whale_address": "0x2aB3...Ff12",
  "action": "open",
  "side": "buy",
  "symbol": "BTCUSDT",
  "size": 0.5,
  "notional": 25000,
  "leverage": 3,
  "mirrored": true,
  "mirrored_order_id": "M-123456",
  "timestamp": "2025-10-16T12:34:56Z"
}

Testing & Demo Mode

  • Always test with DemoMode: true or using exchange testnets first.
  • Set place_order: false to verify event detection and broadcast formatting without executing trades.
  • Use small order_amount during live testing, and monitor logs in completedorders.yaml and terminal output.

Operational Best Practices

  • Use max_open_per_whale to avoid over-exposure to one whale's sequence of trades.
  • Enable cooldown_seconds to reduce duplicate processing if whales split orders into many micro-orders.
  • Prefer signal-only during volatile market conditions or when you can't ensure fast execution/slippage control.
  • If mirroring with leverage, ensure you have margin and fail-safes (global forced close thresholds).
  • Log every incoming event and mirrored action for auditability and backtesting.

Logging & Monitoring

Recommended logging/monitoring to enable in appsettings.yaml or your bot config:

  • Terminal logs for real-time troubleshooting.
  • completedorders.yaml — persisted completed mirrored trades for backtest and PnL.
  • Optional remote logging: Sentry, Loki, LogDNA, DataDog for alerts and historical audit logs.
  • Prometheus metrics for open positions count, mirrored orders count, and error rates.

Error handling & retries

  • On order placement failure, bot retries up to 3 times with exponential backoff (configurable).
  • If slippage exceeds slippage_tolerance_percent, order is canceled and a warning is emitted.
  • If mirrored order cannot be placed due to insufficient balance, bot broadcasts a warning and skips mirroring.

Limitations & Risks

  • Following wallets does not guarantee profit — whales can be market makers, insiders, or perform short-term manipulations.
  • Mirroring liquidations or high-leverage whale moves can amplify losses.
  • Execution latency and slippage can cause different trade outcomes vs. the whale.
  • Respect exchange API rate limits — tracking many whales increases API calls and resource usage.

FAQ

Q: Can I track any wallet address?

A: Yes — add any public wallet address to tracking_addresses. The bot will attempt to detect open/close events associated with that address.

Q: Will the bot replicate position sizes exactly?

A: Not necessarily. The bot uses order_amount as the mirrored trade size (or proportionally mirrors partial fills if enabled). You can implement percent-based sizing in advanced money-management configuration.

Q: What if a whale splits an order into many micro-orders?

A: Use cooldown_seconds and follow_partial_fills to control how split orders are mirrored and to avoid over-exposure.

Getting started checklist

  1. Enable the tracker: set is_enabled: true in tradesettings.yaml.
  2. Add whale addresses to tracking_addresses.
  3. Set place_order = false initially to verify events and notifications.
  4. Verify broadcasts are delivered to Telegram/Discord/WhatsApp.
  5. Switch to place_order: true once comfortable, keep DemoMode = true until live verification is complete.
  6. Monitor logs and set alerts for placement errors, slippage, and insufficient balance events.

Complete example snippet (copy into tradesettings.yaml)

HyperLiquidWhaleTracker:
  is_enabled: true
  tracking_addresses:
    - "0x2aB3...Ff12"
    - "0x1cD4...Aa77"
  place_order: true
  order_amount: 150.0
  leverage: 3
  broadcast_signals: true
  max_open_per_whale: 2
  slippage_tolerance_percent: 0.5
  follow_partial_fills: true
  close_on_whale_close: true
  include_liquidations: false
  only_follow_buy: false
  only_follow_sell: false
  min_whale_order_value: 100.0
  cooldown_seconds: 60

Tracking and mirroring public wallet activity is technically feasible, but you should ensure compliance with local laws, exchange terms, and ethical trading practices. MagicTradeBot provides the tools — it is your responsibility to use them legally and responsibly.

Support & Troubleshooting

If you encounter issues:

  • Check terminal logs and completedorders.yaml for errors.
  • Verify API keys and permissions (trading allowed, withdrawals disabled).
  • Confirm environment variables override file settings if used for secrets.
  • Contact support via your MagicTradeBot dashboard or consult the full Configuration documentation.

📎 Related Topics