Documentation

Everything you need to copy the smartest traders on Hyperliquid, without ever giving up custody of your funds.

01 What it is

Whales Sonar mirrors the live positions of selected top Hyperliquid traders (we call them whales) into your own account, in about one second. When a whale opens, resizes, or closes a position, your bot does the same, scaled to your capital.

The copy is strictly proportional: if a whale puts 10% of her account into a position at 5x leverage, your bot puts 10% of yours at 5x. You hold her whole book, scaled to your size, at her leverage. You always see exactly what the bot holds, its P&L, and every action it took.

You keep full custody the entire time: your funds never leave your own Hyperliquid account (see Security).

02 Getting started

Connect your wallet (MetaMask, Rabby, or WalletConnect on mobile). No email, no password.
Have a Hyperliquid account with USDC. Deposit on app.hyperliquid.xyz (bridge USDC from Arbitrum), and set it to Unified.
Authorize an agent (API) wallet with one signature. This key can trade but never withdraw (see The agent wallet).
Pick a whale from the Top 50 and choose how much of your equity to deploy.
Start. The bot mirrors her live. Track it in your Portfolio.

Not ready to fund? Try the free simulator first, no wallet needed.

03 Free simulator

The simulator lets you test the whole thing with zero risk and no wallet. Pick whales, set a virtual budget (up to $10,000 total to spread across them), and watch the copy play out live, marked with realistic Hyperliquid and Whales Sonar fees and order-book slippage. It is the honest way to evaluate the strategy before funding anything.

04 Unified vs classic account

Hyperliquid accounts come in two modes, and it matters for copying:

Unified (recommended). Spot and perp share one collateral pool. Your USDC sitting in spot automatically backs your perp positions and tokenized-stock (xyz) positions.
Classic. Spot and perp are separate pots. The bot cannot use your spot USDC as margin, and builder-dex orders (tokenized stocks) get rejected with "insufficient margin", even though the funds are there.

Switch to Unified in your Hyperliquid settings before you start copying.

Good to know After you switch modes, Hyperliquid caches the old mode for about 15 minutes. If a bot launched just before the switch looks empty, Stop and Start it once the cache clears.

05 The agent (API) wallet

To trade for you without ever touching your money, you authorize an agent wallet (Hyperliquid's "API wallet"). By Hyperliquid's own design, this key can place and cancel orders but cannot withdraw or transfer your funds. We generate it, hold it encrypted, and it only ever signs orders for your account.

You can revoke it any time on Hyperliquid or from Settings, which immediately stops live trading on that account.

Renewal Agent keys expire (about 180 days on Hyperliquid). We show a countdown and prompt you to renew well before expiry, so copying never silently stops.

06 Sizing & faithful copy

Your position size = your equity × conviction, where conviction = a position's value divided by the whale's total account value. So you mirror her at the same fraction of wealth and the same leverage.

This always fits when her account is solvent, because your margin ratio equals hers, so margin is never the reason a faithful copy cannot be placed. Two things can make you look like you drift, neither a choice: a position that lost money shrinks your equity (you are just down on her trade), and a coin the bot temporarily cannot re-copy.

The one real limit Hyperliquid enforces a minimum order size (about $11). If a whale's position, scaled to your capital, falls below it, the bot cannot copy it without over-sizing, so it skips it and tells you. Add funds to bring it above the minimum. We never silently up-size beyond the faithful copy.

07 Fees

One transparent, on-chain fee: a Hyperliquid builder fee of 0.045% (4.5 bps) on the notional of each trade the bot executes for you, the same order of magnitude as Hyperliquid's own taker fee. No subscription, no deposit fee, no profit share, no withdrawal fee.

What you pay per trade is Hyperliquid's own fee plus our builder fee:

Fee	Rate
Hyperliquid taker (base)	0.045%
Hyperliquid maker (base)	0.015%
Whales Sonar builder	0.045%

Copy orders fill immediately so they track the whale within about a second, which makes them taker orders (see maker/taker). Your total cost therefore scales with how often the whale trades: an active whale means more fills, so more fee. It is one reason our scoring favors whales that are not high-frequency churners.

You authorize the builder fee once, by signing with your wallet. It is capped by that signature and can never be raised without you signing again.

08 Risk controls

Two safety nets on your own account, each optional and independent:

Stop-loss. If your account value falls to a level you set, the bot closes every position and pauses itself.
Take-profit. If it reaches a level you set, same, gains locked, bot paused.

And two optional whale circuit breakers that watch the whale herself, not your account:

Whale drop %. If her account falls more than your threshold below its recent peak (a big loss or a large withdrawal), your bot closes everything and pauses.
Whale minimum equity. If her account falls under an absolute floor you set, same reaction.

Soft stops In a very fast market the exit can fill slightly past your level, like any stop order.

09 Whale scoring & tiers

Every trader on Hyperliquid is scored 0 to 100 on their real, on-chain perps track record, tuned for a roughly one-month copy horizon: consistency (how often they are up), loss control (shallow drawdowns), recent momentum, steadiness of the curve, risk-adjusted return, and the right amount of activity (not dormant, not high-frequency churn).

Tiers judge outcomes, never trading style:

A / Proven. Statistically proven skill (beyond the luck of tens of thousands of wallets) and verified trade-level quality. The hardest badge to earn.
B / Emerging. Strong, but not yet fully proven.
C / Watch. Promising, at least one quality gate not yet met. Each card says exactly what is missing.

Not a promise A high score is information, not a guarantee. Past performance does not predict future results, and copying leveraged perps can lose the entirety of your funds.

10 Security

Non-custodial by design, not by promise:

Your funds never leave your own Hyperliquid account.
The agent key can trade but cannot withdraw or transfer, period.
You can revoke it any time, on Hyperliquid or in Settings.
Keys are encrypted at rest (envelope encryption via a cloud key-management service) and never shown again, not even to you.
No email anywhere. You are identified only by your wallet; alerts are delivered by web push.

11 Troubleshooting

My bot launched with 0 positions

The account had nothing deployable at launch, or was still in Classic mode. Fund it (or switch to Unified), then Stop and Start the bot to re-bootstrap.

"This position was too small to copy"

Scaled to your capital, that coin fell below Hyperliquid's minimum order size (about $11). Add funds and it will be copied on the next move (see Sizing).

The amounts do not match my Hyperliquid app

A unified account is split in Hyperliquid's own interface into a main account (spot + main perp) and each builder dex (for example xyz tokenized stocks), shown as separate views. We display the true total (the sum of all of them), which is what the "on-chain" link on each wallet shows on the explorer. Reading a single Hyperliquid tab under-shows; adding the tabs yourself over-counts.

Copying seems to have stopped

Check that your agent key has not expired. Settings shows a countdown and a one-click renew.

12 Glossary

Maker / Taker: A maker order rests in the order book and waits (cheaper fee). A taker order fills immediately against what is already there (instant, higher fee). Copy orders are takers, to track the whale fast.
Notional: The full market value of a position (size times price), before leverage.
Leverage: How much position you control per dollar of margin. 5x means $5 of position per $1 of margin.
uPnL (unrealized P&L): The paper gain or loss on positions that are still open, marked to the current price.
Unified account: The Hyperliquid mode where your spot USDC backs your perp and builder-dex positions from a single pool.
Builder dex (HIP-3): A market deployed on top of Hyperliquid (for example xyz, tokenized stocks), with its own isolated collateral.
Conviction: A position's value as a fraction of the whale's total account, used to size your copy proportionally.

More questions? See the FAQ or the Terms & risk disclosure. Nothing here is financial advice.