TONTONDocs
TON CenterStreaming API

Streaming API: Server-Sent Events

Server-Sent Events (SSE) transport of the Streaming API uses a single POST request to establish the connection and specify the subscription. No further messages are sent by the client on this connection.

Usage

Send one POST request to the SSE endpoint with a JSON body that defines the subscription.

Endpoints

  • Mainnet: https://toncenter.com/api/streaming/v2/sse
  • Testnet: https://testnet.toncenter.com/api/streaming/v2/sse

TonAPI endpoint compatibility

TonAPI supports the same SSE subscription format on different endpoints:

  • Mainnet: https://tonapi.io/streaming/v2/sse
  • Testnet: https://testnet.tonapi.io/streaming/v2/sse

Authentication uses a Ton Console API key.

Request fields

string[]required

One or more event types to receive: transactions, actions, trace, trace_invalidated, account_state_change, jettons_change. The event types section and notification schemas section provide the exact payload structure for each event.

string[]

Wallet or contract addresses to monitor. Accepts valid TON address formats. Optional when subscribing only to a "trace", otherwise required.

string[]

Optional list of normalized external message hashes to monitor. Required when subscribing to a "trace".

stringdefault: finalized

Optional minimum finality: "pending", "confirmed", or "finalized". Defaults to "finalized".

boolean

Optional. If true, includes address book data in supported notifications.

boolean

Optional. If true, includes token metadata (jetton or NFT) in supported notifications.

string[]

Optional action type filter. Applies only to "actions". Refer to a list of available action types in API v3.

string[]default: ["latest"]

Optional list of action classification types supported by the client. Defaults to ["latest"].

SSE subscription rules

Streaming API does not expose separate "pending_transactions" or "pending_actions" event types. Subscribe to "transactions" or "actions", then use min_finality to control delivery timing.

  • Include "trace" in types and provide trace_external_hash_norms to subscribe to a specific trace.
  • Omit addresses when subscribing only to a "trace".

Examples

Lowest-latency stream of "pending" → "confirmed" → "finalized" finality levels:

POST https://toncenter.com/api/streaming/v2/sse
Content-Type: application/json
Accept: text/event-stream

{
  "types": ["transactions", "actions"],
  "addresses": ["EQC...ACCOUNT_ADDRESS", "0:abc...RAW_ADDRESS"],
  "min_finality": "pending",
  "include_address_book": true,
  "include_metadata": false,
  "action_types": ["jetton_transfer", "ton_transfer"]
}

Subscribing to a specific trace:

POST https://toncenter.com/api/streaming/v2/sse
Content-Type: application/json
Accept: text/event-stream

{
  "types": ["trace"],
  "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
  "min_finality": "pending",
  "include_address_book": true,
  "include_metadata": true
}

Successful SSE subscriptions receive the following message from the server:

{"status": "subscribed"}

To keep the subscription alive, the server sends the following keepalive line every 15 seconds:

: keepalive\n\n

Ignore SSE lines that begin with :.

Known limitations

Rate limit on reconnect (429 error)

If a client reconnects immediately after a disconnect, the previous connection may still be open for ~1 minute. The reconnect attempt receives a 429 error. Use exponential backoff or an enterprise plan API key.

POST-only subscription

Despite SSE typically using GET requests, Streaming API endpoints require a POST with the subscription JSON in the request body.

GET requests are not supported yet.

No invalidation signal for account_state_change or jettons_change

If a "confirmed" account state or jetton balance update is later rolled back, no "trace_invalidated" notification is sent for these event types.

When using "account_state_change" or "jettons_change" at "confirmed" finality, consider waiting for "finalized" for balance-critical flows.

Next steps

Last updated on

Overview

WebSocket

On this page

UsageEndpointsRequest fieldsExamplesKnown limitationsRate limit on reconnect (429 error)POST-only subscriptionNo invalidation signal for account_state_change or jettons_changeNext steps