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.
Must be "subscribe".
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.
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.
Optional list of normalized external message hashes to monitor. Required when subscribing to a "trace".
finalizedOptional minimum finality: "pending", "confirmed", or "finalized". Defaults to "finalized".
Optional. If true, includes address book data in supported notifications.
Optional. If true, includes token metadata (jetton or NFT) in supported notifications.
Optional action type filter. Applies only to "actions". Refer to a list of available action types in API v3.
["latest"]Optional list of action classification types supported by the client. Defaults to ["latest"].
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.
Must be "unsubscribe".
Wallet or contract addresses to remove from monitoring. Accepts valid TON address formats.
List of normalized external message hashes to remove from monitoring.
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.
Must be "ping".
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
Last updated on