> ## 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. # Order Entry — Add TWAP 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: ```json theme={null} { "type": "auth", "params": { "hmac": { "public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..." } } } ``` ## 2) Add TWAP ```json theme={null} { "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](/api-reference/enums#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 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 python theme={null} # 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() ``` ```javascript node theme={null} // 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", }, })); }); ws.on("message", (m) => console.log(m.toString())); ``` ```go go theme={null} // 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", }, }) } ``` ```java java theme={null} // 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\"}}"); } @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: ```json theme={null} { "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. |