BlogDeveloper

How to Launch Point & Referral Programs on Your Hyperliquid App

Run referrals and points on Hyperliquid builder codes: discount referred users, pay referrers from real fills, score points fairly and spot farming.

HydromancerTeam
How to Launch Point & Referral Programs on Your Hyperliquid App

There are two ways to reward the people who use your Hyperliquid app. A referral program pays them for bringing in new traders. A points program pays them for coming back. They solve different problems, and on Hyperliquid both are built from the same record: every fill your app sends, tagged with your builder code.

This guide builds the two together:

  • Referrals. A referrer gets a share of the fees their friends pay you, and the friend gets a discount.
  • Points. You score what each user does in your app and pay that score back later: as a fee discount, as cash, or as a share of something bigger.

Why apps run them:

  • You only pay a referrer when it works. Their cut comes out of fees a referred user has already paid you.
  • Traders listen to traders. A recommendation from someone they follow carries more weight than a banner.
  • A score brings people back. A number that grows every week is a reason to open your app again.
  • You choose what gets rewarded. Volume, days active, resting orders, referrals: you decide what counts.
  • The cost of points comes later. They cost nothing to hand out, and you set what they're worth once you know what you can afford.

On Hyperliquid, the fee behind all of this is your builder fee: the fee your app adds to each order it sends. You set it on every order, and it's recorded onchain on every fill.

Why should you choose to build a referral and points program on Hyperliquid?

#1: The fee is yours to split

A builder fee can be up to 0.1% on perps (futures with no expiry date) and 1% on spot (buying the token itself), and it's paid to your builder address.

#2: Every fill is on the public record

Each fill shows the wallet, the market, the size and the builder fee it paid. A fill is one completed match between a buyer and a seller. You can total what a referrer is owed or what a user scored, and they can check your math.

#3: There's no billing or tracking to build

Hyperliquid collects the fee when each order fills, and you claim it. One app's week came to 133,607 fills from 2,148 wallets, all readable without touching its servers.

#4: Apps already run both

Based pays 60% of its fee on direct referrals. Liquid pays 10% by default and up to 50% for some referrers. Invo pays 10% to 40%. Dexari, a mobile trading app, is in its second points season with weekly distributions.

#5: Traders have plenty of apps to choose from

1,022 builder codes sent trades to Hyperliquid in the last 30 days, so a reason to join and a reason to come back both matter. In the week we studied, 29% of the app's wallets traded on only one day out of seven.

#6: Your fee can fund it

Apps collected $13.3 million in builder fees in the 30 days to 12 November 2026, and they sent 12.4% of Hyperliquid's volume in October 2026, the highest full month on record.

How we tested. We pulled one large trading app's fills for the week of 2 to 8 November 2026. On 13 November 2026 we ran the referral example on one hour of them, scored the whole week under three points rules, ran the pair check on the whole week, and watched a busy builder code's live fills for 30 seconds. The fills and fees are real. The referral list and the scoring rules are made up for the examples. We placed no orders, sent no payouts and gave no points to anyone.

The code shown in this guide is an example that proves the idea works, not a finished app, so you don't need to copy it line for line. The API requests are exact: the request types, fields and URLs are what each API expects. Feel free to be creative with what you will create!

Part 1: Build the referral program

A referral program has two levers, and both use what builder codes already do:

  1. A share for the referrer. You keep a list of who referred whom, add up the builder fees each referred user paid, and pay a percentage of that to the referrer.
  2. A discount for the referred user. Because the fee is set on each order, you send a referred user's orders with a lower fee.

Referral programs on Hyperliquid apps today

App The referrer earns The referred user gets
Liquid10% of Liquid's fee by default,
up to 50% for some referrers
10% off Liquid's fee
Based60% of Based's fee on direct
referrals, plus 9% and 3% on
the next two levels
Not stated on the program page
Invo10% to 40% of fees, rising
with the number of referrals,
plus a second level
Not stated in the guide
Pump.funNot stated in the launch thread0.04% per trade instead of 0.05%

