Skip to main content

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.

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

  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.
  5. 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.
{
  "type": "auth",
  "params": {
    "hmac": {
      "public_key": "qfex_pub_xxxxx", // Your public (API) key
      "nonce": "c0ffee...", // Secure random hex string
      "unix_ts": 1760545414, // Current Unix timestamp (seconds)
      "signature": "5f2e..." // Hex-encoded HMAC-SHA256(secret, "nonce:unix_ts")
    },
    // optional
    "account_id": "11111111-1111-1111-1111-111111111111"
  }
}
Alternatively, authenticate with a JWT: 
{
  "type": "auth",
  "params": {
    "jwt": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImNiYzVmZWNmLTlhODItNGFlNy04NDFkLTBkMTdjMjUzMWM3OCIsInR5cCI6IkpXVCJ9...",
    // optional
    "account_id": "11111111-1111-1111-1111-111111111111"
  }
}

​
Sample Code

# Python (websocket-client)
# pip install websocket-client
import hashlib
import hmac
import json
import secrets
import time

import websocket

PUB_KEY = "qfex_pub_xxxxx"
SECRET_KEY = "qfex_secret_yyyyyy"


def build_auth_message():
    nonce = secrets.token_hex(16)
    unix_ts = int(time.time())
    payload = f"{nonce}:{unix_ts}".encode()
    signature = hmac.new(SECRET_KEY.encode(), payload, hashlib.sha256).hexdigest()
    return {
        "type": "auth",
        "params": {
            "hmac": {
                "public_key": PUB_KEY,
                "nonce": nonce,
                "unix_ts": unix_ts,
                "signature": signature,
            }
        },
    }


def on_open(ws):
    ws.send(json.dumps(build_auth_message()))


def on_message(_, message):
    print("Message:", message)


def on_error(_, error):
    print("Error:", error)


def on_close(_, code, reason):
    print("Closed:", code, reason)


ws = websocket.WebSocketApp(
    "wss://trade.qfex.com?api_key=" + PUB_KEY,
    on_open=on_open,
    on_message=on_message,
    on_error=on_error,
    on_close=on_close,
)
ws.run_forever()

​
Example Response

{ "type": "auth", "result": "success" }
After the client successfully authenticates, the server keeps the connection alive by periodically sending heartbeat messages in the form of WebSocket ping frames.