Builder Codes API - QFEX API Documentation

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

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

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.

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:

{
  "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.

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.

{
  "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:

{
  "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 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 channel
REST GET /user/positions balance object

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

​Create a builder code

​View your builder code

​Use a builder code on the Trade WebSocket

​Builder rewards

Create a builder code

View your builder code

Use a builder code on the Trade WebSocket

Builder rewards