Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Builder Codes (Front End Fee)

Build your own custom frontend and earn fees

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.

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.

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, and that address can be updated at any time without losing the integratorId.

Fee Structure

  • The integrator fee is charged on top of regular trading fees — the user's approval caps only this additional fee

  • Fees are charged on filled notional volume, and the fee follows the order: it applies when the order fills immediately as taker and when it rests on the book and later fills as maker

  • 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 — orders carrying a higher fee, or a fee from an integrator the user has not approved, are rejected onchain

  • The protocol enforces a hard upper bound of 1.00% on any integrator fee

Maker fills earn builder fees. The API reference at aftermath.finance/docs still describes integratorFee as applying to "taker volume only" and still says an integrator needs a per-market vault. Both statements are stale, and this page is the current one. The deployed Move ABI confirms it: perpetuals::events::FilledMakerOrder in move-interfaces carries integrator_id and integrator_fee_paid_usd, exactly as FilledTakerOrder does.

For Developers

TypeScript. We've integrated the builder code approval functions into our TypeScript SDK and detailed them in our docs. One-time integrator registration uses the native API.

LogoPerpetuals | Aftermathdocs.aftermath.finance

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

LogoSwagger UIaftermath.finance

API Endpoints

All builder code endpoints accept POST requests with a JSON body. Base URL: https://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

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 GasPool sponsorship) are optional on every builder-code transaction route. A sponsor contains walletAddress, bytes, and signature, plus an optional MIST gasBudget; bytes is base64 of the reusable Aftermath Terms and Conditions message.

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

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

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-ts-sdk) — Typed helper methods for builder code approvals. One-time registration uses the native API.

  • CCXT-compatible API (/api/ccxt/*) — Exchange-style endpoints for bot integrations that follow the CCXT standard.

PreviousReference Gas Price
NextMargin

Last updated