> For the complete documentation index, see [llms.txt](https://docs.aftermath.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aftermath.finance/perpetuals/architecture/builder-codes-front-end-fee.md).

# Builder Codes (Front End Fee)

Builder codes allow third-party integrators to permissionlessly earn fees on orders they submit on behalf of users. This enables trading platforms, referral programs, and white-label solutions to monetize their user traffic by providing order flow to the Aftermath ecosystem.

### Overview

**Builder codes** provide a flexible fee-sharing mechanism for integrators building on Aftermath Perpetuals. The system works as follows:

1. **Integrator Registration**: An integrator registers once, globally, and is assigned a numeric `integratorId`
2. **User Authorization**: Users approve specific integrators and set a maximum fee they're willing to pay
3. **Order Submission**: Integrators submit orders on behalf of users, specifying their fee (up to the approved maximum)

Unlike referral codes, builder codes are applied in real time as part of the onchain fee logic.

{% hint style="info" %}
**Changed:** integrators are now identified by a numeric `integratorId`, not by address, and registration is a single global step. The previous per-market fee-vault model — creating a vault per market and claiming accrued fees — has been removed.
{% endhint %}

### How It Works

#### For Users

Users maintain full control over which integrators can earn fees on their orders:

* Approve integrators with a maximum fee cap per integrator
* Revoke permissions at any time
* Set different fee limits for different integrators

#### For Integrators

Integrators complete a one-time global setup before earning fees:

1. Register once as an integrator — this is global, not per market
2. Get users to approve them, each user setting a maximum fee
3. Submit orders carrying `integratorId` and the fee to charge

There is no vault to create and no claim step. A registration is simply the integrator's global address recorded under the perpetuals registry.

#### Fee Structure

* Fees are charged on **taker volume only** — maker volume generates no integrator fee
* Fees are expressed as a fractional decimal: `0.0005` is a 0.05% fee
* The per-order fee must not exceed the `maxIntegratorFee` that user approved for that integrator

### For Developers

**TypeScript.** We've integrated all required builder code functionality into our TypeScript SDK and detailed all functions in our docs.

{% embed url="<https://docs.aftermath.finance/for-developers/typescript-sdk/products/perpetuals/perpetuals#builder-code-integration-methods>" %}

**API.** For more information on how to interact with builder codes through our API, view our API reference.

{% embed url="<https://v2-preview.aftermath.finance/docs>" %}

#### API Endpoints

All builder code endpoints accept POST requests with a JSON body. Base URL: `https://v2-preview.aftermath.finance`

Read registration and per-account approvals:

* `/api/perpetuals/builder-codes/integrator-registration` — resolves an `integratorId` to its registered `integratorAddress`
* `/api/perpetuals/builder-codes/integrator-config` — takes `accountId` and `integratorId`, returns `{ exists, maxIntegratorFee }`

Build transactions for setup and approval:

* `/api/perpetuals/builder-codes/transactions/create-integrator-registration` — one-time global registration, signed by the integrator
* `/api/perpetuals/builder-codes/transactions/create-integrator-config` — user approves an integrator and sets the fee cap
* `/api/perpetuals/builder-codes/transactions/remove-integrator-config` — user revokes an integrator

Example: register as an integrator

```
## Request
POST https://v2-preview.aftermath.finance/api/perpetuals/builder-codes/transactions/create-integrator-registration
Content-Type: application/json

{}

## Response
{
  "txKind": "<base64-encoded TransactionKind>",
  "sponsorSignature": null
}
```

The integrator's identity is taken from the transaction sender on-chain, so no address goes in the request body. Both `txKind` (to extend an existing transaction) and `sponsor` (for gas pool sponsorship) are optional on every builder-code transaction route.

Example: a user approves an integrator with a 0.05% cap

```
## Request
POST https://v2-preview.aftermath.finance/api/perpetuals/builder-codes/transactions/create-integrator-config
Content-Type: application/json

{
  "accountId": "123n",
  "integratorId": 1,
  "maxIntegratorFee": 0.0005
}
```

Once approved, attach the builder code to each order you submit for that user:

```json
{
  "builderCode": { "integratorId": 1, "integratorFee": 0.0005 }
}
```

SL/TP and stop orders accept their own `builderCode`, independent of the parent order's.

#### Transaction Flow

All transaction endpoints return a serialized transaction kind. To execute on-chain:

1. Call the transaction endpoint with your parameters
2. Read `txKind` from the JSON response
3. Build a `Transaction` from the `txKind` using the Sui SDK
4. Sign the transaction with your wallet
5. Submit to the Sui network

If you passed a `sponsor`, the response also carries `sponsorSignature`. In that case `txKind` holds base64 BCS-encoded `Transaction` bytes with gas payment already attached — sign those bytes and submit them together with the sponsor signature.

#### Integration Modes

There are three ways to integrate builder codes:

* Native API (`/api/perpetuals/*`) — Recommended. Full feature set including registration, approval, and transaction builders.
* TypeScript SDK (`@aftermath-finance/sdk`) — Typed helper methods for builder code operations. Best for TypeScript applications.
* CCXT-compatible API (`/api/ccxt/*`) — Exchange-style endpoints for bot integrations that follow the CCXT standard.