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

> Create and retrieve builder codes, attach them to Trade WebSocket sessions, and read builder rewards

For an overview of builder codes, fee-share mechanics, and how to create a code in the QFEX dashboard, see [Builder Codes](/qfex/builder-code).

<Info>
  Builder codes are not yet released. This page will be updated once this is
  available.
</Info>

## Create a builder code

Each user may create **one** builder code.

`POST /user/builder-code`. HMAC headers are required. A second create returns **409 Conflict**.

Specify both fee shares in basis points:

* `qfex_fee_share_bps`: QFEX's share of the trading fee. Minimum **5000** (50%).
* `builder_fee_share_bps`: the builder's share of the trading fee. Must be **>= 0** and at most **5000** (50%).
* The two shares need not sum to 10000, but their sum must be at most 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
}
```

Example **201** response:

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

## View your builder code

Use `GET /user/builder-code` to retrieve the authenticated user's builder code and configured fee shares. If the user has not created a code yet, the API returns **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
```

Share the returned `builder_code` UUID with users or embed it in your client. Do not put it on individual order messages.

## Use a builder code on the Trade WebSocket

Connect to `wss://trade.qfex.com?api_key=YOUR_PUBLIC_KEY` and authenticate within one minute. Add `builder_code` next to `hmac` or `jwt` on the auth message. Browser WebSocket APIs cannot set custom handshake headers, so the auth message is the supported way to attach a 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"
  }
}
```

With JWT:

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

You can still include optional `account_id` on the same auth payload if the session should trade on a subaccount.

The code applies for the life of that connection. Reconnect and send auth again to change or drop it. Native clients may send `x-qfex-builder-code` on the WebSocket upgrade instead; if the auth message also includes `builder_code`, the auth message wins.

Orders, stop orders, and TWAPs placed on that connection inherit the builder code. If the code is missing, empty, or unknown, no builder rewards are attributed.

See [Authenticate](/websocket/channels/trade/authenticate) for HMAC signing and full client samples.

## Builder rewards

Credited builder share is exposed as `builder_rewards` on the builder-code owner's public user balance.

* Trade WebSocket [balances](/websocket/channels/trade/balance) channel
* REST `GET /user/positions` balance object

The trader's balance does not show the builder's share.