These are each app's published terms when we checked on 13 November 2026. The links are in Sources.

Steps 1 to 4 run from sign-up to the referrer's payout.

Step 1: Record who referred whom

Hyperliquid has no idea your referral codes exist. The link between a wallet and its referrer lives in your own database, and you set it once, at sign-up.

Decide the rules before you launch. Liquid's are a good starting point: a code can only be entered at sign-up, a user can't use their own code, and a user who already has a referrer can't add another.

To stop someone registering a wallet that isn't theirs, have each user sign a message with it. Step 1 of our trading competition guide covers that check.

Step 2: Charge referred users the discounted fee

Every order your app sends carries a builder field with your address and the fee for that order:

json
{"b": "0xYourBuilderAddress", "f": 45}

f is in tenths of a basis point, so 50 is 0.05% and 45 is 0.045%. Send 50 for a regular user and 45 for a referred one, and the discount is live. The builder codes guide has a full tested order.

The fee can't be higher than the user approved. Hyperliquid's maxBuilderFee request takes the user's wallet and your builder address, and returns that limit in the same unit.

The approval is a ceiling, not the price. In the week we pulled, the app's largest trader had approved 1000, which is 1%, and paid a small fraction of that on perps.

Here is what that app charged across the whole week, on perp fills:

Builder fee charged Share of perp volume Wallets
0.050%29.1%870
0.045%25.7%700
0.035%14.5%452
Under 0.015%22.9%2
Other rates7.7%33

That reads as a base rate and two discount tiers, plus much lower rates for a couple of accounts, all on one builder code. The 2 wallets on the lowest rates were 23% of the perp volume.

Discount now or rebate later? You can also charge everyone the full fee and pay the difference back. A lower fee at order time is what the user sees straight away. A rebate gives them a balance to come back and claim.

Step 3: Add up what each referrer earned

Hydromancer's builderFillsByTime returns every fill sent with your builder code between two times, with the wallet and the builder fee on each one. Send your API key in the Authorization header, as the example does.

This example reads referrals.json, a file that maps each referred wallet to a referral code, and pays each code 20% of the builder fees its users paid in one hour. Set BUILDER to your builder address:

code
import json, os, requests
from collections import defaultdict

HM = "https://api.hydromancer.xyz/info"
AUTH = {"Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}"}
referrer_of = json.load(open("referrals.json"))   # {user: referral code}
body = {"type": "builderFillsByTime", "builder": os.environ["BUILDER"],
        "startTime": 1793793600000, "endTime": 1793797199999}
owed = defaultdict(float)
for f in requests.post(HM, json=body, headers=AUTH).json():
    code = referrer_of.get(f["user"])
    if code and f.get("builderFee"):
        owed[code] += 0.20 * float(f["builderFee"])   # a 20% share
for code, usd in sorted(owed.items()):
    print(code, round(usd, 2))
code
ALICE 22.12
BOB 31.96
CAROL 41.98

That hour held 1,607 fills and $691.06 in builder fees. In our test we assigned wallets to three made-up codes, so the split above is only an illustration.

Four things to know before you run this on a full week:

  • One request returns up to 2,000 fills. For a longer period, ask for the next page with a cursor built from the last fill's time and txIndex. The loop is in the builder codes guide. Our week took 67 requests.
  • A few fills have no fee amount. In that hour it was 41 of 1,607. The example skips them.
  • Check the fee token. Every fill that week was paid in USDC. Each fill has a feeToken field if your users trade with other collateral.
  • Sub-builders take their cut first. If you split your fee with sub-builders, a fill lists them in subBuilders. Work out the referrer's share from what you keep.

builderFillsByTime is a Hydromancer endpoint, not part of Hyperliquid's API. With Hyperliquid's API alone, you can download your builder fills as one file per day. The builder codes guide shows both routes.

Step 4: Pay referrers

