- 接口:
wss://trade.qfex.com?api_key=YOUR_API_KEY。 - 连接后必须在 1 分钟内完成身份认证。
1. 身份认证
连接后立即发送:{ "type": "auth", "params": { "hmac": { "public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..." } } }
2. 取消订单
可以按order_id、client_order_id、twap_id 或 client_twap_id 取消。将标识符填入 order_id 字段,并用 cancel_order_id_type 指定如何解释该值。
order_id:始终是唯一的 UUID v4,只取消一笔订单。client_order_id:不保证唯一,会取消该品种中具有相同客户端订单 ID 的全部订单。twap_id:服务器生成的 TWAP ID,取消匹配的 TWAP。client_twap_id:客户端提供的 TWAP ID,取消该品种中匹配的 TWAP。
按订单 ID 取消单笔订单
{
"type": "cancel_order",
"params": {
"order_id": "REPLACE_WITH_ORDER_UUID_V4",
"symbol": "AAPL-USD",
"cancel_order_id_type": "order_id"
}
}
按客户端订单 ID 取消,可能影响多笔订单
{
"type": "cancel_order",
"params": {
"order_id": "my-client-oid-123",
"symbol": "AAPL-USD",
"cancel_order_id_type": "client_order_id"
}
}
按 TWAP ID 取消
{
"type": "cancel_order",
"params": {
"order_id": "0c7c8e4d-f67e-4aa5-9c64-36a1a622ac35",
"symbol": "AAPL-USD",
"cancel_order_id_type": "twap_id"
}
}
按客户端 TWAP ID 取消
{
"type": "cancel_order",
"params": {
"order_id": "rebalance-aapl-001",
"symbol": "AAPL-USD",
"cancel_order_id_type": "client_twap_id"
}
}
参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
order_id | string | 视取消模式而定 | cancel_order_id_type = "order_id" 时为订单的 UUID v4,只取消一笔订单。四种模式均将标识符实际放在此字段。 |
client_order_id | string | 客户端 ID 模式需要此标识符 | 客户端指定的订单 ID;按客户端 ID 取消时可能影响多笔订单。请依照上方示例将其值放入请求的 order_id 字段。 |
symbol | string | 是 | 订单对应的交易品种,例如 AAPL-USD。 |
cancel_order_id_type | enum | 是 | 必须为 "order_id"、"client_order_id"、"twap_id" 或 "client_twap_id",用于指定引擎如何解释 ID。 |
- 四种模式均将标识符放入
order_id。引擎根据cancel_order_id_type判断其属于订单 ID、客户端订单 ID、TWAP ID 还是客户端 TWAP ID。 - 订单 ID 始终唯一,格式为 UUID v4。
- 客户端订单 ID 不保证唯一,可能取消同一品种的多笔订单。
twap_id和client_twap_id用于取消 TWAP。- 响应包含 OrderStatus 状态码,例如
CANCELLED、NO_SUCH_ORDER或REJECTED。
示例代码
# Python (websocket-client)
# pip install websocket-client
import json
import websocket
API_KEY = "YOUR_API_KEY"
ORDER_ID = "REPLACE_WITH_ORDER_UUID_V4" # for order_id flow
CLIENT_OID = "my-client-oid-123" # for client_order_id flow
def send(ws, obj):
ws.send(json.dumps(obj))
def on_open(ws):
# 1) Authenticate
# https://docs.qfex.com/websocket/channels/trade/authenticate#how-it-works
send(ws, {"type": "auth", "params": { "hmac": { "public_key": "qfex_pub_xxxxx", "nonce": "c0ffee...", "unix_ts": 1760545414, "signature": "5f2e..." }}})
# 2a) Cancel by order_id (exactly one order)
send(ws, {
"type": "cancel_order",
"params": {
"order_id": ORDER_ID,
"symbol": "AAPL-USD",
"cancel_order_id_type": "order_id"
}
})
# 2b) Cancel by client_order_id (may cancel multiple)
# send(ws, {
# "type": "cancel_order",
# "params": {
# "client_order_id": CLIENT_OID,
# "symbol": "AAPL-USD",
# "cancel_order_id_type": "client_order_id"
# }
# })
ws = websocket.WebSocketApp(
"wss://trade.qfex.com?api_key=YOUR_API_KEY",
on_open=on_open,
on_message=lambda _, m: print(m),
on_error=lambda _, e: print("Error:", e),
on_close=lambda *_: print("Closed"),
)
ws.run_forever()
// Node.js (ws)
// npm i ws
const WebSocket = require("ws");
const API_KEY = "YOUR_API_KEY";
const ORDER_ID = "REPLACE_WITH_ORDER_UUID_V4"; // for order_id flow
const CLIENT_OID = "my-client-oid-123"; // for client_order_id flow
const ws = new WebSocket("wss://trade.qfex.com?api_key=YOUR_API_KEY");
ws.on("open", () => {
// 1) Authenticate
ws.send(JSON.stringify({ type: "auth", params: { api_key: API_KEY } }));
// 2a) Cancel by order_id (exactly one order)
ws.send(
JSON.stringify({
type: "cancel_order",
params: {
order_id: ORDER_ID,
symbol: "AAPL-USD",
cancel_order_id_type: "order_id",
},
})
);
// 2b) Cancel by client_order_id (may cancel multiple)
// ws.send(JSON.stringify({
// type: "cancel_order",
// params: {
// client_order_id: CLIENT_OID,
// symbol: "AAPL-USD",
// cancel_order_id_type: "client_order_id"
// }
// }));
});
ws.on("message", (m) => console.log(m.toString()));
ws.on("error", (e) => console.error("WS error:", e));
ws.on("close", (code, reason) =>
console.log("Closed:", code, reason?.toString())
);
// Go (gorilla/websocket)
// go get github.com/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()
// 1) Authenticate
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..."}}
})
// 2a) Cancel by order_id (exactly one order)
mustWriteJSON(c, map[string]any{
"type": "cancel_order",
"params": map[string]any{
"order_id": "REPLACE_WITH_ORDER_UUID_V4",
"symbol": "AAPL-USD",
"cancel_order_id_type": "order_id",
},
})
// 2b) Cancel by client_order_id (may cancel multiple)
// mustWriteJSON(c, map[string]any{
// "type": "cancel_order",
// "params": map[string]any{
// "client_order_id": "my-client-oid-123",
// "symbol": "AAPL-USD",
// "cancel_order_id_type": "client_order_id",
// },
// })
}
// Java (OkHttp WebSocket)
// Gradle: implementation("com.squareup.okhttp3:okhttp:4.12.0")
import java.util.concurrent.TimeUnit;
import okhttp3.*;
public class CancelOrderWs {
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) {
// 1) Authenticate
ws.send("{\"type\": \"auth\", \"params\": { \"hmac\": { \"public_key\": \"qfex_pub_xxxxx\", \"nonce\": \"c0ffee...\..\", \"unix_ts\": 1760545414, \"signature\": \"5f2e...\" }}}");
// 2a) Cancel by order_id (exactly one order)
ws.send("{\"type\":\"cancel_order\",\"params\":{\"order_id\":\"REPLACE_WITH_ORDER_UUID_V4\",\"symbol\":\"AAPL-USD\",\"cancel_order_id_type\":\"order_id\"}}");
// 2b) Cancel by client_order_id (may cancel multiple)
// ws.send("{\"type\":\"cancel_order\",\"params\":{\"client_order_id\":\"my-client-oid-123\",\"symbol\":\"AAPL-USD\",\"cancel_order_id_type\":\"client_order_id\"}}");
}
@Override public void onMessage(WebSocket ws, String text) {
System.out.println(text);
}
@Override public void onFailure(WebSocket ws, Throwable t, Response r) {
System.err.println("WS error: " + t.getMessage());
}
};
client.newWebSocket(req, li);
try { Thread.sleep(Long.MAX_VALUE); } catch (InterruptedException ignored) {}
}
}
响应示例
下单返回ACK;撤单返回相同结构,但状态为 CANCELLED。
{
"order_response": {
"order_id": "5b309929-206f-40ec-804d-cbe46e81afc1",
"symbol": "AAPL-USD",
"status": "CANCELLED",
"quantity": 1.0,
"price": 200.0,
"take_profit": 0.0,
"stop_loss": 0.0,
"side": "BUY",
"type": "LIMIT",
"time_in_force": "GTC",
"user_id": "0020ce8e-eaee-480e-8d7f-b9241d756ee5",
"client_order_id": "",
"quantity_remaining": 1.0,
"trade_id": null
}
}