Read the ledger's filtered update stream for the specified contents and filters

POST /v2/updates

Request

curl --request POST \
  --url 'http://localhost:7575/v2/updates' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"beginExclusive":0,"endInclusive":0,"filter":{"filtersByParty":{},"filtersForAnyParty":{}},"verbose":false,"updateFormat":{"includeTransactions":{},"includeReassignments":{},"includeTopologyEvents":{}},"descendingOrder":false}'

200 response

[
  {
    "update": {}
  }
]

JSON Ledger API

Read the ledger’s filtered update stream for the specified contents and filters

OpenAPISince 3.4Changed 3.5

Read the ledger’s filtered update stream for the specified contents and filters. It returns the event types in accordance with the stream contents selected. Also the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: a requesting party must be a stakeholder of an event for it to be included. - ledger effects: a requesting party must be a witness of an event for it to be included. Notice: This endpoint should b…

Protocol Details

Inputs

Query parameters

limit · number

OpenAPI type: integer (int64).

maximum number of elements to return, this param is ignored if is bigger than server setting

stream_idle_timeout_ms · number

OpenAPI type: integer (int64).

timeout to complete and send result if no new elements are received (for open ended streams)

Request body

application/json

beginExclusive · number · required

OpenAPI type: integer (int64).

Exclusive lower bound offset of the requested ledger section (non-negative integer). The response will only contain transactions whose offset is strictly greater than this. If set to zero, the lower bound is set to the beginning of the ledger. If the participant has been pruned, this parameter must be greater or equal than the pruning offset. Required

endInclusive · number

OpenAPI type: integer (int64).

Inclusive higher bound offset of the requested ledger section. If specified the response will only contain transactions whose offset is less than or equal to this. If not specified, - the descending_order must not be selected, - the stream will not terminate. Optional

filter · object

OpenAPI type: TransactionFilter.

Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. Used both for filtering create and archive events as well as for filtering transaction trees.

verbose · boolean

Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels, record and variant type ids for record fields. Optional for backwards compatibility, if defined update_format must be unset

updateFormat · object

OpenAPI type: UpdateFormat.

A format specifying what updates to include and how to render them.

descendingOrder · boolean

If set, the stream will populate the elements in descending order. Optional

Outputs

200

application/json

value · JsGetUpdatesResponse[] · required

400

text/plain

value · string · required

default

application/json

code · string · required

cause · string · required

correlationId · string

traceId · string

context · Map_String · required

resources · Tuple2_String_String[]

errorCategory · integer (int32) · required

grpcCodeValue · integer (int32)

retryInfo · string

definiteAnswer · boolean

History

Changed3.5

The POST /v2/updates operation changed in this snapshot.

Introduced3.4

Request

curl --request POST \
  --url 'http://localhost:7575/v2/updates' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"beginExclusive":0,"endInclusive":0,"filter":{"filtersByParty":{},"filtersForAnyParty":{}},"verbose":false,"updateFormat":{"includeTransactions":{},"includeReassignments":{},"includeTopologyEvents":{}},"descendingOrder":false}'

200 response

[
  {
    "update": {}
  }
]