Builder fees build up on your builder address. Hyperliquid's docs say builders claim them "through the usual referral reward claim process". The matching action on its exchange endpoint is claimRewards.

From there you have two options:

  • Send it. Hyperliquid's transfer actions, usdSend and spotSend, move funds from one Hyperliquid account to another without touching a bridge.
  • Credit it. Show each referrer a balance in your app and let them claim it. Liquid and Invo both work this way, and Invo sets a $10 minimum.

Pick a schedule and publish it. A weekly payout with a small minimum keeps the number of transfers down. We didn't send payouts for this guide: the action names come from Hyperliquid's docs.

Referrals pay people for bringing in new traders. The other half of the intro is points, which pay them for coming back.

Part 2: Build the points program

Hyperliquid ran a points program of its own. From November 2023 it gave its traders 1,000,000 points every week for six months. A second phase followed at 700,000 a week and ended in November 2024, the month the HYPE token launched. Apps built on Hyperliquid now run the same idea on their own users, scored from the same fills as Part 1.

Step 5: Decide what earns points

You score What it rewards Watch out for
Volume tradedSimple, and everyone
understands it
The cheapest thing to
fake, and the biggest
wallets take most of it
Fees paid to youTies points to your revenueUsers on a discount earn
less per dollar traded
Resting orders (orders that wait on the book for someone to trade against)Liquidity, and more
patient traders
A small part of app volume
Days activeHabitTiny trades made only
to tick the box, so
set a minimum size

Volume and fees sound like the same thing. They aren't, once you charge different users different rates, as Step 2 does. In the week we studied, the top 1% of wallets by volume did 57.7% of the volume and paid 47.6% of the builder fees. The fifth-largest wallet traded $5.3 million and paid $267, which put it 51st by fees.

Resting orders are the small end. Orders that waited on the book were 22.9% of the app's fills and 4.3% of its volume.

Step 6: Decide how much the biggest wallets get

Trading volume is lopsided. Half of the app's wallets traded less than $4,728 that week, and one wallet alone was 22% of the volume. The scoring rule decides whether your points follow that shape.

We scored the same week three ways:

Scoring rule Points going to the top 1% of wallets
1 point per dollar traded57.7%
1 point per dollar, capped at $1 million per wallet17.1%
Square root of dollars traded14.3%

The top 1% was 21 wallets. Under a plain per-dollar rule they take more than half of the points. A cap or a square root leaves most of the points for everyone else, while still giving a large trader more than a small one.

Step 7: Choose a fixed pool or a fixed rate

A fixed rate, such as 1 point per $1,000 traded, is easy to explain. It also means the number of points you hand out depends on how much people trade, which you don't control.

A fixed weekly pool turns that around. Hyperliquid's program gave out a set number of points each week and split it by that week's activity. It counted activity up to Wednesday 00:00 UTC and distributed on Thursday. Dexari distributes every Wednesday.

Two lines from those programs are worth copying into your own terms. Hyperliquid's docs say the criteria were "updated on a recurring basis". Dexari's say it "may verify activity and disqualify fraudulent or abusive behavior".

Step 8: Show points live and settle each week

People check their points far more often than you settle them, so show a running estimate. Hydromancer's builderFills stream sends every fill made through your builder code as it happens. Put your API key in the connection URL and set BUILDER to your builder address.

This example scores each fill at 1 point per $1,000:

code
import asyncio, json, os, websockets
URL = "wss://api.hydromancer.xyz/ws?token=" + os.environ["HYDROMANCER_API_KEY"]
SUB = {"type": "subscribe", "subscription": {
    "type": "builderFills", "builder": os.environ["BUILDER"]}}
REPLY = {"connected": SUB, "ping": {"type": "pong"}}
async def main():
    async with websockets.connect(URL, max_size=None) as ws:
        async for raw in ws:
            m = json.loads(raw)
            if m["type"] in REPLY:
                await ws.send(json.dumps(REPLY[m["type"]]))
            for user, f in m.get("fills", []):
                points = float(f["px"]) * float(f["sz"]) / 1000
                print(user[:8], f["coin"], round(points, 3), "points")
