Skip to main content
Connections to trade.qfex.com require authentication. You must authenticate within 1 minute of connecting or the server will close the connection. Authentication uses an HMAC-SHA256 signature or a valid JWT token.

How it works

HMAC

  1. Connect to wss://trade.qfex.com?api_key=YOUR_PUBLIC_KEY.
  2. Generate a cryptographically secure random nonce (hex encoded, max 100 characters) and capture the current Unix timestamp.
  3. Build the string ${nonce}:${unix_ts} and compute an HMAC-SHA256 using your secret key. Hex-encode the result to get the signature.
  4. Send the auth payload with the hmac block shown below. The nonce must be unique within a 15 minute window.

JWT

For a JWT session, including a token obtained through QFEX OAuth, connect with the JWT as the query parameter:
Then authenticate with the same JWT:
If you want the authenticated Trade WebSocket session to use a subaccount, include an optional account_id field alongside either hmac or jwt. When omitted, the connection uses the primary account.

Builder attribution

To attribute trading fees to a builder, include optional builder_code on the same auth payload. The builder code is a UUID created by the builder in Developer Settings or through the Builder Codes API.
The code applies for the life of the connection. Orders, stop orders, and TWAPs sent over the connection inherit it automatically. Do not include the builder code on every individual order. Browser WebSocket clients cannot set custom handshake headers, so params.builder_code is the supported way to attach it. See the Builder Integration Guide for the full OAuth-to-trading flow.

Sample Code

Example Response

After the client successfully authenticates, the server keeps the connection alive by periodically sending heartbeat messages in the form of WebSocket ping frames.