结算记录

类型：USER_DATA · 权重：10（列表）/ 5（汇总）

状态：已上线。

GET /api/v3/settlements · GET /api/v3/settlements/summary

Rocky 扩展接口。钱包出资分段上的每笔成交都是一笔由你自己的 validator 确认并支付流量的 Canton DvP，所以这里直接暴露结算记录本身，而不只是 myTrades 上的 settlementStatus 标志：尝试次数、最近一次错误、下次重试时间，以及交割后的 cantonUpdateId。用它来对账库存和流量支出。背景：链上结算、外部做市商指南。

列表 — GET /api/v3/settlements

GET /api/v3/settlements?symbol=CBTC-USDCB&status=pending&limit=100&timestamp=1756600000000&signature=...

字段	类型	必填	默认	说明
symbol	string	否	—	省略则返回所有交易对。
status	string	否	—	pending、processing、retry、confirmed、failed、skipped 之一（不区分大小写）。其他值 → -1100。
limit	integer	否	500	非正数 → 默认值；上限 1000。

按最近更新时间倒序。没有结算记录的成交（在启用结算之前执行，或属于内部分段）不会列出；它们在 myTrades 上显示为 settlementStatus: "internal"。

响应 — 200（值仅为示意）

[
  {
    "tradeId": "019910a4-5b2e-7c3d-9e8f-0a1b2c3d4e5f",
    "orderId": "019910a4-9f21-7b34-8c56-1d2e3f4a5b6c",
    "symbol": "CBTC-USDCB",
    "side": "BUY",
    "price": "50000",
    "qty": "0.001",
    "quoteQty": "50.000",
    "isMaker": true,
    "tradeTime": 1756600000456,
    "settlementStatus": "confirmed",
    "attempts": 1,
    "cantonUpdateId": "12207f3a9c1e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d0f2a",
    "lastError": null,
    "nextAttemptTime": null,
    "updateTime": 1756600002100
  },
  {
    "tradeId": "019910a4-6c3f-7d4e-8f90-1b2c3d4e5f60",
    "orderId": "019910a4-a1c2-7d3e-9f40-5a6b7c8d9e0f",
    "symbol": "CBTC-USDCB",
    "side": "SELL",
    "price": "49990",
    "qty": "0.002",
    "quoteQty": "99.980",
    "isMaker": true,
    "tradeTime": 1756600003210,
    "settlementStatus": "retry",
    "attempts": 3,
    "cantonUpdateId": null,
    "lastError": "backpressure",
    "nextAttemptTime": 1756600011000,
    "updateTime": 1756600007000
  }
]

字段	类型	说明
tradeId	string	与 myTrades 上的 id 相同。
orderId	string 或 null	该成交对应的订单；仅对订单归属上线前记录的成交为 null。
symbol、side、price、qty、quoteQty、isMaker、tradeTime		你这一侧的成交信息；quoteQty = price × qty。
settlementStatus	string	见 结算状态机。
attempts	number	到目前为止的提交次数。达到重试上限（默认 20）后结算器放弃该记录（failed）。
cantonUpdateId	string 或 null	交割交易的账本 update id；仅在 confirmed 时非空。按 验证结算 的方法核验。
lastError	string 或 null	最近一次失败尝试的分类错误（如 backpressure、no-memberauth、missing-party:<id>）。终态类错误会直接把记录置为 failed。
nextAttemptTime	number 或 null	pending / processing / retry 期间的下次计划尝试时间，Unix 毫秒；终态后为 null。
updateTime	number	记录最近一次变更时间，Unix 毫秒。

汇总 — GET /api/v3/settlements/summary

GET /api/v3/settlements/summary?symbol=CBTC-USDCB&timestamp=1756600000000&signature=...

字段	类型	必填	说明
symbol	string	否	省略则统计所有交易对。

响应 — 200（值仅为示意）

{
  "bySymbol": [
    {
      "symbol": "CBTC-USDCB",
      "counts": { "confirmed": 12, "failed": 0, "pending": 3, "processing": 1, "retry": 0, "skipped": 0 },
      "unsettledQuoteQty": "212.450"
    }
  ],
  "total": {
    "counts": { "confirmed": 12, "failed": 0, "pending": 3, "processing": 1, "retry": 0, "skipped": 0 },
    "unsettledQuoteQty": "212.450"
  }
}

字段	说明
counts	每个状态始终存在，没有时为 0。
unsettledQuoteQty	pending、processing、retry 记录的 quoteQty 之和：仍在等待上链的名义金额。不含 failed，那是运维事项而不是队列深度。

结算按 venue 串行，持续成交速率超过链的吸收能力时，最先表现为这里的 pending 增长。请在 failed > 0 或 unsettledQuoteQty 超过容忍值时告警。

错误

HTTP	code	原因
400	-1100	status 不是六个值之一。
429	-1003	权重桶耗尽。
500	-1000	数据库不可用。