BlogDeveloper

How to Build a Hyperliquid Copy Trading Bot

Learn how to build a Hyperliquid copy trading bot on Hyperliquid with the Hyperliquid API.

HydromancerTeam
How to Build a Hyperliquid Copy Trading Bot

What if your account could trade alongside a Hyperliquid trader who keeps getting it right, automatically?

That's what a copy trading bot does. It follows the trader's wallet, the "leader", and mirrors each trade in your account at a smaller size.

Hyperliquid copy trading compared with a CEX

Copy trading means something different on Hyperliquid than on a centralized exchange (CEX) such as Binance or Bybit:

On Hyperliquid On a centralized exchange
Who you can copyAny wallet: every
trade and position
is public on-chain		Usually only traders
in the exchange's
copy-trading program
Checking a leader firstPull their trades and
PnL history yourself
from the API		Usually the stats the
exchange chooses to show
Where your money sitsYour own account, under
your own sizing rules		Usually an account
the exchange holds
your funds in
Building it for othersBuilder codes earn up to
0.1% on the perp fills
you place for users		The exchange
runs the program

Hyperliquid also has a built-in way to follow a trader: vaults. In a user vault, you deposit into the leader's vault, they trade it, and they keep 10% of the profits. A copy bot works the other way around. Your money stays in your account, and you set the size, caps and leverage of every copy.

The goal is a bot that keeps up with the leader. To get there, we'll look at:

  1. Why the usual ways of copy trading on Hyperliquid fall short.
  2. The limits of Hyperliquid's API for following many wallets, and how Hydromancer's API lifts them.
  3. How to build a copy bot step by step: stream the leader's trades, size each copy, and catch missed trades.

We'll use a mini example: Hydromancer supplies the leader's data, and Hyperliquid's SDK places the orders. It's one use case to adapt, not a production template. Nothing here is financial advice: copying a trader copies their losses too. Prices are a snapshot from when we tested.

How most people copy trade on Hyperliquid, and why it falls short

Approach How it works Where it breaks
Copy-trading apps and chat botsPaste a wallet
in, set a size		You often can't see
or change the sizing
and risk logic
Polling the public APIAsk for the leader's
positions or fills
every few seconds		Copies arrive up to
a polling interval
late, and polling
eats your rate limit
Copying positions, not fillsCompare snapshots and
trade the difference		Trades that open
and close between
snapshots are
never seen
One-to-one size and leverageMirror the
leader exactly		One large trade
can take over a
small account
No recoveryTrust the feed
to never drop		One missed fill
and your positions
drift from the
leader's for good

An effective copy bot does the opposite of each. It gets fills pushed to it as they happen. It sizes every copy with its own caps and leverage. And it re-checks the leader's real positions whenever it might have missed something.

The limits of Hyperliquid's API for copy trading

Hyperliquid's API can do all of this for one or two leaders. Past that, its limits bite. These are per IP address, from Hyperliquid's rate limits docs:

Limit What it means for copy trading
10 unique users across user-specific live subscriptionsYou can follow at most 10
leaders live from one IP
10 live connectionsThe 10-user cap
applies across all of
them, so more
connections don't help
1,200 REST weight per minuteShared by every read and
every order you send
clearinghouseState costs 2Polling 20 leaders'
positions every 2 seconds
uses the whole 1,200
userFills costs 20, plus 1 per 20 fillsPolling one leader's
fills every 2
seconds uses half
the budget or more
userFills returns at most 2,000 recent fillsCatching up after a
gap means paging
userFillsByTime ,
which keeps only the
10,000 most recent

Your own account has one more limit: an action budget. It starts at 10,000 requests and grows by one per USDC you trade. Small copies earn little budget, so don't waste it on needless cancels and retries.

How Hydromancer's API comes in when copy trading on Hyperliquid

Hydromancer streams the same Hyperliquid data, with limits built for following many wallets. Here's a copy bot with and without it:

