> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-reference-full-stack-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscribe updates

> 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.

<div class="x2mdx-ref-page x2mdx-ref-page--operation" />

<div className="x2mdx-ref-operation-shell">
  <div className="x2mdx-ref-operation-main">
    <div class="x2mdx-ref-breadcrumbs" role="navigation" aria-label="Breadcrumb">
      <a href="../../index">JSON API AsyncAPI</a>

      <span class="x2mdx-ref-breadcrumb-separator">›</span>

      <a href="../../channels/v2-updates">/v2/updates</a>

      <span class="x2mdx-ref-breadcrumb-separator">›</span>

      <span>subscribe</span>
    </div>

    <div class="x2mdx-ref-hero">
      <p class="x2mdx-ref-eyebrow">/v2/updates</p>

      <h1 class="x2mdx-ref-title">Subscribe updates</h1>

      <div class="x2mdx-ref-badges">
        <span class="x2mdx-ref-badge x2mdx-ref-badge--protocol">WebSocket</span>

        <a class="x2mdx-ref-badge x2mdx-ref-badge--added" href="#history-added-3-4">Present since at least 3.4</a>

        <a class="x2mdx-ref-badge x2mdx-ref-badge--changed" href="#history-updated-3-5">Updated 3.5</a>
      </div>
    </div>

    <div class="x2mdx-ref-operation-bar">
      <span class="x2mdx-ref-operation-method x2mdx-ref-operation-method--subscribe">SUBSCRIBE</span>

      <code>/v2/updates</code>
    </div>

    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.

    ## Protocol Details

    <dl class="x2mdx-ref-meta-grid">
      <div class="x2mdx-ref-meta-item">
        <dt>Protocol</dt>
        <dd>WebSocket</dd>
      </div>

      <div class="x2mdx-ref-meta-item">
        <dt>Channel</dt>
        <dd>/v2/updates</dd>
      </div>

      <div class="x2mdx-ref-meta-item">
        <dt>Action</dt>
        <dd>subscribe</dd>
      </div>

      <div class="x2mdx-ref-meta-item">
        <dt>Operation ID</dt>
        <dd>onV2Updates</dd>
      </div>

      <div class="x2mdx-ref-meta-item">
        <dt>Content type</dt>
        <dd>application/json</dd>
      </div>

      <div class="x2mdx-ref-meta-item">
        <dt>Payload</dt>
        <dd>oneOf</dd>
      </div>
    </dl>

    ## Inputs

    ## Outputs

    <div class="x2mdx-ref-panel">
      <div class="x2mdx-ref-panel-head">
        <h3>Either\_JsCantonError\_JsGetUpdatesResponse</h3>
      </div>

      <dl class="x2mdx-ref-meta-grid">
        <div class="x2mdx-ref-meta-item">
          <dt>Direction</dt>
          <dd>Server -> Client</dd>
        </div>

        <div class="x2mdx-ref-meta-item">
          <dt>Message</dt>
          <dd>Either\_JsCantonError\_JsGetUpdatesResponse</dd>
        </div>
      </dl>

      <div class="x2mdx-ref-schema-variants">
        <div class="x2mdx-ref-schema-variant-label">Variants</div>

        <div class="x2mdx-ref-schema-variant">
          <div class="x2mdx-ref-schema-variant-head">
            <h4>JsCantonError</h4>

            <p class="x2mdx-ref-schema-summary">object</p>
          </div>

          <div class="x2mdx-ref-fields">
            <div class="x2mdx-ref-field-row">
              <div class="x2mdx-ref-field-main">
                <code class="x2mdx-ref-field-name">code</code>
                <span class="x2mdx-ref-type-badge">string</span>

                <span class="x2mdx-ref-required-badge">required</span>
              </div>
            </div>

            <div class="x2mdx-ref-field-row">
              <div class="x2mdx-ref-field-main">
                <code class="x2mdx-ref-field-name">cause</code>
                <span class="x2mdx-ref-type-badge">string</span>

                <span class="x2mdx-ref-required-badge">required</span>
              </div>
            </div>

            <div class="x2mdx-ref-field-row">
              <div class="x2mdx-ref-field-main">
                <code class="x2mdx-ref-field-name">context</code>
                <span class="x2mdx-ref-type-badge">object</span>

                <span class="x2mdx-ref-required-badge">required</span>
              </div>
            </div>

            <div class="x2mdx-ref-field-row">
              <div class="x2mdx-ref-field-main">
                <code class="x2mdx-ref-field-name">errorCategory</code>
                <span class="x2mdx-ref-type-badge">string</span>

                <span class="x2mdx-ref-required-badge">required</span>
              </div>
            </div>
          </div>
        </div>

        <div class="x2mdx-ref-schema-variant">
          <div class="x2mdx-ref-schema-variant-head">
            <h4>JsGetUpdatesResponse</h4>

            <p class="x2mdx-ref-schema-summary">object</p>
          </div>

          <div class="x2mdx-ref-fields">
            <div class="x2mdx-ref-field-row">
              <div class="x2mdx-ref-field-main">
                <code class="x2mdx-ref-field-name">update</code>
                <span class="x2mdx-ref-type-badge">object</span>
              </div>
            </div>
          </div>

          <div class="x2mdx-ref-schema-variants">
            <div class="x2mdx-ref-schema-variant-label">Variants</div>

            <div class="x2mdx-ref-schema-variant">
              <div class="x2mdx-ref-schema-variant-head">
                <h4>update</h4>

                <p class="x2mdx-ref-schema-summary">oneOf</p>
              </div>

              <div class="x2mdx-ref-fields">
                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">OffsetCheckpoint</code>
                    <span class="x2mdx-ref-type-badge">object</span>
                  </div>
                </div>
              </div>

              <div class="x2mdx-ref-schema-variants">
                <div class="x2mdx-ref-schema-variant-label">Variants</div>

                <div class="x2mdx-ref-schema-variant">
                  <div class="x2mdx-ref-schema-variant-head">
                    <h4>OffsetCheckpoint</h4>

                    <p class="x2mdx-ref-schema-summary">object</p>
                  </div>

                  <div class="x2mdx-ref-fields">
                    <div class="x2mdx-ref-field-row">
                      <div class="x2mdx-ref-field-main">
                        <code class="x2mdx-ref-field-name">OffsetCheckpoint</code>
                        <span class="x2mdx-ref-type-badge">object</span>

                        <span class="x2mdx-ref-required-badge">required</span>
                      </div>
                    </div>
                  </div>
                </div>

                <div class="x2mdx-ref-schema-variant">
                  <div class="x2mdx-ref-schema-variant-head">
                    <h4>Reassignment</h4>

                    <p class="x2mdx-ref-schema-summary">object</p>
                  </div>

                  <div class="x2mdx-ref-fields">
                    <div class="x2mdx-ref-field-row">
                      <div class="x2mdx-ref-field-main">
                        <code class="x2mdx-ref-field-name">Reassignment</code>
                        <span class="x2mdx-ref-type-badge">object</span>

                        <span class="x2mdx-ref-required-badge">required</span>
                      </div>
                    </div>
                  </div>
                </div>

                <div class="x2mdx-ref-schema-variant">
                  <div class="x2mdx-ref-schema-variant-head">
                    <h4>TopologyTransaction</h4>

                    <p class="x2mdx-ref-schema-summary">object</p>
                  </div>

                  <div class="x2mdx-ref-fields">
                    <div class="x2mdx-ref-field-row">
                      <div class="x2mdx-ref-field-main">
                        <code class="x2mdx-ref-field-name">TopologyTransaction</code>
                        <span class="x2mdx-ref-type-badge">object</span>

                        <span class="x2mdx-ref-required-badge">required</span>
                      </div>
                    </div>
                  </div>
                </div>

                <div class="x2mdx-ref-schema-variant">
                  <div class="x2mdx-ref-schema-variant-head">
                    <h4>Transaction</h4>

                    <p class="x2mdx-ref-schema-summary">object</p>
                  </div>

                  <div class="x2mdx-ref-fields">
                    <div class="x2mdx-ref-field-row">
                      <div class="x2mdx-ref-field-main">
                        <code class="x2mdx-ref-field-name">Transaction</code>
                        <span class="x2mdx-ref-type-badge">object</span>

                        <span class="x2mdx-ref-required-badge">required</span>
                      </div>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>

    ## Related Schemas

    <AccordionGroup>
      <Accordion title="Either_JsCantonError_JsGetUpdatesResponse">
        <div class="x2mdx-ref-schema" id="schema-v2-updates-subscribe">
          <div class="x2mdx-ref-schema-variants">
            <div class="x2mdx-ref-schema-variant-label">Variants</div>

            <div class="x2mdx-ref-schema-variant">
              <div class="x2mdx-ref-schema-variant-head">
                <h4>JsCantonError</h4>

                <p class="x2mdx-ref-schema-summary">object</p>
              </div>

              <div class="x2mdx-ref-fields">
                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">code</code>
                    <span class="x2mdx-ref-type-badge">string</span>

                    <span class="x2mdx-ref-required-badge">required</span>
                  </div>
                </div>

                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">cause</code>
                    <span class="x2mdx-ref-type-badge">string</span>

                    <span class="x2mdx-ref-required-badge">required</span>
                  </div>
                </div>

                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">context</code>
                    <span class="x2mdx-ref-type-badge">object</span>

                    <span class="x2mdx-ref-required-badge">required</span>
                  </div>
                </div>

                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">errorCategory</code>
                    <span class="x2mdx-ref-type-badge">string</span>

                    <span class="x2mdx-ref-required-badge">required</span>
                  </div>
                </div>
              </div>
            </div>

            <div class="x2mdx-ref-schema-variant">
              <div class="x2mdx-ref-schema-variant-head">
                <h4>JsGetUpdatesResponse</h4>

                <p class="x2mdx-ref-schema-summary">object</p>
              </div>

              <div class="x2mdx-ref-fields">
                <div class="x2mdx-ref-field-row">
                  <div class="x2mdx-ref-field-main">
                    <code class="x2mdx-ref-field-name">update</code>
                    <span class="x2mdx-ref-type-badge">object</span>
                  </div>
                </div>
              </div>

              <div class="x2mdx-ref-schema-variants">
                <div class="x2mdx-ref-schema-variant-label">Variants</div>

                <div class="x2mdx-ref-schema-variant">
                  <div class="x2mdx-ref-schema-variant-head">
                    <h4>update</h4>

                    <p class="x2mdx-ref-schema-summary">oneOf</p>
                  </div>

                  <div class="x2mdx-ref-fields">
                    <div class="x2mdx-ref-field-row">
                      <div class="x2mdx-ref-field-main">
                        <code class="x2mdx-ref-field-name">OffsetCheckpoint</code>
                        <span class="x2mdx-ref-type-badge">object</span>
                      </div>
                    </div>
                  </div>

                  <div class="x2mdx-ref-schema-variants">
                    <div class="x2mdx-ref-schema-variant-label">Variants</div>

                    <div class="x2mdx-ref-schema-variant">
                      <div class="x2mdx-ref-schema-variant-head">
                        <h4>OffsetCheckpoint</h4>

                        <p class="x2mdx-ref-schema-summary">object</p>
                      </div>

                      <div class="x2mdx-ref-fields">
                        <div class="x2mdx-ref-field-row">
                          <div class="x2mdx-ref-field-main">
                            <code class="x2mdx-ref-field-name">OffsetCheckpoint</code>
                            <span class="x2mdx-ref-type-badge">object</span>

                            <span class="x2mdx-ref-required-badge">required</span>
                          </div>
                        </div>
                      </div>
                    </div>

                    <div class="x2mdx-ref-schema-variant">
                      <div class="x2mdx-ref-schema-variant-head">
                        <h4>Reassignment</h4>

                        <p class="x2mdx-ref-schema-summary">object</p>
                      </div>

                      <div class="x2mdx-ref-fields">
                        <div class="x2mdx-ref-field-row">
                          <div class="x2mdx-ref-field-main">
                            <code class="x2mdx-ref-field-name">Reassignment</code>
                            <span class="x2mdx-ref-type-badge">object</span>

                            <span class="x2mdx-ref-required-badge">required</span>
                          </div>
                        </div>
                      </div>
                    </div>

                    <div class="x2mdx-ref-schema-variant">
                      <div class="x2mdx-ref-schema-variant-head">
                        <h4>TopologyTransaction</h4>

                        <p class="x2mdx-ref-schema-summary">object</p>
                      </div>

                      <div class="x2mdx-ref-fields">
                        <div class="x2mdx-ref-field-row">
                          <div class="x2mdx-ref-field-main">
                            <code class="x2mdx-ref-field-name">TopologyTransaction</code>
                            <span class="x2mdx-ref-type-badge">object</span>

                            <span class="x2mdx-ref-required-badge">required</span>
                          </div>
                        </div>
                      </div>
                    </div>

                    <div class="x2mdx-ref-schema-variant">
                      <div class="x2mdx-ref-schema-variant-head">
                        <h4>Transaction</h4>

                        <p class="x2mdx-ref-schema-summary">object</p>
                      </div>

                      <div class="x2mdx-ref-fields">
                        <div class="x2mdx-ref-field-row">
                          <div class="x2mdx-ref-field-main">
                            <code class="x2mdx-ref-field-name">Transaction</code>
                            <span class="x2mdx-ref-type-badge">object</span>

                            <span class="x2mdx-ref-required-badge">required</span>
                          </div>
                        </div>
                      </div>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </div>
        </div>
      </Accordion>
    </AccordionGroup>

    ## History

    <div class="x2mdx-ref-history" aria-label="Reference history">
      <div class="x2mdx-ref-history-event x2mdx-ref-history-event--changed" id="history-updated-3-5">
        <div class="x2mdx-ref-history-event-head">
          <span class="x2mdx-ref-history-event-label">Updated</span>
          <code class="x2mdx-ref-history-event-version">3.5</code>
        </div>

        <p class="x2mdx-ref-history-event-detail">channel description updated; subscribe description updated</p>
      </div>

      <div class="x2mdx-ref-history-event x2mdx-ref-history-event--introduced" id="history-added-3-4">
        <div class="x2mdx-ref-history-event-head">
          <span class="x2mdx-ref-history-event-label">Present since at least</span>
          <code class="x2mdx-ref-history-event-version">3.4</code>
        </div>
      </div>
    </div>
  </div>

  <div className="x2mdx-ref-right-rail" role="complementary" aria-label="Examples and responses">
    <div className="x2mdx-ref-rail-panel">
      <div className="x2mdx-ref-rail-code">
        <div className="x2mdx-ref-rail-head">
          <span className="x2mdx-ref-rail-heading">wscat</span>
        </div>

        ```bash wscat theme={"theme":{"light":"github-light","dark":"github-dark"}}
        npx wscat -c <WEBSOCKET_URL>
        ```
      </div>
    </div>

    <div className="x2mdx-ref-rail-panel">
      <div className="x2mdx-ref-rail-code x2mdx-ref-rail-code--response">
        <div className="x2mdx-ref-rail-head">
          <span className="x2mdx-ref-rail-heading">message</span>

          <span className="x2mdx-ref-response-label">application/json</span>
        </div>

        ```json message theme={"theme":{"light":"github-light","dark":"github-dark"}}
        {
          "code": "<string>",
          "cause": "<string>",
          "context": {},
          "errorCategory": "<integer>"
        }
        ```
      </div>
    </div>
  </div>
</div>