Streaming API: WebSocket
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
TonAPI endpoint compatibility
TonAPI supports the same WebSocket subscription format on different endpoints:
- Mainnet:
wss://tonapi.io/streaming/v2/ws - Testnet:
wss://testnet.tonapi.io/streaming/v2/ws
Authentication uses a Ton Console API key.
Operations
subscribe
Subscribe operation replaces the entire subscription snapshot for the current connection.
operationstringrequired
Must be "subscribe".
typesstring[]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.
addressesstring[]
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_normsstring[]
Optional list of normalized external message hashes to monitor. Required when subscribing to a "trace".
min_finalitystring
Optional minimum finality: "pending", "confirmed", or "finalized". Defaults to "finalized".
include_address_bookboolean
Optional. If true, includes address book data in supported notifications.
include_metadataboolean
Optional. If true, includes token metadata (jetton or NFT) in supported notifications.
action_typesstring[]
Optional action type filter. Applies only to "actions". Refer to a list of available action types in API v3.
supported_action_typesstring[]
Optional list of action classification types supported by the client. Defaults to ["latest"].
idstring
Optional request identifier to match responses with requests.
{
"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"
}{"id": "1", "status": "subscribed"}unsubscribe
Unsubscribe operation removes one or more addresses or trace hashes from the active subscription.
operationstringrequired
Must be "unsubscribe".
addressesstring[]
Wallet or contract addresses to remove from monitoring. Accepts valid TON address formats.
trace_external_hash_normsstring[]
List of normalized external message hashes to remove from monitoring.
idstring
Optional request identifier to match responses with requests.
{
"operation": "unsubscribe",
"addresses": ["<ACCOUNT_ADDRESS>"],
"trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
"id": "2"
}{"id": "2", "status": "unsubscribed"}ping
Ping operation serves as a keepalive or a connection health check.
operationstringrequired
Must be "ping".
idstring
Optional request identifier to match responses with requests.
It is recommended to send ping request every 15 seconds to keep the connection active.
{
"operation": "ping",
"id": "ping-42"
}{"id": "ping-42", "status": "pong"}Next steps
- Skim the server notification reference
- Get an API key