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.
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. |
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. |
