Order Entry — Add TWAP - QFEX API Documentation

TWAP order entry is performed over WebSocket.

Endpoint: wss://trade.qfex.com?api_key=YOUR_API_KEY
Authenticate within 1 minute of connecting.

1) Authenticate

Send this immediately after you connect:

{ "type": "auth", "params": { "hmac": { "public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..." } } }

2) Add TWAP

{
  "type": "add_twap",
  "params": {
    "symbol": "AAPL-USD",
    "side": "BUY",
    "total_quantity": 10,
    "num_orders": 5,
    "order_interval_secs": 30,
    "reduce_only": false,
    "client_twap_id": "rebalance-aapl-001",
    "start_time": 1785499200.25,
    "worst_price": 250
  }
}

Parameters

Field	Type	Required	Description
`symbol`	string	✅	The market symbol (for example `AAPL-USD`).
`side`	enum	✅	TWAP direction. See OrderDirection.
`total_quantity`	number	✅	Total quantity to execute across the full TWAP. It is validated against the symbol’s minimum child-order size requirement.
`num_orders`	number	✅	Number of child orders the engine will schedule.
`order_interval_secs`	number	✅	Delay in seconds between child orders.
`reduce_only`	bool	✅	If `true`, the TWAP may only reduce an existing position.
`client_twap_id`	string	Optional	Optional client-assigned TWAP identifier for tracking and cancellation.
`start_time`	number	Optional	Unix timestamp in seconds, with optional fractional precision, at which the first child order may be placed. If omitted or in the past, execution starts immediately.
`worst_price`	number	Optional	Exact IOC limit price used for every child order: the maximum execution price for buys or minimum execution price for sells. If omitted, the limit is calculated from the mark price.

⚠️ Notes:

TWAP orders are submitted to trade.qfex.com using the add_twap incoming message.

A successful TWAP is returned as twap_response and also appears in all_orders_response.twaps.

TWAPs can be cancelled with cancel_order using cancel_order_id_type set to twap_id or client_twap_id.

The account must satisfy the same T&C requirements as standard order entry.

Validation Rules

The server validates add_twap requests before forwarding them to the TWAP service.

Rule	Behavior
Symbol must be active	Inactive or unknown symbols are rejected.
`order_interval_secs >= 30`	The minimum interval is 30 seconds.
`num_orders >= 2`	A TWAP must contain at least 2 child orders.
`total_quantity / num_orders >= min_quantity`	The average child order size must not fall below the symbol’s `min_quantity`.
`client_twap_id` length	If provided, it must be within the same configured min/max length limits used for `client_order_id`.
`start_time` format	If provided, it must be a finite Unix timestamp in seconds within the supported protobuf timestamp range. A past timestamp is treated as the current time.
`worst_price` price bounds	If provided, it must be finite and within the permitted price bounds: no greater than the symbol maximum for buys, and no lower than the symbol minimum or greater than the platform maximum for sells.
`worst_price` tick alignment	If provided, it must align with the symbol’s `tick_size`.

Additional implementation notes:

total_quantity is scaled using the symbol quantity precision before validation.
The current validation shown here does not document any explicit requirement that total_quantity align to lot_size, only that the average child size is not below min_quantity.
Errors from local validation are returned as err with error_code: "invalid_parameter" and a descriptive message.

Sample Code

# Python (websocket-client)
# pip install websocket-client
import json
import websocket

def send(ws, obj):
    ws.send(json.dumps(obj))

def on_open(ws):
    send(ws, {"type": "auth", "params": { "hmac": { "public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..." }}})
    send(ws, {
        "type": "add_twap",
        "params": {
            "symbol": "AAPL-USD",
            "side": "BUY",
            "total_quantity": 10,
            "num_orders": 5,
            "order_interval_secs": 30,
            "reduce_only": False,
            "client_twap_id": "rebalance-aapl-001",
            "start_time": 1785499200.25,
            "worst_price": 250
        }
    })

ws = websocket.WebSocketApp(
    "wss://trade.qfex.com?api_key=YOUR_API_KEY",
    on_open=on_open,
    on_message=lambda _, m: print(m),
)
ws.run_forever()

// Node.js (ws)
// npm i ws
import WebSocket from "ws";

const ws = new WebSocket("wss://trade.qfex.com?api_key=YOUR_API_KEY");

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "auth",
    params: {
      hmac: {
        public_key: "qfex_pub_xxxxx",
        nonce: "c0ffee...",
        unix_ts: 1760545414,
        signature: "5f2e...",
      },
    },
  }));

  ws.send(JSON.stringify({
    type: "add_twap",
    params: {
      symbol: "AAPL-USD",
      side: "BUY",
      total_quantity: 10,
      num_orders: 5,
      order_interval_secs: 30,
      reduce_only: false,
      client_twap_id: "rebalance-aapl-001",
      start_time: 1785499200.25,
      worst_price: 250,
    },
  }));
});