What the copy bot needs Without Hydromancer (Hyperliquid's API only) With Hydromancer's API
Follow leaders liveOne subscription
per leader; the
docs allow 10
unique users per
IP		userFills takes
up to 1,000
addresses in one
subscription
Recover from a dropResubscribe, then
backfill over REST		Reconnect with
your session ID
to replay up to
30 seconds
Fill longer gapsuserFillsByTime ,
the 10,000 most
recent fills		userFillsByTime
with history from
28 July 2025
Re-check leaders' positionsclearinghouseState
, one leader
per request		batchClearinghouseStates
: up to 1,000
wallets on one
DEX per request
Copy leverage changes and resting ordersPer-user live
subscriptions
or REST reads,
within the same
10-user cap		userLeverageUpdates
and
userOrderUpdates
for many
addresses at once
Choose who to followThe undocumented
leaderboard file		userPnlLeaderboard
: ranked by
realized PnL,
with a bot filter
Place the copiesHyperliquid's
exchange API		The same: orders
always go to
Hyperliquid

Each followed address counts toward your plan's subscription total. That's 500 on Starter, 5,000 on Growth and 10,000 on Scale, per our streaming limits docs. Orders still go to Hyperliquid, through the SDK.

Which to use: to follow one or two wallets, Hyperliquid's own live feed is enough. Choose Hydromancer when you follow more than 10 leaders, or need to recover quickly when a connection drops.

How the mini example works

Job What it does
Watch the leadersHydromancer's userFills feed, pushed as fills happen
Decide what to copyNew opens and adds on perps you can trade
Size it10% of the leader's change, capped
at $25 per coin and $60 in total
Place ordersImmediate-or-cancel orders through
Hyperliquid's SDK, at your own leverage
Stay in stepRe-reads the leader's positions after a reconnect,
every 5 minutes, and when a fill doesn't add up
Stop safelyLimits and a kill file, then cancel, flatten and check
Diagram of a copy trading bot on Hyperliquid in four steps: watch the leader's fills, size your share with caps, place your order through Hyperliquid's exchange API, and resync against the leader's positions.

You need Python 3, pip install hyperliquid-python-sdk, a Hydromancer API key, and a Hyperliquid account with an API wallet. Use an account that does nothing but copy. Our trading bot guide covers order placement and the kill switch, and our whale tracker guide shows how to find active wallets.

Step 1: Stream the leader's trades as they happen

A copy bot reacts to the leader's fills. A fill is one executed trade, with its coin, side, size and price. Rather than asking for the leader's fills every few seconds, subscribe once and let the server push each new fill to you. On Hyperliquid's own live feed, that's one subscription per leader:

code
import json
import websocket

ws = websocket.create_connection("wss://api.hyperliquid.xyz/ws")
sub = {"type": "userFills", "user": LEADER}
ws.send(json.dumps({"method": "subscribe", "subscription": sub}))

while True:
    msg = json.loads(ws.recv())
    if msg.get("channel") != "userFills":
        continue
    if msg["data"].get("isSnapshot"):
        continue  # skip the first, historical batch
    f = msg["data"]["fills"][0]
    print(f["dir"], f["sz"], f["coin"], "@", f["px"],
          "| leader's position before:", f["startPosition"])
    break
code
Close Short 0.022 XMR @ 605.1 | leader's position before: -3333.903

Each fill carries the leader's position before it (startPosition), so one fill tells you both the trade and the new position. That's what the bot copies: position changes, not orders. In a long-running bot, send {"method": "ping"} when the feed has been quiet for about 50 seconds; Hyperliquid closes connections that stay silent for 60.

Following more than 10 leaders: plug in Hydromancer. Hyperliquid's live feed stops at 10 users per IP. Hydromancer's userFills takes a list of up to 1,000 addresses in one subscription, and fills arrive as [address, fill] pairs:

code
import json
import os
import websocket

key = os.environ["HYDROMANCER_API_KEY"]
ws = websocket.create_connection("wss://api.hydromancer.xyz/ws?token=" + key)
ws.recv()  # the "connected" message

sub = {"type": "userFills", "addresses": LEADERS}
ws.send(json.dumps({"type": "subscribe", "subscription": sub}))

The fill fields are the same. The only change is that each fill comes with its address, so route it to the right leader before sizing the copy.

Step 2: Decide how much to copy

Copying the leader's exact size rarely makes sense. Their account is likely far bigger than yours, and one large trade could take over your whole balance. So each copy is a fraction of the leader's change, with two limits: a cap per coin, and a skip when the order would be too small to trade.

With a 10% ratio, a $25 cap per coin and ETH at $2,300:

Leader adds You hold You copy Why
4 ETH0 ETH0.0108 ETH10% would be 0.4 ETH,
cut to the $25 cap
0.03 ETH0 ETHNothing10% is worth $6.90,
under Hyperliquid's
$10 minimum
2 ETH0.0102 ETHNothingToo little room left
under the cap for a
minimum-sized order

Closes are sized from your position: if the leader closes half, you close about half of what you hold, adjusted for size steps and the minimum. A flip closes what you hold, then opens the new side within the same limits. Set your own leverage per coin rather than mirroring the leader's.

Step 3: Re-check the leader's positions to catch missed trades

No feed is perfect. A dropped connection or a restart can make the bot miss a fill, and then its copy of the leader's positions is wrong for good. The fix is to check its view against the leader's real positions from time to time. On Hyperliquid, that's one clearinghouseState request per leader:

code
import requests

state = requests.post(
    "https://api.hyperliquid.xyz/info",
    json={"type": "clearinghouseState", "user": LEADER},
).json()

positions = {}
for p in state["assetPositions"]:
    positions[p["position"]["coin"]] = p["position"]["szi"]

print(len(positions), "open positions, e.g. XMR:", positions.get("XMR"))
code
24 open positions, e.g. XMR: -3339.508

Many leaders: plug in Hydromancer. At 2 weight per request, re-checking hundreds of leaders eats your 1,200-a-minute budget. Hydromancer's batchClearinghouseStates reads up to 1,000 wallets on one DEX in a single request:

code
import os
import requests

states = requests.post(
    "https://api.hydromancer.xyz/info",
    json={"type": "batchClearinghouseStates", "users": LEADERS},
    headers={"Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}"},
).json()

print(len(states["successful_states"]), "leaders' positions in one request")
code
50 leaders' positions in one request

The bot uses these checks in three ways:

  • Out-of-step check. If a fill's startPosition doesn't match what the bot thinks the leader holds, something is out of step, possibly a missed fill.
  • Resync. The bot then re-reads the leader's real positions and copies any difference.
  • Timer and reconnects. It also resyncs every 5 minutes and after each reconnect. The mini example reconnects with a fresh session and relies on this resync. A production bot can also reconnect with its session ID to replay short drops.

A change found by a resync is copied late, at the current price. It's a repair, not a good copy.

What one live run did

We let the mini example follow an active leader for about 12 minutes, with orders on Hyperliquid's testnet:

Count
Leader fills seen23
Copied2 (BTC and SOL shorts,
each cut to the $25 cap)
Skipped: at or near the cap2
Skipped: too small after caps and rounding4
Skipped: leader reduced a position we didn't hold11
Skipped: market not available to the test account4

We then stopped it with the kill file. It closed both positions and confirmed the account was flat. Of the 21 skips, 6 came from the caps and the minimum order size. The other 15 were reductions of positions we never copied, or markets we couldn't trade.

Be honest about what copying can't do

  • You always trade AFTER the leader, possibly at a different price.
  • Leverage differs. A large account can ride out a move that would liquidate a small copy.
  • Results will differ from the leader's, because of skipped fills and caps. You also pay or receive funding on your own positions, which won't match the leader's.
  • Your current portfolio move is not the same as the leader as there are way too many factors beyond your control.

FAQ

Is copy trading on Hyperliquid profitable?

It can be, but not automatically. You trade after the leader, possibly at a different price, skip fills that are too small, and pay your own fees and funding. A leader's past results don't promise future ones, so size copies small and check the leader's history first.

Is copy trading allowed on Hyperliquid?

Every wallet's trades on Hyperliquid are public, so following a wallet means reading public data, and your copies are ordinary orders through Hyperliquid's API. Rules can differ by country, and this isn't legal advice.

What's a good copy trading strategy on Hyperliquid?

Pick leaders by their closed-trade results over months, not one big win, and follow several rather than one. Cap your size per coin and in total, skip copies too small to trade, and set your own leverage. Our leaderboard guide shows how to rank traders by realized PnL.

How many wallets can I copy on Hyperliquid?

With Hyperliquid's own live feed, up to 10 users per IP. Hydromancer's userFills takes up to 1,000 addresses in one subscription, within your plan's subscription total (500 on Starter, more on higher plans).

Why not just poll the leader's positions?

Polling makes every copy as late as your polling interval, and it uses the request weight you need for your own orders. It also misses trades that open and close between polls.

Should I copy the leader's existing positions?

The mini example doesn't. It records them at start and copies only changes from then on, so it never enters an old trade at a later price.

Next steps

← All posts

Read next