asyncio.run(main())
code
0x284ddf SOL 0.1 points
0xbd7f89 ETH 0.17 points
0x2392c7 BTC 0.03 points
0x2392c7 BTC 0.675 points
0x2392c7 BTC 0.015 points
0x2392c7 BTC 0.04 points

Your output will show your own users' wallets and trades. The first message you receive is connected, and that's when you subscribe. The server sends a ping from time to time and expects a pong back. Each builderFills message carries a list of fills, and each fill comes with its wallet address. If the connection drops, skip the fills you've already counted when you reconnect: a fill's trade ID (tid), wallet and side don't repeat together.

Treat the live number as an estimate and settle each week from the full record, with the same builderFillsByTime request as Step 3. The same stream can keep a referrer's balance moving while their friends trade.

Part 3: Protect both programs

Four checks follow: count only trades through your app, price in self-referral, make wash trading cost more than it pays, and look for many wallets and bots.

Count only what goes through your app

A user who approved your fee can still trade anywhere. Those trades pay you nothing, so they pay the referrer nothing, and you have no fee to fund points for them.

We checked how often that happens. Hydromancer's builderApprovedFillsByTime returns every fill by wallets that have approved your builder fee, whichever app they used. Of the first 2,000 such fills in one afternoon hour, 571 didn't carry the app's builder code. 60 of those were liquidations, which never carry one. 80 carried another app's code, and 431 carried none, 275 of them from a single wallet. Leaving out the liquidations, that was 10% of the value traded, from 39 of 303 wallets.

Say it plainly in your terms. Dexari's read: "Only actions performed directly on Dexari count toward points." That's also the natural rule, because builderFills and builderFillsByTime return only the fills sent with your code.

Hyperliquid's own referral codes are a separate thing. They're tied to the user's Hyperliquid account and pay out of Hyperliquid's fees, not yours. Our Hyperliquid fees guide has the rates.

Price in self-referral

A user who refers their own second wallet collects the discount and the referrer's share. Treat those two added together as the deepest discount you offer anyone, and price it so you're fine with that.

Fun one: Make wash trading cost more than it pays!

The simplest way to farm volume is a wash trade: one person on both sides, with two wallets.

It wouldn't be good if someone is washtrading on your platform to maximise points.

So, you need to work out what that costs. At Hyperliquid's base rates on its standard perp markets, a trade costs 0.045% on the side that takes liquidity, meaning the order that trades at once, and 0.015% on the side that rests. Your builder fee is charged on both fills. With a 0.05% builder fee, the pair pays 0.16% in total. A $1 million wash trade costs $1,600, and $1,000 of that is your own fee. It also puts $2 million of volume on your scoreboard.

A referrer's share alone can't make that pay. It's a slice of fees already paid, and Hyperliquid's own fees are paid on top, so trading against yourself costs more than the share returns, even at a 100% share.

Points and sign-up bonuses change that. If the points for $2 million of volume are worth more than $1,600, farming pays. Keep them worth less. Two things lower the cost. Traders with very high volume pay Hyperliquid lower rates. And some markets charge less: on the stock and commodity markets listed through HIP-3, the fee on top of yours was about 0.009% for the side that took liquidity in the week we studied. Your own fee doesn't shrink, so on those markets it's most of what a wash trade costs.

You can also look for it. Every trade has an ID, and both sides share it, as our fills vs trades guide explains. If one trade ID shows up twice in your fills, both wallets were your users. This example reads a week of builder fills saved as fills.json:

code
import json
from collections import Counter, defaultdict

fills = json.load(open("fills.json"))    # a week of your builder fills
users = defaultdict(set)
for f in fills:
    users[f["tid"]].add(f["user"])       # one trade ID, up to two wallets
