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"
  }
}

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.

⚠️ 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 KYC and 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`.

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"
        }
    })

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()

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,
    "total_num_orders": 5,
    "order_interval_secs": 30,
    "reduce_only": false,
    "side": "BUY",
    "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.
`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.
`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.

API Documentation

REST API

WebSocket

​1) Authenticate

​2) Add TWAP

​Parameters

​Validation Rules

​Sample Code

​TWAP Response Shape