BlogDeveloper

How to Run a Trading Competition on Hyperliquid

Run a Hyperliquid trading competition: register wallets, score PnL over your own start and end time, filter out cheating, and track it live. Tested.

HydromancerTeam
How to Run a Trading Competition on Hyperliquid

A Hyperliquid trading competition (or trading challenge) brings traders in: a prize pool, a leaderboard, a fixed window.

Why people run one:

• To bring in traders. Exchanges, apps and communities use prizes to get new users trading.
• To build a community around a leaderboard people check every day.
• To find talent. Funds and prop firms use competitions to spot good traders.
• To give traders a reason to come back. A fixed window and a prize create urgency.

Why should you choose to run a trading competition on Hyperliquid?

• No exchange sponsor needed. A community, a fund or a trading group can verify every entrant's trades straight from the chain, instead of asking an exchange to host the scoreboard.
• Players keep their money. Funds stay in each player's own wallet the whole time; you only need their address.
• You set the rules. Hyperliquid's leaderboard ranks fixed windows (day, week, month, all time). Yours can run Friday to Sunday, count one market, or reward risk-adjusted returns.
• It brings trading to your app. Trades players make through your app during the event carry your builder code, so the competition earns while it runs.

The scoring is the hard part: PnL over *your* window, not Hyperliquid's.

How we tested. We scored the same 10 players over the same 3 days, once with each API and its own PnL measure, on 31 October 2026, and timed both. The examples that read a .txt file expect one full wallet address per line.

Step 1: Register players and prove the wallet is theirs

Each player gives a wallet address. To stop people entering a famous trader's address, ask them to sign a message with that wallet. If the competition is meant to bring volume to your app, require trades to go through your builder code and check each player has approved it with approvedBuilders or maxBuilderFee.

Use a fresh sub-account per player if they have one (Hyperliquid unlocks sub-accounts after $100,000 of trading volume). It separates competition trades from everything else in their wallet, which makes scoring simple.

Step 2: Score PnL over your window

Hyperliquid's portfolio request returns PnL for fixed windows only (day, week, month, all time). A competition from Friday 00:00 to Sunday 23:59 doesn't line up with any of them, so both prototypes score an exact start and end time.

Hyperliquid API

Every fill carries closedPnl and fee, so realized PnL for any window is their sum over the window's fills. The prototype pages through each player's fills and adds them up, pausing so a busy player doesn't use up the IP's rate limit:

code
import time, requests

end, board = int(time.time() * 1000), []
for p in open("players.txt").read().split():
    fills, start, page = {}, end - 3 * 86400000, [0] * 2000
    while len(page) == 2000:
        page = requests.post("https://api.hyperliquid.xyz/info", json={
            "type": "userFillsByTime", "user": p, "startTime": start,
            "endTime": end}).json()
        fills.update({f["tid"]: f for f in page})
        start = page[-1]["time"] if page else end
        time.sleep(6)                 # a full page weighs 120 of 1,200/min
    pnl = sum(float(f["closedPnl"]) - float(f["fee"]) for f in fills.values())
    board.append((round(pnl), len(fills), p[:10]))
print(sorted(board, reverse=True))
json
[(1342203, 26171, '0x58b27998'), (763365, 21303, '0x9546b9d4'), (213374, 4871, '0xda3768e9'), (178015, 10740, '0x9321d811'), (0, 0, '0xedcdcaa1'), (-16529, 2247, '0x051c2e6d'), (-45630, 5190, '0x90dbb196'), (-72618, 1795, '0x020ca66c'), (-82610, 3135, '0xe83b5e36'), (-142970, 4892, '0x77ee3604')]

Hydromancer API

userPnlSummary takes a startTime and endTime and scores the trades closed in that window, net of fees and funding:

code
import os, time, requests

H = {"Authorization": "Bearer " + os.environ["HYDROMANCER_API_KEY"]}
end = int(time.time() * 1000)
board = []
for p in open("players.txt").read().split():
    s = requests.post("https://api.hydromancer.xyz/info", headers=H, json={
        "type": "userPnlSummary", "user": p,
        "startTime": end - 3 * 86400000, "endTime": end}).json()
    board.append((round(float(s["totalPnl"])), s["totalTrades"], p[:10]))