ws.on("message", (m) => console.log(m.toString()));

// Go (gorilla/websocket)
package main

import (
	"log"

	"github.com/gorilla/websocket"
)

func mustWriteJSON(c *websocket.Conn, v any) {
	if err := c.WriteJSON(v); err != nil {
		log.Fatal("write:", err)
	}
}

func main() {
	c, _, err := websocket.DefaultDialer.Dial("wss://trade.qfex.com?api_key=YOUR_API_KEY", nil)
	if err != nil {
		log.Fatal("dial:", err)
	}
	defer c.Close()

	mustWriteJSON(c, map[string]any{
		"type": "auth",
		"params": map[string]any{"hmac": map[string]any{"public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..."}},
	})

	mustWriteJSON(c, map[string]any{
		"type": "add_twap",
		"params": map[string]any{
			"symbol":              "AAPL-USD",
			"side":                "BUY",
			"total_quantity":      10,
			"num_orders":          5,
			"order_interval_secs": 30,
			"reduce_only":         false,
			"client_twap_id":      "rebalance-aapl-001",
			"start_time":          1785499200.25,
			"worst_price":         250,
		},
	})
}

// Java (OkHttp WebSocket)
import java.util.concurrent.TimeUnit;
import okhttp3.*;

public class AddTwapWs {
  public static void main(String[] args) {
    OkHttpClient client = new OkHttpClient.Builder()
        .pingInterval(20, TimeUnit.SECONDS)
        .build();

    Request req = new Request.Builder()
        .url("wss://trade.qfex.com?api_key=YOUR_API_KEY")
        .build();

    WebSocketListener li = new WebSocketListener() {
      @Override public void onOpen(WebSocket ws, Response r) {
        ws.send("{\"type\":\"auth\",\"params\":{\"hmac\":{\"public_key\":\"qfex_pub_xxxxx\",\"nonce\":\"c0ffee...\",\"unix_ts\":1760545414,\"signature\":\"5f2e...\"}}}");
        ws.send("{\"type\":\"add_twap\",\"params\":{\"symbol\":\"AAPL-USD\",\"side\":\"BUY\",\"total_quantity\":10,\"num_orders\":5,\"order_interval_secs\":30,\"reduce_only\":false,\"client_twap_id\":\"rebalance-aapl-001\",\"start_time\":1785499200.25,\"worst_price\":250}}");
      }

      @Override public void onMessage(WebSocket ws, String text) {
        System.out.println(text);
      }
    };

    client.newWebSocket(req, li);
    try { Thread.sleep(Long.MAX_VALUE); } catch (InterruptedException ignored) {}
  }
}

TWAP Response Shape

Successful TWAP requests are returned as a twap_response object:

{
  "twap_response": {
    "twap_id": "0c7c8e4d-f67e-4aa5-9c64-36a1a622ac35",
    "client_twap_id": "rebalance-aapl-001",
    "user_id": "0020ce8e-eaee-480e-8d7f-b9241d756ee5",
    "status": "ENGINE_STATUS",
    "symbol": "AAPL-USD",
    "total_quantity": 10,
    "filled_quantity": 0,
    "average_fill_price": 0,
    "worst_price": 250,
    "total_num_orders": 5,
    "order_interval_secs": 30,
    "reduce_only": false,
    "side": "BUY",
    "start_time": 1785499200.25,
    "updated_at": 1760545414.123,
    "created_at": 1760545414.123
  }
}

Field	Type	Description
`twap_id`	string	Server-generated TWAP identifier.
`client_twap_id`	string or null	Optional client-provided TWAP identifier.
`user_id`	string	Account identifier for the TWAP owner.
`status`	string	Current engine status for the TWAP.
`symbol`	string	Market symbol.
`total_quantity`	number	Total requested quantity across the TWAP.
`filled_quantity`	number	Quantity already filled.
`average_fill_price`	number	Average execution price across all fills so far.
`worst_price`	number or null	Configured IOC limit price for every child order, or `null` when the limit is calculated from the mark price.
`total_num_orders`	number	Total number of scheduled child orders.
`order_interval_secs`	number	Interval between child orders in seconds.
`reduce_only`	bool	Whether the TWAP is reduce-only.
`side`	enum	TWAP direction.
`start_time`	number or null	Effective scheduled start time as Unix seconds with fractional precision. Omitted or past request values are returned as the time at which the TWAP was accepted.
`updated_at`	number or null	Last update timestamp in seconds with fractional precision.
`created_at`	number or null	Creation timestamp in seconds with fractional precision.