永久查詢和分頁

本指南針對 Agent Java SDK v0.3.0、Java 8+ 以及標記的公共合約。初始化 client 後在合作伙伴後端運行示例 快速入門.

先決條件示例

Java 片段共享這些導入。使用快速啟動初始化 client 並從保存的綁定中獲取 platformUserId。示例用戶/訂單 ID 必須替換為您自己的持久值。

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

查詢永續合約數據

六種接口和Java方法

所有請求均使用公共前綴 /v1/agent/perpetual 進行簽名 POST。

platformUserIds 是公共平臺 ID 的字符串數組。如果指定，則需要 1 到 100 名具有訪問權限的唯一玩家；在允許省略的端點上，僅查詢當前商戶可以訪問的直接玩家範圍。交易填充查詢始終需要此數組；條件順序查詢還需要顯式的用戶 ID。省略不等於[]，空數組是非法的。範圍由簽約商戶決定，不能通過其他商戶ID來擴大範圍。

在加入簽名有效負載之前，數組值被序列化為緊湊的 JSON。例如，platformUserIds 標記為 ["1188041528"]，在 k=v 有效負載中給出 platformUserIds=["1188041528"]。保留數組元素順序、雙引號和字符串 ID；請勿插入格式空格或使用 Java List.toString()（例如 [1188041528]）。 SDK 自動處理此序列化。

訂單查詢必須通過orderCategory=NORMAL或CONDITIONAL。普通訂單使用 orderId，條件訂單使用 conditionId。它們不能跨類別混合。條件訂單和觸發條件訂單生成的普通訂單作為實體單獨處理。

過濾條件

歷史查詢的時間為Unix毫秒，間隔為[startTime, endTime)；請求籤名的時間是 timestamp 是 Unix 秒。建議固定UTC時間窗口，分段查詢；使用 UTC 進行日常核對。狀態和類型使用平臺合約枚舉，不會自行翻譯成中文字符串。

limit 默認為 500，範圍為 1~1000；頁面大小不保證每次都會返回相同的數字。目前6個接口共享每個商戶每秒2次、4個突發的查詢配額，實例內每個商戶最大併發數限制為2。商戶側採用統一隊列，建議從順序分頁和較小的歷史窗口開始。

Java 查詢示例

查詢玩家當前的普通訂單：

CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest();
current.orderCategory = "NORMAL";
current.platformUserIds = Collections.singletonList(platformUserId);
current.symbol = "BTCUSDT";
current.limit = 100;
PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current);

查詢最近一小時的合約變動情況並處理游標。以下示例不會自動重試；當實際應用遇到電流限制或暫時故障時，請按照鏈接的相關指南恢復相同頁面。

PerpetualLedgerRequest ledger = new PerpetualLedgerRequest();
ledger.platformUserIds = Collections.singletonList(platformUserId);
ledger.endTime = System.currentTimeMillis();
ledger.startTime = ledger.endTime - 3_600_000L;
ledger.limit = 100;
Set<String> seenCursors = new HashSet<>();
while (true) {
    PerpetualResponse page = client.listPerpetualLedger(ledger);
    for (PerpetualRecord row : page.data.items) {
        // Persist records idempotently by platformUserId, entityType and entityId.
    }
    if (!page.data.hasMore) {
        break;
    }
    String next = page.data.nextCursor;
    if (next == null || next.isEmpty() || !seenCursors.add(next)) {
        throw new IllegalStateException("游标未推进，停止查询并排查");
    }
    ledger.cursor = next;
    Thread.sleep(650L); // Other queries must share the same partner rate-limit queue.
}

返回結構和保存規則

看 通用響應和分頁 對於共享字段。資源字段記錄在 訂單, 貿易填補, 職位 和 合同臺賬.

六個接口統一返回PerpetualResponse：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "nextCursor": "",
    "hasMore": false
  }
}

每個 items 包含 platformUserId、entityType、entityId、data。實體類型包括 ORDER、CONDITION_ORDER、TRADE_FILL、POSITION、ACCOUNT_LEDGER。使用這三個身份字段構建冪等密鑰；請勿將條件訂單 ID、訂單 ID 和填寫 ID 視為相同的數字。

data 提供價格、數量、狀態、費用、損益或按資源的餘額變化等字段。金額、價格、數量、實體ID作為字符串處理；業務時間以毫秒為單位。缺失的字段不會填充為 0，也不會從其他實體推斷出來。

游標是查詢的分頁位置，不是可靠的增量訂閱，也不是有保證的跨頁原子快照。當前光標自第一輪生成起24小時內有效；後續分頁保留相同的商家、資源、玩家收藏和過濾條件。歷史拉取固定窗口，重複拉取時冪等；重新查詢後刷新當前訂單/持倉狀態。當需要實時接口時，採用平臺前端的數據機制，輪詢六接口不能視為高頻行情接口。

錯誤和恢復

HTTP成功並不代表事業成功，您必須勾選code。 Java SDK 將引發業務錯誤，如 AgentApiException。

限流、超時或臨時失效後，cursor及原失效頁面的所有過濾條件將被保留；每次重新調用 SDK 時，都會生成新的 timestamp、nonce、sign。不能直接跳轉到下一頁，也不能將失敗視為空結果。 SDK 不負責自動重試資金交易。

通用響應和分頁

每個data.items[]的結構：

同一個ledgerId可以分離出手續費、盈虧等多個明細；按 ledgerId 刪除重複項將導致數據丟失。來自不同資源的 ID 不能混合。分頁和字段保存規則請參見《接入指南》鏈接相關指南。

類型、單位和省略字段

• 金額、價格、數量、實體ID使用字符串；使用十進制來處理金額，並且不能使用浮點數或將長 ID 轉換為 JavaScript 數字。金額幣種和數量單位根據交易對/合約規格說明。
• 業務時間使用整數（int64），均為Unix毫秒；請求認證時間戳和進入憑證expireAt使用秒，不能混淆。
• 字符串業務字段通常為空時不輸出，而數值字段為0時會省略一些。缺失字段並不代表業務值為0。
• 一般記錄模型中的 reduceOnly、closeOnly、makerOnly 不會省略 false，因此這三個 false 也可能出現在交易或持倉中。它們僅在訂單資源中進行說明；不能認為該筆交易/持倉已執行相應的訂單規則。
• closePosition 是一個可選的布爾值：由條件訂單提供，通常對於其他資源被省略。 Missing 與 false 有著不同的含義。
• 下表“當前提供”表示讀取邏輯有字段源；可選字段仍然可以被省略，因為它們沒有值。模型中存在的字段不保證在每個接口中都被填充。

狀態和保證金模式的區別

普通訂單的CANCELED的拼寫與條件訂單的CANCELLED的拼寫不同；觸發條件訂單並不意味著生成的普通訂單已被成交。不要對所有資源重複使用同一組狀態轉換表。

條件訂單 marginMode 返回 CROSS / ISOLATED;歷史普通訂單和倉位目前返回“1”/“2”，分別為全倉/逐倉保證金。 marginMode目前不適用於普通訂單。商家可以在自己的展示層按資源進行歸一化，原始值仍需保存。

模型中聲明但未在此查詢中提供的字段

Generic RecordData / Java PerpetualData 模型還聲明瞭以下字段，但當前的六類生產讀取邏輯不會填充它們。 **不應列為可用業務數據，也不應使用字段默認值來替代實際結果。 **

實際現場應用範圍以上述資源表為準；當平臺更新字段或枚舉時，應根據新的接口描述和SDK版本進行適配。

來源及相關指南

• 官方v0.3.0源碼
• 資金錢包
• 升級指南