> ## Documentation Index
> Fetch the complete documentation index at: https://companyname-a7d5b98e-security-edits.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming API notification reference

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

## Event types

Once a subscription is established, the server sends event messages (notifications) matching the selected `types` and `min_finality`. Each message is a JSON object representing a single event.

The `type` field in each notification identifies the notification schema:

* `"transactions"` — subscribe to transactions and their finality levels.
* `"actions"` — subscribe to certain actions by setting `action_types`.
* `"trace"` — subscribe to a transaction trace.
* `"account_state_change"` — emitted for each matching confirmed or finalized account transaction.
* `"jettons_change"` — emitted for each matching confirmed or finalized jetton wallet transaction.
* `"trace_invalidated"` — emitted when earlier trace data becomes invalid.

## Notification schemas

Trace-related notifications, such as `"transactions"`, `"actions"`, and `"trace"` are grouped by the trace. They use the same `trace_external_hash_norm` value across all events generated from one external message.

Transactions and actions in the same trace are ordered by logical time (LT) in descending order. The `"trace"` event includes the full trace tree and a map of all transactions in that trace.

### `"transactions"`

Subscriptions that include `"transactions"` can receive multiple notifications for the same trace as finality increases.

Trace is determined by its `trace_external_hash_norm`.

| Field                      | Type            | Description                                                              |
| -------------------------- | --------------- | ------------------------------------------------------------------------ |
| `type`                     | `string`        | Always `"transactions"`.                                                 |
| `finality`                 | `string`        | `"pending"`, `"confirmed"`, or `"finalized"`.                            |
| `trace_external_hash_norm` | `string`        | Normalized external message hash for the trace.                          |
| `transactions`             | `Transaction[]` | Transactions in the trace, ordered by descending logical time.           |
| `address_book`             | `object`        | Optional mapping of addresses to a friendly format and a TON DNS domain. |
| `metadata`                 | `object`        | Optional mapping of token addresses to metadata (jetton or NFT).         |

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "transactions",
  "finality": "pending",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "transactions": [ /* transaction objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}
```

### `"actions"`

Subscriptions that include `"actions"` can receive multiple notifications for the same trace as finality increases.

<Aside type="note">
  Unlike [traces](#traces) and [transactions](#transactions), actions do not exist on-chain and in blockchain history. Instead, actions are aggregated based on the internal logic of TON Center's [API v3](/ecosystem/api/toncenter/v3/overview).
</Aside>

Trace is determined by its `trace_external_hash_norm`.

| Field                      | Type       | Description                                                              |
| -------------------------- | ---------- | ------------------------------------------------------------------------ |
| `type`                     | `string`   | Always `"actions"`.                                                      |
| `finality`                 | `string`   | `"pending"`, `"confirmed"`, or `"finalized"`.                            |
| `trace_external_hash_norm` | `string`   | Normalized external message hash for the trace.                          |
| `actions`                  | `Action[]` | Classified actions for the trace.                                        |
| `address_book`             | `object`   | Optional mapping of addresses to a friendly format and a TON DNS domain. |
| `metadata`                 | `object`   | Optional mapping of token addresses to metadata (jetton or NFT).         |

<Aside type="note">
  Use `action_types` when subscribing via [SSE](/ecosystem/api/toncenter/streaming/sse) or a [WebSocket](/ecosystem/api/toncenter/streaming/wss) to filter received `actions`. Refer to a list of [available action types in API v3](/ecosystem/api/toncenter/v3/actions-and-traces/get-actions#parameter-action-type).
</Aside>

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "actions",
  "finality": "confirmed",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "actions": [ /* action objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}
```

### `"trace"`

Subscriptions that include `"trace"` receive trace-wide payloads. These payloads are not filtered by account address and include all transactions and actions in the trace.

Trace is determined by its `trace_external_hash_norm`.

| Field                      | Type        | Description                                                              |
| -------------------------- | ----------- | ------------------------------------------------------------------------ |
| `type`                     | `string`    | Always `"trace"`.                                                        |
| `finality`                 | `string`    | `"pending"`, `"confirmed"`, or `"finalized"`.                            |
| `trace_external_hash_norm` | `string`    | Normalized external message hash for the trace.                          |
| `trace`                    | `TraceNode` | Trace tree.                                                              |
| `transactions`             | `object`    | Map of transaction hash to transaction object.                           |
| `actions`                  | `Action[]`  | Optional classified actions for the trace.                               |
| `address_book`             | `object`    | Optional mapping of addresses to a friendly format and a TON DNS domain. |
| `metadata`                 | `object`    | Optional mapping of token addresses to metadata (jetton or NFT).         |

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "trace",
  "finality": "confirmed",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "trace": {},
  "transactions": { /* mappings */ },
  "actions": [ /* action objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}
```

### `"account_state_change"`

Subscriptions that include `"account_state_change"` receive notifications for each transaction executed on a subscribed account address.

This event is emitted only for `"confirmed"` and `"finalized"` finality levels.

| Field      | Type           | Description                                                                                                                                                                                                                        |
| ---------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | `string`       | Always `"account_state_change"`.                                                                                                                                                                                                   |
| `finality` | `string`       | `"confirmed"` or `"finalized"`.                                                                                                                                                                                                    |
| `account`  | `string`       | Account address in raw format, e.g., `0:abc...RAW_ADDRESS`.                                                                                                                                                                        |
| `state`    | `AccountState` | Account state without full code and data [BoCs](/foundations/serialization/boc). Includes state hash, nanoToncoin balance, [account status](/foundations/status), data and code hashes. All hashes are given in the Base64 format. |

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "account_state_change",
  "finality": "finalized",
  "account": "0:18AA...RAW_ADDRESS",
  "state": {
    "hash": "P0Gc...BASE64_HASH",
    "balance": "42...NANOTON_BALANCE",
    "account_status": "active",
    "data_hash": "7qNe...BASE64_HASH",
    "code_hash": "ow8E...BASE64_HASH"
  }
}
```

### `"jettons_change"`

Subscriptions that include `"jettons_change"` receive notifications for each transaction on a jetton wallet contract when the subscribed address is its own address or its owner's TON wallet address.

This event is emitted only for `"confirmed"` and `"finalized"` finality levels.

| Field          | Type           | Description                                                                                                                                                      |
| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `string`       | Always `"jettons_change"`.                                                                                                                                       |
| `finality`     | `string`       | `"confirmed"` or `"finalized"`.                                                                                                                                  |
| `jetton`       | `JettonWallet` | Jetton wallet data. Includes its raw address, jetton balance, owner's raw address, jetton master (minter) raw address, and logical time of its last transaction. |
| `address_book` | `object`       | Optional mapping of addresses to a friendly format and a TON DNS domain.                                                                                         |
| `metadata`     | `object`       | Optional mapping of token addresses to metadata (jetton or NFT).                                                                                                 |

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "jettons_change",
  "finality": "finalized",
  "jetton": {
    "address": "0:88DA...RAW_ADDRESS",
    "balance": "42...JETTON_BALANCE",
    "owner": "0:18AA...RAW_ADDRESS",
    "jetton": "0:B113...RAW_ADDRESS",
    "last_transaction_lt": "61664...LT_UNIX_TIME",
  },
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}
```

### `"trace_invalidated"`

The `"trace_invalidated"` notification signals that previously emitted speculative or intermediate trace data is no longer valid.

Typical causes include:

* external message was not accepted by the blockchain;
* later state change invalidated previous emulation result;
* confirmed shard block was replaced by another block, and the trace did not end up in the finalized block.

Trace in the notification is determined by its `trace_external_hash_norm`.

| Field                      | Type     | Description                                                 |
| -------------------------- | -------- | ----------------------------------------------------------- |
| `type`                     | `string` | Always `"trace_invalidated"`.                               |
| `trace_external_hash_norm` | `string` | Normalized external message hash for the invalidated trace. |

```jsonc title="Notification example" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "type": "trace_invalidated",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH"
}
```

Upon receiving this notification, remove any stored `"trace"`, `"transactions"`, and `"actions"` data for the affected `trace_external_hash_norm`.

The `"trace_invalidated"` notification cannot be sent for the `"finalized"` finality level of the trace.

## Delivery semantics

| Type                   | Finality values                           | Delivery behavior                                                             |
| ---------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `transactions`         | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace as finality increases.                                      |
| `actions`              | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace as action classification and finality progress.             |
| `trace`                | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace with the full trace payload.                                |
| `account_state_change` | `"confirmed"`, `"finalized"`              | Emitted for each matching confirmed or finalized account transaction.         |
| `jettons_change`       | `"confirmed"`, `"finalized"`              | Emitted for each matching confirmed or finalized jetton wallet transaction.   |
| `trace_invalidated`    | Not applicable                            | Emitted when earlier trace-based data [becomes invalid](#event-invalidation). |

### `min_finality` behavior

For trace-based events:

* `min_finality = "pending"` returns `"pending"`, `"confirmed"`, and `"finalized"` snapshots.
* `min_finality = "confirmed"` skips pure emulation and starts at `"confirmed"` or later.
* `min_finality = "finalized"` returns only finalized trace-based events.

For non-trace events:

* `"account_state_change"` and `"jettons_change"` are emitted only with `"confirmed"` and `"finalized"` finality levels.

## Event invalidation

Subscriptions that allow speculative states can later receive `"trace_invalidated"`. If the finality level reaches `"finalized"`, the server is guaranteed not to emit `"trace_invalidated"` for the trace.

<Aside type="note">
  The current API does not expose a separate invalidation signal for `"account_state_change"` or `"jettons_change"` emitted at the `"confirmed"` finality level.
</Aside>

## See also

* [Streaming API overview](/ecosystem/api/toncenter/streaming/overview)
* [SSE](/ecosystem/api/toncenter/streaming/sse)
* [WebSocket](/ecosystem/api/toncenter/streaming/wss)
* [API key](/ecosystem/api/toncenter/get-api-key)
* [API authentication](/ecosystem/api/toncenter/v3-authentication)