Streaming API overview

The TON Center Streaming API (v2) provides developer access to TON Blockchain through Server-Sent Events (SSE) and WebSockets. 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). Use it when building wallets, explorers, monitoring systems, or automation tools.

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 and notification schemas section provide the exact payload structure for each event.

Finality model

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

"finality": "pending" | "confirmed" | "finalized"

Each trace moves through the following monotonic lifecycle:

• 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

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 and event invalidation section document the exact behavior for each event type.

Supported interfaces

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

See also

• Notification reference
• API key
• API authentication