Skip to main content
WebSocket transport of the Streaming API is the preferred interface for persistent and bidirectional communication with dynamic subscription patterns.

​
Usage

Connect to the WebSocket endpoint, then send JSON messages for subscribe, unsubscribe, and ping operations. Each request may include an optional id field for request and response correlation.

​
Endpoints

  • Mainnet: wss://toncenter.com/api/streaming/v2/ws
  • Testnet: wss://testnet.toncenter.com/api/streaming/v2/ws

​
Operations

​
subscribe

Subscribe operation replaces the entire subscription snapshot for the current connection.
​
operation
string
required
Must be "subscribe".
​
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. May be left empty when subscribing only to a "trace", otherwise required for non-trace event types.
​
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"].
​
id
string
Optional request identifier to match responses with requests.
Request example
{
  "operation": "subscribe",
  "types": ["transactions", "actions", "account_state_change", "jettons_change", "trace"],
  "addresses": ["<ACCOUNT_ADDRESS>"],
  "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
  "min_finality": "pending",
  "include_address_book": true,
  "include_metadata": false,
  "action_types": ["jetton_transfer", "ton_transfer"],
  "id": "1"
}
Successful response
{"id": "1", "status": "subscribed"}

​
unsubscribe

Unsubscribe operation removes one or more addresses or trace hashes from the active subscription.
​
operation
string
required
Must be "unsubscribe".
​
addresses
string[]
Wallet or contract addresses to remove from monitoring. Accepts valid TON address formats.
​
trace_external_hash_norms
string[]
List of normalized external message hashes to remove from monitoring.
​
id
string
Optional request identifier to match responses with requests.
Request example
{
  "operation": "unsubscribe",
  "addresses": ["<ACCOUNT_ADDRESS>"],
  "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
  "id": "2"
}
Successful response
{"id": "2", "status": "unsubscribed"}

​
ping

Ping operation serves as a keepalive or a connection health check.
​
operation
string
required
Must be "ping".
​
id
string
Optional request identifier to match responses with requests.
It is recommended to send ping request every 15 seconds to keep the connection active.
Request example
{
  "operation": "ping",
  "id": "ping-42"
}
Successful response
{"id": "ping-42", "status": "pong"}

​
Next steps