Skip to main content
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

​
Request fields

​
types
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.
​
addresses
string[]
Wallet or contract addresses to monitor. Accepts valid TON address formats. Optional when subscribing only to a "trace", otherwise required.
​
trace_external_hash_norms
string[]
Optional list of normalized external message hashes to monitor. Required when subscribing to a "trace".
​
min_finality
string
default:"finalized"
Optional minimum finality: "pending", "confirmed", or "finalized". Defaults to "finalized".
​
include_address_book
boolean
Optional. If true, includes address book data in supported notifications.
​
include_metadata
boolean
Optional. If true, includes token metadata (jetton or NFT) in supported notifications.
​
action_types
string[]
Optional action type filter. Applies only to "actions". Refer to a list of available action types in API v3.
​
supported_action_types
string[]
default:"[\"latest\"]"
Optional list of action classification types supported by the client. Defaults to ["latest"].
  • 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.

​
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