Builder Codes

Builder codes on HyperLink: charge an approved per-order fee on the orders your app routes to Hyperliquid, with fixed fee tiers and API-based claims.

Builder codes let applications charge a fee on the orders they send through HyperLink on a user's behalf. The user approves a maximum fee rate for each builder with their main wallet and can revoke it at any time. The fee is set per order and accrues to the builder's HyperLink account.

The flow mirrors Hyperliquid's builder codes: approve a rate with approveBuilderFee, then attach {"b": builder, "f": fee} to order actions.

Differences from Hyperliquid

	HyperLink	Hyperliquid
Per-order fee f	One of four tiers: 5, 10, 15, 20 (0.5–2 bp)	Any value up to the approved max
Maximum fee rate	0.02% (2 bp) on perps and spot	0.1% on perps, 1% on spot

Everything else carries over: approvals are signed by the user's main wallet, f is in tenths of a basis point (10 = 1 bp), fees are charged in the quote or collateral asset, and each user can have at most 10 active builder approvals.

Approve a builder fee

The user signs an approveBuilderFee action with their main wallet; agent (API) keys cannot approve builder fees. maxFeeRate is a percent string with up to three decimals, at most "0.02%".

{
  "action": {
    "type": "approveBuilderFee",
    "hyperliquidChain": "Mainnet",
    "signatureChainId": "0xa4b1",
    "maxFeeRate": "0.01%",
    "builder": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f",
    "nonce": 1712140800000
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

The action uses the user-signed EIP-712 domain, identical to Hyperliquid's HyperliquidTransaction:ApproveBuilderFee type; see Authentication & Keys for signing chainIds. A success returns { "status": "ok", "response": { "type": "default" } }.

With the HyperLink Python SDK, construct the client with the main wallet key:

import os
from eth_account import Account
from hyperliquid.exchange import Exchange

wallet = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])  # main wallet, not an agent key
exchange = Exchange(wallet, base_url="https://api.hyperlink.xyz")
exchange.approve_builder_fee("0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f", "0.01%")

To revoke a builder, approve them with "0%". Approving an 11th builder is rejected until one is revoked.

Attach the fee to orders

Once approved, order actions may include the optional builder field. b is the builder address in lowercase hex; f is the fee in tenths of a basis point and must be one of the four tiers, at or below the user's approved max.

f	Fee rate
5	0.5 bp (0.005%)
10	1 bp (0.01%)
15	1.5 bp (0.015%)
20	2 bp (0.02%)

{
  "action": {
    "type": "order",
    "orders": [
      { "a": 0, "b": true, "p": "50000", "s": "0.1", "r": false, "t": { "limit": { "tif": "Gtc" } }, "c": "0x1234567890abcdef1234567890abcdef" }
    ],
    "grouping": "na",
    "builder": { "b": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f", "f": 10 }
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Or through the SDK's builder parameter (orders can use your regular agent-keyed client):

from hyperliquid.utils.types import Cloid

result = exchange.order(
    name="BTC",
    is_buy=True,
    sz=0.1,
    limit_px=50000,
    order_type={"limit": {"tif": "Gtc"}},
    cloid=Cloid.from_str("0x1234567890abcdef1234567890abcdef"),  # required on HyperLink
    builder={"b": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f", "f": 10},
)

Fees are calculated from fill notional and accrue in the market's quote or collateral token. They apply to both sides of perp trades and to spot sells on any configured quote token. Spot buys do not accrue builder fees (same as Hyperliquid).

Query approvals

Two signed POST /exchange queries cover approvals; in both, user must be the authenticated account.

approvedBuilders lists the builder addresses the account has approved:

{
  "action": {
    "type": "approvedBuilders",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1"
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Response:

["0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f"]

maxBuilderFee returns the approved rate for one builder in tenths of a basis point, or 0 when unapproved:

{
  "action": {
    "type": "maxBuilderFee",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1",
    "builder": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f"
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Response:

10

Track accrued fees

As on Hyperliquid, accrued builder fees are part of the referral query response. builderRewards is the cumulative total, unclaimedRewards is what is currently claimable, and claimedRewards is what has been claimed. Top-level amounts are USDC; tokenToState breaks the same figures down per settlement token index. The response also carries the account's referral statistics.

{
  "action": {
    "type": "referral",
    "user": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f"
  },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Response:

{
  "referredUserCount": 0,
  "referredUserTotalVolume": "0.0",
  "builderRewards": "1.5",
  "unclaimedRewards": "1.0",
  "claimedRewards": "0.5",
  "tokenToState": [
    [0, { "cumVlm": "0.0", "unclaimedRewards": "1.0", "claimedRewards": "0.5", "builderRewards": "1.5" }]
  ],
  "code": null
}

Claim builder fees

Builders claim accrued fees with the claimRewards action, which credits each eligible DEX/token reward bucket to the builder's HyperLink spot balance in the same settlement token. Each bucket must exceed one whole settlement token; smaller buckets remain unclaimed. The action takes no parameters and can be agent-signed.

{
  "action": { "type": "claimRewards" },
  "nonce": 1712140800000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Errors

The API returns Builder fee has not been approved. when approval is missing, revoked, or below the order's f. Other builder-code admission failures return Order rejected.; verify the builder address and fee tier.

Next steps

• Exchange Methods: full approveBuilderFee, claimRewards, approvedBuilders, and maxBuilderFee schemas.

• Authentication & Keys: agent-signed vs user-signed actions.

• Fees: HyperLink's own fee schedule.