Sign in

POST /v2/state/active-contracts

Query active contracts list (blocking call). Querying active contracts is an expensive operation and if possible should not be repeated often. Consider querying active contracts initially (for a given offset) and then repeatedly call one of /v2/updates/...endpoints to get subsequent modifications. You can also use websockets to get updates with better performance.

Returns a stream of the snapshot of the active contracts and incomplete (un)assignments at a ledger offset. Once the stream of GetActiveContractsResponses completes, the client SHOULD begin streaming updates from the update service, starting at the GetActiveContractsRequest.active_at_offset specified in this request. Clients SHOULD NOT assume that the set of active contracts they receive reflects the state at the ledger end.

Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (http-list-max-elements-limit) there will be an error (413 Content Too Large) returned. Increasing this limit may lead to performance issues and high memory consumption. Consider using websockets (asyncapi) for better efficiency with larger results.

post/v2/state/active-contracts

Query parameters

limitinteger

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

stream_idle_timeout_msinteger

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

Request body

verboseboolean

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 for record fields. Optional, if specified event_format must be unset.

activeAtOffsetinteger required

The offset at which the snapshot of the active contracts will be computed. Must be no greater than the current ledger end offset. Must be greater than or equal to the last pruning offset. Must be a valid absolute offset (positive integer) or ledger begin offset (zero). If zero, the empty set will be returned.

Required

streamContinuationTokenstring

Opaque representation of a continuation token defining a position in the active contracts snapshot. The prefix of the active contracts snapshot will be omitted up to and including the element from which the continuation token was read. To reuse the continuation token from a GetActiveContractsPageResponse:

  • subsequent request must be executed on the same participant with the same version of canton,
  • subsequent request must have the same active_at_offset,
  • subsequent request must have the same event_format
  • and the participant must not have been pruned after the active_at_offset.

If not specified, the whole active contracts snapshot will be returned.

Optional: can be empty

Response

workflowIdstring

The workflow ID used in command submission which corresponds to the contract_entry. Only set if the workflow_id for the command was set. Must be a valid LedgerString (as described in value.proto).

Optional

streamContinuationTokenstring

Opaque representation of a continuation token which can be used in the request to bypass the already processed part of the active contracts snapshot. Only populated for the streaming GetActiveContracts rpc call.

Optional: can be empty

Changes

No recorded changes to this endpoint across all 1 revision of this API.