positions 频道以接收持仓快照,每个交易品种对应一个 position_response。系统每 60 秒定期发布快照,并在成交、资金费用、保证金变化及订单保证金预留变化后发送额外的事件驱动更新。
更新时机与初始快照
新订阅建立后,网关发送{"subscribed":"positions"},并立即为每个已缓存持仓将一条 position_response 加入发送队列,无需等待下一次定期刷新。若没有缓存持仓,则在持仓数据可用之前仅发送订阅确认。
订单保证金预留更新按账户以约一秒的频率合并;其他账户事件可能更早触发快照。投递为异步方式,不保证每笔订单对应一条消息。60 秒是定期刷新间隔,并非最大投递延迟保证。
1. 身份认证
{
"type": "auth",
"params": {
"hmac": {
"public_key": "qfex_pub_xxxxx",
"nonce": "c0ffee...",
"unix_ts": 1760545414,
"signature": "5f2e..."
}
}
}
2. 订阅
{ "type": "subscribe", "params": { "channels": ["positions"] } }
示例代码
# Python (websocket-client)
import json, websocket
API_KEY = "YOUR_API_KEY"
def send(ws, obj): ws.send(json.dumps(obj))
def on_open(ws):
# 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..." }}})
send(ws, {"type": "subscribe", "params": {"channels": ["positions"]}})
ws = websocket.WebSocketApp(
"wss://trade.qfex.com?api_key=YOUR_API_KEY",
on_open=on_open,
on_message=lambda _, m: print("Message:", m),
)
ws.run_forever()
// Node.js (ws)
import WebSocket from "ws";
const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket("wss://trade.qfex.com?api_key=YOUR_API_KEY");
ws.on("open", () => {
ws.send(JSON.stringify({ type: "auth", params: { api_key: API_KEY } }));
ws.send(
JSON.stringify({ type: "subscribe", params: { channels: ["positions"] } })
);
});
ws.on("message", (msg) => console.log("Message:", msg.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": "subscribe",
"params": map[string]any{"channels": []string{"positions"}},
})
for {
_, data, err := c.ReadMessage()
if err != nil { log.Fatal("read:", err) }
log.Println(string(data))
}
}
// Java (OkHttp WebSocket)
import java.util.concurrent.TimeUnit;
import okhttp3.*;
public class PositionsSub {
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\":\"subscribe\",\"params\":{\"channels\":[\"positions\"]}}");
}
@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) {}
}
}
响应示例
{ "subscribed": "positions" }
{
"position_response": {
"id": "c003ad60-ded4-401b-9b4c-e255a53d32ea",
"symbol": "AAPL-USD",
"position": 0.0,
"margin_alloc": 0.0,
"realised_pnl": 0.0,
"unrealised_pnl": 0.0,
"net_funding": 0.0,
"open_orders": 0.0,
"open_quantity": 0.0,
"leverage": 20.0,
"initial_margin": 0.05,
"maintenance_margin": 0.03333333333333333,
"average_price": 0.0
}
}
初始、定期及事件驱动更新均使用
position_response。每条消息替换该品种的持仓状态;它不是增量,也不是所有持仓的完整列表。旧版 position_update/v4_positions 消息封装不适用于 wss://trade.qfex.com。