> For the complete documentation index, see [llms.txt](https://www.aevo.xyz/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.aevo.xyz/docs/api-reference/builder-codes.md).

# Builder Codes

Builder Codes let an application that routes trades to Aevo (a **builder**) earn a fee on the orders it submits for its users. The user approves the builder once, with a maximum fee. After that, the builder attaches its `builder_id` and a fee rate to each order it places for that user.

* The **builder fee** is separate from Aevo's trading fee. It is paid by the user in USDC and credited to the builder's fee account on every fill.
* The builder chooses the rate **per order**, so it can vary by user, market or order type. It can never exceed what the user approved or Aevo's protocol cap.
* Builder fees work on **perpetual** and **option** orders.
* Builders get a dashboard and a reporting API for volume, fees, traders and fills, including a CSV export for reconciliation.

## How it works

1. **Register** a builder from your fee account. Aevo generates your `builder_id`. See [Become a builder](/docs/api-reference/builder-codes/become-a-builder.md).
2. **Get user approval.** Each user signs a one-time `ApproveBuilder` message that sets the maximum fee your builder may charge them. See [User approval](/docs/api-reference/builder-codes/user-approval.md).
3. **Place orders** with `builder_id` and `builder_fee_rate`. See [Placing orders](/docs/api-reference/builder-codes/placing-orders.md).
4. **Track and reconcile** earnings with the dashboard or the reporting API. See [Reporting API](/docs/api-reference/builder-codes/reporting-api.md).

## Endpoint map

Which endpoint to call at each step, and whose credentials to use.

* **Fee account**: the builder's own Aevo account, which receives the fees.
* **User**: the trader's account. Your app calls these with the user's API key, and signs orders with the user's signing key.

| Step                                                       | Endpoint                                                                                                                                                                                                                                                                                  | Called with                                          | Signature needed                                             |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| Read protocol limits                                       | [`GET /builder-config`](/docs/api-reference/urls/public-api/getbuilderconfig.md)                                                                                                                                                                                                          | No auth                                              | —                                                            |
| Register your builder                                      | [`POST /builder/register`](/docs/api-reference/urls/private-api/postbuilderregister.md)                                                                                                                                                                                                   | Fee account API key                                  | —                                                            |
| Rename your builder                                        | [`POST /builder/profile`](/docs/api-reference/urls/private-api/postbuilderprofile.md)                                                                                                                                                                                                     | Fee account API key                                  | —                                                            |
| Show a builder's public profile                            | [`GET /builders/{builder_id}`](/docs/api-reference/urls/public-api/getbuildersbuilderid.md)                                                                                                                                                                                               | No auth                                              | —                                                            |
| Onboard a new user (creates the account and a signing key) | [`POST /register`](/docs/api-reference/urls/private-api/postregister.md)                                                                                                                                                                                                                  | No auth                                              | User wallet (`Register`) and the new signing key (`SignKey`) |
| User approves your builder                                 | [`POST /builder/approve`](/docs/api-reference/urls/private-api/postbuilderapprove.md) from your app, or the [approval link](/docs/api-reference/builder-codes/user-approval.md#option-2-approval-link)                                                                                    | No auth needed (send `account`), or the user API key | User wallet (`ApproveBuilder`)                               |
| Check whether a user approved you                          | [`GET /builder/approval`](/docs/api-reference/urls/private-api/getbuilderapproval.md)                                                                                                                                                                                                     | Fee account API key                                  | —                                                            |
| User lists their approvals                                 | [`GET /account/builder-approvals`](/docs/api-reference/urls/private-api/getaccountbuilderapprovals.md)                                                                                                                                                                                    | User API key                                         | —                                                            |
| User revokes                                               | [`POST /builder/revoke`](/docs/api-reference/urls/private-api/postbuilderrevoke.md)                                                                                                                                                                                                       | User API key                                         | —                                                            |
| Place or edit an order with a builder fee                  | [`POST /orders`](/docs/api-reference/urls/private-api/postorders.md), [`POST /orders/{order_id}`](/docs/api-reference/urls/private-api/postordersorderid.md), [`POST /batch-orders`](/docs/api-reference/urls/private-api/postbatchorders.md), or websocket `create_order` / `edit_order` | User API key                                         | User signing key (builder `Order` type)                      |
| Totals, daily series, comparison with the previous period  | [`GET /builder/stats`](/docs/api-reference/urls/private-api/getbuilderstats.md)                                                                                                                                                                                                           | Fee account API key (read-only works)                | —                                                            |
| Per-market breakdown                                       | [`GET /builder/markets`](/docs/api-reference/urls/private-api/getbuildermarkets.md)                                                                                                                                                                                                       | Fee account API key (read-only works)                | —                                                            |
| Per-trader breakdown                                       | [`GET /builder/users`](/docs/api-reference/urls/private-api/getbuilderusers.md)                                                                                                                                                                                                           | Fee account API key (read-only works)                | —                                                            |
| Individual fills, CSV export                               | [`GET /builder/fills`](/docs/api-reference/urls/private-api/getbuilderfills.md)                                                                                                                                                                                                           | Fee account API key (read-only works)                | —                                                            |

## Fee units

Fee rates are decimal fractions with at most 6 decimals.

| Rate  | Basis points | API value  | Signed EIP-712 value |
| ----- | ------------ | ---------- | -------------------- |
| 0.01% | 1 bps        | `"0.0001"` | `100`                |
| 0.03% | 3 bps        | `"0.0003"` | `300`                |
| 0.05% | 5 bps        | `"0.0005"` | `500`                |

REST and websocket requests take the **decimal string**. EIP-712 signatures use the **raw 6-decimal integer** (the rate × 1,000,000).

## Limits

Every builder fee must be at or below both of:

* the **user's approved maximum** (`max_fee_rate` in their approval), and
* **Aevo's protocol cap** for the instrument type:

|                | Maximum builder fee                                                            |
| -------------- | ------------------------------------------------------------------------------ |
| **Perpetuals** | **5 bps** (0.05%) of notional                                                  |
| **Options**    | **3 bps** (0.03%) of index notional, and never more than **5% of the premium** |

The live values are published at [`GET /builder-config`](/docs/api-reference/urls/public-api/getbuilderconfig.md) (`max_fee_rate_perps` = `"0.0005"`, `max_fee_rate_options` = `"0.0003"`, `option_premium_cap` = `"0.05"`). A user's approved maximum can't exceed 5 bps either.

An order above either limit is rejected when it is submitted. If a limit changes after an order is resting (the user revokes, the builder is suspended, or a cap is lowered), later fills of that order still execute, with a builder fee of `0`.

## Fee formulas

**Perpetuals**

```
builder_fee = builder_fee_rate × price × contracts
```

**Options.** This has the same shape as Aevo's own option fee, so cheap options are protected:

```
builder_fee = min(
  builder_fee_rate  × index_price × contracts,
  option_premium_cap × premium    × contracts
)
```

Example: ETH index 2,700, 1 contract, builder rate `0.0003`, option premium cap `0.05`.

| Premium | Index leg | Premium-cap leg | Builder fee |
| ------- | --------- | --------------- | ----------- |
| 100     | 0.81      | 5.00            | **0.81**    |
| 20      | 0.81      | 1.00            | **0.81**    |
| 5       | 0.81      | 0.25            | **0.25**    |
| 1       | 0.81      | 0.05            | **0.05**    |

For a full comparison, including the crossover premium and how one approval interacts with the two caps, see [Perpetuals vs Options Fees](/docs/aevo-products/aevo-builder-codes/perps-vs-options-fees.md).

## Environments

|           | Mainnet                | Testnet                        |
| --------- | ---------------------- | ------------------------------ |
| REST      | `https://api.aevo.xyz` | `https://api-testnet.aevo.xyz` |
| Websocket | `wss://ws.aevo.xyz`    | `wss://ws-testnet.aevo.xyz`    |
| App       | `https://app.aevo.xyz` | `https://testnet.aevo.xyz`     |

{% hint style="info" %}
Build and test on testnet first. The [Python SDK](https://github.com/aevoxyz/aevo-sdk) supports registration, approvals, builder orders and reporting, and includes `builder_example.py`, a complete dry-run flow.
{% endhint %}


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://www.aevo.xyz/docs/api-reference/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 `build a script that syncs our docs to a CMS` 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.