> 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 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](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 rewards

Use the `claimRewards` action to claim builder fees, referral cashback, and referral commissions. It credits each eligible DEX/token reward bucket to the account'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.
* [Referral Program](/trade/referral-program.md): referral cashback and commissions.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hyperlink.xyz/api/builder-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.