pairs = Counter(tuple(sorted(u)) for u in users.values() if len(u) == 2)
print("Trades with your users on both sides:", sum(pairs.values()))
for (a, b), n in pairs.most_common(3):
    print(a[:8], b[:8], "traded against each other", n, "time(s)")
code
Trades with your users on both sides: 27
0x7a3f26 0xe35288 traded against each other 1 time(s)
0x5693d5 0x81791f traded against each other 1 time(s)
0x45617e 0xd33910 traded against each other 1 time(s)

That's the whole week for the app we studied: 27 trades out of 133,580 had its users on both sides, and no pair of wallets met twice. That looks like chance, not farming. A pair that trades with each other again and again is the pattern to look into.

Check for many wallets and bots

  • One person, many wallets. Look for wallets funded from the same address. Step 4 of our trading competition guide covers this.
  • Bots. Hydromancer's userPnlLeaderboard has a minHumanScore filter for accounts that trade like programs.

Referral shares and points both come back to the record from the top: every fill your app sends, tagged with your builder code.

What changes with Hydromancer?

Hyperliquid's API gives you the pieces to run both programs: the per-order fee, the approval check, your all-time fee total and a daily file of your fills. Orders, approvals, claims and payouts always go through Hyperliquid.

Hydromancer adds the reading side:

  • Any time range. builderFillsByTime covers any window from 28 July 2025, with the wallet and fee on every fill.
  • Live. The builderFills stream sends each fill as it happens, for running point totals and referrer balances.
  • Outside your app. The approval-based endpoints show what your users do elsewhere.

These are Hydromancer endpoints, added for builder convenience, and aren't part of the original Hyperliquid API. OneKey uses Hydromancer data for its Perps referral rebates. Plans start at $300 a month, and the pricing page has the details.

FAQ

Is this the same as a Hyperliquid referral code?

No. A Hyperliquid referral code is run by Hyperliquid and pays out of Hyperliquid's fees. A program built on your builder code is yours: you set the share, the discount and the rules, and it's paid out of your builder fee.

Can I charge different users different builder fees?

Yes. The fee is set on each order, up to the maximum that user approved. The app in our test charged 12 different rates on perps in one week.

How do referrers get paid?

You claim your builder fees on Hyperliquid, then either transfer each referrer's share to their Hyperliquid account or credit a balance in your app that they can claim.

Do trades on other apps count?

Only if you decide to pay for them out of pocket. You earn a builder fee on orders sent with your code, and nothing on the rest.

Does Hyperliquid have a points program now?

Hyperliquid's docs describe its points program in the past tense: it began on 1 November 2023 and its last phase ended in November 2024. Programs run by apps are separate, and each app decides what its points are worth.

What should a point be worth?

Less than it costs to fake. At base rates with a 0.05% builder fee, $2 million of wash-traded volume costs $1,600 in fees.

How often should points be distributed?

Weekly is what both programs in this guide chose. Hyperliquid distributed every Thursday, and Dexari distributes every Wednesday.

Can users verify their points and referral earnings?

Yes, if you publish the rule. Every fill sent with your builder code is public, so anyone can recompute a score or a referrer's share.

Sources

#1: Hyperliquid docs, Builder codes
#2: Hyperliquid docs, Exchange endpoint
#3: Hyperliquid docs, Referrals
#4: Hyperliquid docs, Points
#5: Hyperliquid docs, Fees
#6: Hyper Foundation on X, HYPE genesis event, 28 November 2024
#7: Liquid docs, Referral bonuses
#8: Based docs, Affiliate Program
#9: Invo guides, Referral Earnings
#10: Pump.fun on X, perps fees, 28 October 2026
#11: Dexari Help Center, Points Program
#12: Hydromancer docs, builderFillsByTime
#13: Hydromancer docs, builderFills stream
#14: Hydromancer docs, Monitor approved builder users
#15: Flowscan, Hyperliquid builders

Continue