合约查询与分页

本文对应 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 方法

全部使用签名 POST 请求，公共前缀为 /v1/agent/perpetual。

platformUserIds 是公开平台 ID 的字符串数组，指定时需 1～100 个不重复且有权访问的玩家；对于允许省略的接口，省略时仅查询当前商户有权访问的直属玩家范围。成交查询始终必须传入该数组，条件委托查询也必须明确指定玩家 ID。省略与 [] 不等价，空数组非法。范围由签名商户确定，不能传其他商户 ID 扩大范围。

数组值参与签名前先序列化为紧凑 JSON。例如，platformUserIds 使用 ["1188041528"]，签名原文中的键值片段为 platformUserIds=["1188041528"]。保留数组元素顺序、双引号和字符串 ID，不插入格式化空格，不使用 Java List.toString()（例如 [1188041528]）。SDK 自动完成该序列化。

委托查询必传 orderCategory=NORMAL 或 CONDITIONAL。普通委托使用 orderId，条件委托使用 conditionId，不能跨类别混用。条件单与其触发生成的普通委托分别按实体处理。

过滤条件

历史查询的时间为 Unix 毫秒，区间为 [startTime, endTime)；请求签名的 timestamp 为 Unix 秒。建议固定 UTC 时间窗口并分段查询；日对账采用 UTC 日切。状态和类型使用平台契约枚举，不自行翻译成中文字符串。

limit 默认 500，范围 1～1000；页大小不保证每次返回相同数量。六接口当前共享每商户 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) {
        // 在此按 platformUserId、entityType、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); // 控制本查询频率；其他查询也需共享商户队列。
}

返回结构与保存规则

公共字段见公共响应与分页。资源字段分别见委托字段、成交字段、持仓字段和账变字段。

六接口统一返回 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 使用 string；用十进制处理金额，不能使用浮点数或将长 ID 转为 JavaScript Number。金额币种和数量单位按交易对/合约规格解释。
• 业务时间使用 integer（int64），均为 Unix 毫秒；请求认证 timestamp 和入口凭据 expireAt 使用秒，不能混淆。
• 字符串业务字段为空时通常不输出，数值字段为 0 时有些会被省略。字段缺失不代表业务值为 0。
• 通用记录模型中的 reduceOnly、closeOnly、makerOnly 不省略 false，因此成交或持仓也可能出现这三个 false。只在委托资源中解释它们；不能据此认为成交/持仓执行了对应委托规则。
• closePosition 是可选 boolean：条件委托会提供，其他资源通常省略。缺失与 false 含义不同。
• 下表“当前提供”指读取逻辑具有字段来源；可选字段仍可能因没有值而省略。模型里存在的字段不保证每个接口都会填充。

状态与保证金模式的区别

普通委托的 CANCELED 与条件单的 CANCELLED 拼写不同；条件单已触发不等于生成的普通委托已成交。不要复用同一套 status 翻译表处理所有资源。

条件委托 marginMode 返回 CROSS / ISOLATED；历史普通委托及持仓目前返回 “1” / “2”，分别为全仓/逐仓。当前普通委托不提供 marginMode。商户可以在自己的展示层按资源归一化，原始值仍需保存。

模型中声明但本次查询不提供的字段

通用 RecordData / Java PerpetualData 模型还声明了下列字段，但当前六类正式读取逻辑不填充它们。不应列为可用业务数据，也不能用字段默认值替代真实结果。

实际字段适用范围以上述各资源表为准；平台更新字段或枚举时，按新的接口说明和 SDK 版本适配。

来源与相关指南

• 官方 v0.3.0 源码
• Funding 钱包
• 升级指南