> For the complete documentation index, see [llms.txt](https://ch-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://ch-docs.aftermath.finance/yong-xu-he-yue/architecture/builder-codes-front-end-fee.md).

# 集成商代码（前端费用）

构建您自己的定制前端并赚取费用

集成商代码 (Builder Codes) 允许第三方集成商无许可地对代用户提交的订单收取费用。交易平台、推荐计划和白标方案由此可以将自己的用户流量变现，同时为 Aftermath 生态注入订单流。

### 概览

**Builder Codes** 为基于 Aftermath Perpetuals 构建的集成商提供灵活的费用分成机制。系统运作如下：

1. **集成商注册**：集成商全局注册一次，获得一个数字 `integratorId`
2. **用户授权**：用户批准特定集成商，并设定自己愿意支付的费用上限
3. **订单提交**：集成商代用户提交订单，并指定收取的费用（不超过已批准的上限）

与推荐码不同，Builder Codes 作为链上费用逻辑的一部分实时生效。

{% hint style="info" %}
\*\*变更：\*\*集成商现在以数字 `integratorId` 标识，而非地址，且注册是一次性的全局步骤。之前的按市场费用金库模型——为每个市场创建金库并领取累计费用——已被移除。
{% endhint %}

### 工作原理

#### 对用户

用户对哪些集成商可以从其订单中收费拥有完全控制权：

* 批准集成商，并为每个集成商设置费用上限
* 随时撤销授权
* 为不同集成商设置不同的费用上限

#### 对集成商

集成商在开始收费前完成一次性全局设置：

1. 注册为集成商——全局一次，无需按市场注册
2. 让用户批准自己，每位用户设定一个费用上限
3. 提交携带 `integratorId` 和收费金额的订单

无需创建金库，也没有领取步骤。注册只是把集成商的全局地址记录到永续合约注册表之下，该地址可以随时更新而不丢失 `integratorId`。

#### 费用结构

* 集成商费用在常规交易费**之外**加收——用户批准的上限只约束这笔附加费用
* 费用按成交的名义价值计收，并跟随订单：订单立即作为吃单方 (Taker) 成交时适用，**且**订单挂在订单簿上、之后作为挂单方 (Maker) 成交时同样适用
* 费用以小数形式表示：`0.0005` 即 0.05% 的费率
* 单笔订单的费用不得超过用户为该集成商批准的 `maxIntegratorFee`——携带更高费用的订单，或来自用户未批准的集成商的收费订单，会在链上被拒绝
* 协议对任何集成商费用强制执行 **1.00%** 的硬性上限

### 面向开发者

\*\*TypeScript。\*\*我们已将全部所需的 Builder Codes 功能集成进 TypeScript SDK，并在文档中详细说明了所有函数。

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

\*\*API。\*\*关于如何通过 API 使用 Builder Codes 的更多信息，请查阅我们的 API 参考。

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

#### API 端点

所有 Builder Codes 端点都接受携带 JSON 请求体的 POST 请求。基础 URL：`https://v2-preview.aftermath.finance`

读取注册信息和按账户的授权：

* `/api/perpetuals/builder-codes/integrator-registration` — 将 `integratorId` 解析为其注册的 `integratorAddress`
* `/api/perpetuals/builder-codes/integrator-config` — 接收 `accountId` 和 `integratorId`，返回 `{ exists, maxIntegratorFee }`

构建用于设置和授权的交易：

* `/api/perpetuals/builder-codes/transactions/create-integrator-registration` — 一次性全局注册，由集成商签名
* `/api/perpetuals/builder-codes/transactions/create-integrator-config` — 用户批准某集成商并设置费用上限
* `/api/perpetuals/builder-codes/transactions/remove-integrator-config` — 用户撤销某集成商

示例：注册为集成商

```
## 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
}
```

集成商的身份在链上取自交易发送方，因此请求体中不需要地址。每个 Builder Codes 交易路由上，`txKind`（用于扩展已有交易）和 `sponsor`（用于 Gas 池代付）均为可选。

示例：用户以 0.05% 的上限批准某集成商

```
## 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
}
```

批准后，在为该用户提交的每笔订单上附加 Builder Code：

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

SL/TP 和止损触发单接受各自独立的 `builderCode`，与父订单的互不影响。

#### 交易流程

所有交易端点都返回序列化的交易类型（transaction kind）。链上执行步骤：

1. 携带参数调用交易端点
2. 从 JSON 响应中读取 `txKind`
3. 使用 Sui SDK 从 `txKind` 构建 `Transaction`
4. 用您的钱包签署交易
5. 提交到 Sui 网络

如果传入了 `sponsor`，响应还会携带 `sponsorSignature`。此时 `txKind` 存放的是 base64 BCS 编码的 `Transaction` 字节，Gas 支付已附加——签署这些字节并与代付方签名一起提交即可。

#### 集成方式

集成 Builder Codes 有三种方式：

* 原生 API（`/api/perpetuals/*`）— 推荐。功能最全，涵盖注册、授权和交易构建器。
* TypeScript SDK（`@aftermath-finance/sdk`）— 为 Builder Codes 操作提供类型化辅助方法。最适合 TypeScript 应用。
* CCXT 兼容 API（`/api/ccxt/*`）— 交易所风格的端点，适合遵循 CCXT 标准的机器人集成。