Builder Codes API

For an overview of builder codes and fee-share mechanics, see Builder Codes. If you are building an aggregator, trading terminal, or other application that needs to authenticate end users and attribute their trading automatically, start with the Builder Integration Guide. For wallet signatures that return main-account trading keys, use Builder wallet registration.

Create a builder code

Each QFEX account may have one active builder code. An aggregator normally creates one code for its own account and reuses that same UUID across its end-user Trade WebSocket connections. Do not create one builder code per trader. POST /user/builder-code. HMAC headers are required. A second active 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 active builder code and configured fee shares. If the user has not created an active code, 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

Store the returned builder_code UUID in your integration and attach it when authenticating attributed Trade WebSocket connections. Do not put it on individual order messages.

Use a builder code on the Trade WebSocket

The builder code belongs on the Trade WebSocket auth message. It applies to the entire connection.

HMAC authentication

Connect with your API public key:

wss://trade.qfex.com?api_key=YOUR_PUBLIC_KEY

Then authenticate within one minute and add builder_code next to the HMAC block:

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

JWT or OAuth authentication

When authenticating with a QFEX user JWT, including a token obtained through QFEX OAuth, connect with the JWT as the query parameter:

wss://trade.qfex.com/?jwt=URL_ENCODED_JWT

Then send the same JWT and your builder code in the auth message:

{
  "type": "auth",
  "params": {
    "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "builder_code": "11111111-1111-4111-8111-111111111111"
  }
}

You can include optional account_id on the same auth payload if the session should trade on a subaccount. Browser WebSocket APIs cannot set custom handshake headers, so params.builder_code is the recommended way to attach the code. 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. The code applies for the life of that connection. Reconnect and send auth again to change or drop it. Orders, stop orders, and TWAPs placed on that connection inherit the builder code automatically. If the code is missing, empty, inactive, or unknown, no builder rewards are attributed. See Authenticate for HMAC signing and full client samples, or Builder Integration Guide for the end-to-end OAuth flow.

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.

API Documentation

Builder Codes

REST API

Funding API

WebSocket

Create a builder code

View your builder code

Use a builder code on the Trade WebSocket

HMAC authentication

JWT or OAuth authentication

Builder rewards

​Create a builder code

​View your builder code

​Use a builder code on the Trade WebSocket

​HMAC authentication

​JWT or OAuth authentication

​Builder rewards

Create a builder code

View your builder code

Use a builder code on the Trade WebSocket

HMAC authentication

JWT or OAuth authentication

Builder rewards