> 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/zh/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%** 的硬性上限

{% hint style="warning" %}
**挂单成交同样赚取集成商费用。**[aftermath.finance/docs](https://aftermath.finance/docs) 上的 API 参考仍将 `integratorFee` 描述为“仅适用于吃单成交量”，并仍称集成商需要按市场设立金库。这两种说法均已过时，以本页为准。已部署的 Move ABI 可以印证这一点：[move-interfaces](https://github.com/AftermathFinance/move-interfaces) 中的 `perpetuals::events::FilledMakerOrder` 与 `FilledTakerOrder` 一样，携带 `integrator_id` 和 `integrator_fee_paid_usd`。
{% endhint %}

### 面向开发者

\*\*TypeScript。\*\*我们的 TypeScript SDK 包含 Builder Codes 授权相关函数，文档见下方。一次性的集成商注册需使用原生 API。

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

\*\*API。\*\*Builder Codes 端点请参阅我们的 API 参考。

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

#### API 端点

所有 Builder Codes 端点都接受携带 JSON 请求体的 POST 请求。基础 URL：`https://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://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`（用于 GasPool 代付）均为可选。sponsor 包含 `walletAddress`、`bytes` 和 `signature`，以及可选的以 MIST 计的 `gasBudget`；`bytes` 是可复用的 `Aftermath Terms and Conditions` 消息的 base64 编码。

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

```
## Request
POST https://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-ts-sdk`）：为 Builder Codes 授权提供类型化辅助方法。一次性注册需使用原生 API。
* CCXT 兼容 API（`/api/ccxt/*`）：交易所风格的端点，适合遵循 CCXT 标准的机器人集成。
