# Streaming API overview (https://docs-kyrm16yq7-ton-core-docs.vercel.app/llms/ecosystem/api/toncenter/streaming/overview/content.md)



The TON Center **Streaming API** (v2) provides developer access to TON Blockchain through [Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) and [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It delivers low-latency, real-time updates on transactions and actions observed on the TON blockchain. Clients can subscribe to updates for monitoring a wallet, some contract addresses, or a specific trace of transactions.

Streaming API serves as a real-time, streaming version of the [indexed access layer (API v3)](/llms/ecosystem/api/toncenter/v3/overview/content.md). Use it when building wallets, explorers, monitoring systems, or automation tools.

<Callout type="caution" title="Gap recovery">
  The Streaming API does not recover past events; it only tracks current ones. As such, network interruptions, client restarts, or brief service downtime can cause missed events.

  When application state or business logic depends on a complete event sequence, resynchronize with historical data by polling [API v3](/llms/ecosystem/api/toncenter/v3/overview/content.md) after reconnecting.
</Callout>

<Callout type="note" title="Version naming">
  The [API v2](/llms/ecosystem/api/toncenter/v2/overview/content.md) and [API v3](/llms/ecosystem/api/toncenter/v3/overview/content.md) include their major version numbers in their product names. For the Streaming API, `v2` means the current protocol version and doesn't refer to different APIs.
</Callout>

<Callout type="note" title="Compatibility with TonAPI">
  TonAPI exposes compatible Streaming API endpoints for the same SSE and WebSocket protocol. The request fields, event types, and finality model documented on this page also apply there.

  Authentication uses a [Ton Console API key](https://tonconsole.com/tonapi/api-keys).
</Callout>

## Event groups [#event-groups]

The Streaming API emits the following event groups:

* Trace-based events: `transactions`, `actions`, `trace`
* State updates: `account_state_change` and `jettons_change`
* Invalidation signal: `trace_invalidated`

The [event types section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) and [notification schemas section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) provide the exact payload structure for each event.

## Finality model [#finality-model]

Trace-based events carry a `finality` field according to their finality level:

```json
"finality": "pending" | "confirmed" | "finalized"
```

Each trace moves through the following monotonic lifecycle:

<Mermaid
  chart="flowchart LR
  pending --> confirmed --> finalized
  pending --> trace_invalidated
  confirmed --> trace_invalidated"
/>

* `pending` — result of emulation or speculative execution. This state can be invalidated (`trace_invalidated`).
* `confirmed` — trace or transactions are included in a candidate shard block. Rollback chance is very small, but still possible.
* `finalized` — committed in the masterchain and will not be updated nor invalidated.

Non-trace events behave differently:

* `account_state_change` and `jettons_change` are emitted only when `finality` field is set to either `confirmed` or `finalized`.
* `trace_invalidated` applies to previously emitted trace-based data and is not emitted after `finalized`.

## Delivery behavior [#delivery-behavior]

The `min_finality` field is used to control how early the server emits trace-based updates:

* `pending` — receive every trace snapshot as it moves from `pending` to `confirmed` to `finalized`.
* `confirmed` — skip pure emulation results and start at `confirmed` or later.
* `finalized` — receive only finalized trace-based events.

Choose the setting based on the tolerance for speculative data:

* Use `pending` for the lowest latency.
* Use `confirmed` for lower rollback risk with near-real-time delivery.
* Use `finalized` when only settled data is acceptable.

The [delivery semantics section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) and [event invalidation section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) document the exact behavior for each event type.

## Supported interfaces [#supported-interfaces]

The Streaming API exposes two transports: SSE and a WebSocket. Choose either of the transports to proceed with its usage:

<Columns cols="2">
  <Card title="SSE: Server-Sent Events" icon="server" href="/ecosystem/api/toncenter/streaming/sse">
    Recommended for browser environments or clients that prefer HTTP streaming and a fixed subscription.
  </Card>

  <Card title="WebSocket" icon="signal-stream" href="/ecosystem/api/toncenter/streaming/wss">
    Preferred for persistent, bidirectional communication with dynamic subscription patterns.
  </Card>
</Columns>

## See also [#see-also]

* [Notification reference](/llms/ecosystem/api/toncenter/streaming/reference/content.md)
* [API key](/llms/ecosystem/api/toncenter/get-api-key/content.md)
* [API authentication](/llms/ecosystem/api/toncenter/v3-authentication/content.md)