Settlement Ledger

Type: USER_DATA · Weight: 10 (list) / 5 (summary)

Status: Live in production.

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

Rocky extension. Every fill on the wallet-funded segment is one Canton DvP that your own validator confirms and pays traffic for, so this surface exposes the settlement rows themselves rather than only the settlementStatus flag on myTrades: attempts, the last error, when the next retry is due, and the cantonUpdateId once delivered. Use it to reconcile inventory and traffic spend against fills. Background: On-chain Settlement, External Market Maker Guide.

List — GET /api/v3/settlements

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

Name	Type	Required	Default	Notes
symbol	string	no	—	Omit for all symbols.
status	string	no	—	One of pending, processing, retry, confirmed, failed, skipped (case-insensitive). Any other value → -1100.
limit	integer	no	500	Non-positive → default; clamped to 1000.

Rows are ordered by last update, newest first. Fills without a settlement row (executed before settlement was enabled, or on the internal segment) are not listed; they appear on myTrades as settlementStatus: "internal".

Response — 200 (values illustrative)

[
  {
    "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
  }
]

Field	Type	Notes
tradeId	string	Same value as id on myTrades.
orderId	string or null	The order this fill executed against; null only for fills recorded before order attribution shipped.
symbol, side, price, qty, quoteQty, isMaker, tradeTime		Your side of the fill; quoteQty = price × qty.
settlementStatus	string	See the status machine.
attempts	number	Submission attempts so far. The settler abandons a row (failed) at the attempt cap, default 20.
cantonUpdateId	string or null	Ledger update id of the delivery transaction; non-null only when confirmed. Verify it as described in Verifying a settlement.
lastError	string or null	Classified error from the last failed attempt (for example backpressure, no-memberauth, missing-party:<id>). A terminal class moves the row straight to failed.
nextAttemptTime	number or null	Unix ms of the next scheduled attempt while pending / processing / retry; null once terminal.
updateTime	number	Last change to the row, Unix ms.

Summary — GET /api/v3/settlements/summary

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

Name	Type	Required	Notes
symbol	string	no	Omit for all symbols.

Response — 200 (values illustrative)

{
  "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"
  }
}

Field	Notes
counts	Every status is always present, zero when absent.
unsettledQuoteQty	Sum of quoteQty over rows in pending, processing and retry: the notional still waiting to move on chain. failed is excluded; it is an operations case, not queue depth.

Settlement is serialized per venue, so a sustained fill rate above what the chain absorbs shows up here first as growing pending. Alarm on failed > 0 and on unsettledQuoteQty above your tolerance.

Errors

HTTP	code	cause
400	-1100	status is not one of the six values.
429	-1003	Weight bucket exhausted.
500	-1000	Database unavailable.