> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder Codes API

> 创建与查询 Builder Code、附加到交易 WebSocket 会话并读取开发者奖励

Builder Code 及手续费分成机制概览见 [Builder Codes](https://docs.qfex.com/cn/qfex/builder-code.md)。

若您正在构建聚合器、交易终端或其他需要认证终端用户并自动归因其交易的应用，请先阅读[开发者集成指南](https://docs.qfex.com/cn/api-reference/builder-integration.md)。若要通过钱包签名获得主账户交易密钥，请使用 [Builder 钱包注册](https://docs.qfex.com/cn/api-reference/builder-wallet-registration.md)。

## 创建 Builder Code

每个 QFEX 账户最多拥有**一个有效的 Builder Code**。聚合器通常为自己的账户创建一个代码，并在所有终端用户的交易 WebSocket 连接上复用同一 UUID。不要为每位交易者创建一个代码。

调用 `POST /user/builder-code`，必须提供 HMAC 请求头。已有有效代码时再次创建，返回 **409 Conflict**。

以基点为单位指定两项手续费分成：

* `qfex_fee_share_bps`：QFEX 的手续费分成，最低 **5000**（50%）。
* `builder_fee_share_bps`：开发者的手续费分成，必须**大于或等于 0**，且不超过 **5000**（50%）。
* 两项之和不必等于 10000，但不得超过 10000。

```http theme={null}
POST /user/builder-code
x-qfex-public-key: qfex_pub_xxxxx
x-qfex-hmac-signature: 5f2e...
x-qfex-nonce: c0ffee...
x-qfex-timestamp: 1760545414
Content-Type: application/json

{
  "qfex_fee_share_bps": 5000,
  "builder_fee_share_bps": 3000
}
```

**201** 响应示例：

```json theme={null}
{
  "builder_code": "11111111-1111-4111-8111-111111111111",
  "qfex_fee_share_bps": 5000,
  "qfex_fee_share_percent": 50.0,
  "builder_fee_share_bps": 3000,
  "builder_fee_share_percent": 30.0,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-09-01T12:00:00Z"
}
```

## 查询 Builder Code

使用 `GET /user/builder-code` 获取当前已认证用户的有效 Builder Code 及其分成配置。用户尚未创建有效代码时，返回 **404**。

```http theme={null}
GET /user/builder-code
x-qfex-public-key: qfex_pub_xxxxx
x-qfex-hmac-signature: 5f2e...
x-qfex-nonce: c0ffee...
x-qfex-timestamp: 1760545414
```

在集成配置中保存返回的 `builder_code` UUID，并在需要归因的交易 WebSocket 连接认证时附加。不要将其放在单个订单消息上。

## 在交易 WebSocket 上使用 Builder Code

Builder Code 应放在交易 WebSocket 的**身份认证消息**中，并对整条连接生效。

### HMAC 认证

使用 API 公开密钥连接：

```text theme={null}
wss://trade.qfex.com?api_key=YOUR_PUBLIC_KEY
```

随后在一分钟内完成认证，并在 HMAC 对象旁添加 `builder_code`：

```json theme={null}
{
  "type": "auth",
  "params": {
    "hmac": {
      "public_key": "qfex_pub_xxxxx",
      "nonce": "c0ffee...",
      "unix_ts": 1760545414,
      "signature": "5f2e..."
    },
    "builder_code": "11111111-1111-4111-8111-111111111111"
  }
}
```

### JWT 或 OAuth 认证

使用 QFEX 用户 JWT（包括经 QFEX OAuth 获取的令牌）认证时，将 JWT 作为查询参数建立连接：

```text theme={null}
wss://trade.qfex.com/?jwt=URL_ENCODED_JWT
```

随后在认证消息中发送同一个 JWT 及 Builder Code：

```json theme={null}
{
  "type": "auth",
  "params": {
    "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "builder_code": "11111111-1111-4111-8111-111111111111"
  }
}
```

若会话需要在子账户交易，可在同一认证载荷中添加可选的 `account_id`。

浏览器 WebSocket API 无法设置自定义握手请求头，因此建议通过 `params.builder_code` 传递代码。原生客户端也可以在 WebSocket 升级请求中发送 `x-qfex-builder-code`；如果认证消息同时提供 `builder_code`，则以认证消息为准。

代码在该连接的整个生命周期内生效。要修改或移除代码，请重连并重新认证。通过该连接提交的普通订单、触发单和 TWAP 订单会自动继承 Builder Code。

如果代码缺失、为空、未激活或不存在，则不归因任何 Builder 奖励。

HMAC 签名及完整客户端示例见[身份认证](https://docs.qfex.com/cn/websocket/channels/trade/authenticate.md)，端到端 OAuth 流程见[开发者集成指南](https://docs.qfex.com/cn/api-reference/builder-integration.md)。

## Builder 奖励

已入账的开发者分成，以 `builder_rewards` 字段显示在 Builder Code 所有者的公开用户余额对象中，可通过以下方式读取：

* 交易 WebSocket 的[余额](https://docs.qfex.com/cn/websocket/channels/trade/balance.md)频道；
* REST `GET /user/positions` 的余额对象。

交易者自己的余额不会显示开发者的分成。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.