> For the complete documentation index, see [llms.txt](https://docs.hyperlink.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperlink.xyz/api/builder-codes.md). # Builder Codes 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](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/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%"`. ```json { "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](/api/api-keys.md) for signing chainIds. A success returns `{ "status": "ok", "response": { "type": "default" } }`. With the HyperLink Python SDK, construct the client with the main wallet key: ```python 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%) | ```json { "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): ```python 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: ```json { "action": { "type": "approvedBuilders", "user": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1" }, "nonce": 1712140800000, "signature": { "r": "0x...", "s": "0x...", "v": 27 } } ``` Response: ```json ["0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f"] ``` `maxBuilderFee` returns the approved rate for one builder in tenths of a basis point, or `0` when unapproved: ```json { "action": { "type": "maxBuilderFee", "user": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1", "builder": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f" }, "nonce": 1712140800000, "signature": { "r": "0x...", "s": "0x...", "v": 27 } } ``` Response: ```json 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. ```json { "action": { "type": "referral", "user": "0x8c67a1b3d5e9f2407b6a0c4d8e1f5a3b7c9d0e2f" }, "nonce": 1712140800000, "signature": { "r": "0x...", "s": "0x...", "v": 27 } } ``` Response: ```json { "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. ```json { "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](/api/exchange-methods.md): full `approveBuilderFee`, `claimRewards`, `approvedBuilders`, and `maxBuilderFee` schemas. * [Authentication & Keys](/api/api-keys.md): agent-signed vs user-signed actions. * [Fees](/trade/fees.md): HyperLink's own fee schedule. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hyperlink.xyz/api/builder-codes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.