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

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

• Skim the server notification reference
• Get an API key