print(sorted(board, reverse=True))
json
[(1433511, 16, '0x58b27998'), (615584, 18, '0x9321d811'), (59309, 26, '0xda3768e9'), (0, 0, '0xedcdcaa1'), (-10730, 8, '0x9546b9d4'), (-56565, 3, '0x020ca66c'), (-70455, 3, '0x051c2e6d'), (-73686, 7, '0xe83b5e36'), (-272758, 3, '0x90dbb196'), (-390351, 15, '0x77ee3604')]

Side by side

Hyperliquid API Hydromancer API
What it countsProfit on every fill in the windowWhole trades closed in the window
Leader0x58b279980x58b27998
Worked2 of 2 runs3 of 3 runs
Time to finish (median)298 s1.7 s
Requests4610
Rate-limit cost5,007 weight (limit: 1,200 a minute per IP)200 points (limit: 20,000 a minute on the Growth plan)
Data received over REST (uncompressed)26.8 MBunder 0.1 MB

Both work, and both put the same player first. The columns differ because they count different things: the fill sum books profit on every partial close inside the window, while userPnlSummary counts whole positions that closed in it, so the second column on Hydromancer is trades and on Hyperliquid is fills.

The fill sum also leaves out funding, while userPnlSummary is net of fees and funding. Those two differences are how one player can show +$763k on one board and -$10.7k on the other.

Pick one and publish it. The official version is slow because busy players make a lot of fills (more than 80,000 in three days here); it also only reaches each player's most recent fills (how far that goes), so for a long competition with busy players, record fills live from day one. userPnlSummary is a paid add-on.

Step 3: Decide what counts, and say so

Two PnL numbers can both be right and point in opposite directions: the same trader can be down on the account and up on closed trades over the same month (a real example). Players will argue about whichever one you don't pick, so publish the rule before registration opens:

• Realized PnL (closed trades only) is easy to explain but lets a player hide a losing open position until the end.
• Account value change counts open positions too, but deposits and withdrawals must be taken out, or a player could deposit their way to the top.
• Return (%) instead of dollars lets small accounts compete with large ones.

Most competitions also set a minimum number of trades and close everything at the end time.

Step 4: Stop the obvious cheating

• Wash trading: a player trading with their own second wallet. Since every trade lists both addresses, flag players whose trades mostly hit the same counterparty.
• Deposit pumping: strip deposits and transfers out using userNonFundingLedgerUpdates.
• Multiple entries: one person, many wallets. Look for wallets funded from the same address.

Hydromancer's leaderboard (also a paid add-on) includes a heuristic humanScore that flags accounts trading like bots, if your rules exclude them.

Step 5: A live leaderboard

Players refresh the leaderboard constantly, so the "current balance" column has to stay fresh.

Hyperliquid API

Two requests per player, perps and spot. Fine for a 20-player league; for 200 players refreshed every minute, that's most of an IP's budget gone before the rest of your site runs.

Hydromancer API

batchPortfolioStates returns live account state for up to 500 wallets in one request. Hydromancer added this endpoint for builder convenience; it isn't part of Hyperliquid's original API, and orders still go through Hyperliquid.

Side by side

Hyperliquid API Hydromancer API
Requests to refresh 200 players4001 (main DEX; with every HIP-3 DEX included, 100 players per request)
Rate-limit cost per refresh800 of the 1,200 weight each IP gets a minute200 points (3 per wallet, capped at 200 a request), of 20,000 a minute on the Growth plan

Recompute the window scores from Step 2 every few minutes, and the current balances as often as you like.

FAQ

Can anyone run a trading competition on Hyperliquid?

Yes. Trading data is public, so anyone can score real accounts. Check the rules where you and your players live if there's a prize.

How do I score PnL for a custom start and end time?

On the official API, add up closedPnl minus fee from each player's userFillsByTime over your window; it took five minutes for 10 busy players in our test. Hydromancer's userPnlSummary accepts startTime and endTime and took under two seconds.

How do competitions make money?

Usually by bringing traders to an app that earns builder fees on their orders, or through sponsors.

• Hyperliquid leaderboard: track top addresses' PnL
• How to build a Hyperliquid copy trading bot
• Hyperliquid builder codes

Sources

- Hyperliquid docs: Info endpoint, Sub-accounts
- Hydromancer docs: userPnlSummary, Pricing

All posts
Continue

Read next