# Streaming API: WebSocket (https://docs-kyrm16yq7-ton-core-docs.vercel.app/llms/ecosystem/api/toncenter/streaming/wss/content.md)



[WebSocket](https://en.wikipedia.org/wiki/WebSocket) transport of the [Streaming API](/llms/ecosystem/api/toncenter/streaming/overview/content.md) is the preferred interface for persistent and bidirectional communication with dynamic subscription patterns.

## Usage [#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 [#endpoints]

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

<Callout type="note" title="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](https://tonconsole.com/tonapi/api-keys).
</Callout>

### Operations [#operations]

#### `subscribe` [#subscribe]

Subscribe operation replaces the entire subscription snapshot for the current connection.

<ParamField path="operation" type="string" required="true">
  Must be `"subscribe"`.
</ParamField>

<ParamField path="types" type="string[]" required="true">
  One or more event types to receive: `transactions`, `actions`, `trace`, `trace_invalidated`, `account_state_change`, `jettons_change`. The [event types section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) and [notification schemas section](/llms/ecosystem/api/toncenter/streaming/reference/content.md) provide the exact payload structure for each event.
</ParamField>

<ParamField path="addresses" type="string[]">
  Wallet or contract addresses to monitor. Accepts [valid TON address formats](/llms/foundations/addresses/formats/content.md). May be left empty when subscribing only to a `"trace"`, otherwise required for non-trace event types.
</ParamField>

<ParamField path="trace_external_hash_norms" type="string[]">
  Optional list of normalized external message hashes to monitor. Required when subscribing to a `"trace"`.
</ParamField>

<ParamField path="min_finality" type="string" default="finalized">
  Optional minimum finality: `"pending"`, `"confirmed"`, or `"finalized"`. Defaults to `"finalized"`.
</ParamField>

<ParamField path="include_address_book" type="boolean">
  Optional. If `true`, includes address book data in supported notifications.
</ParamField>

<ParamField path="include_metadata" type="boolean">
  Optional. If `true`, includes token metadata (jetton or NFT) in supported notifications.
</ParamField>

<ParamField path="action_types" type="string[]">
  Optional action type filter. Applies only to `"actions"`. Refer to a list of [available action types in API v3](/llms/ecosystem/api/toncenter/v3/actions-and-traces/get-actions/content.md).
</ParamField>

<ParamField path="supported_action_types" type="string[]" default="`[&#x22;latest&#x22;]`">
  Optional list of action classification types supported by the client. Defaults to `["latest"]`.
</ParamField>

<ParamField path="id" type="string">
  Optional request identifier to match responses with requests.
</ParamField>

```json title="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"
}
```

```json title="Successful response"
{"id": "1", "status": "subscribed"}
```

#### `unsubscribe` [#unsubscribe]

Unsubscribe operation removes one or more addresses or trace hashes from the active subscription.

<ParamField path="operation" type="string" required="true">
  Must be `"unsubscribe"`.
</ParamField>

<ParamField path="addresses" type="string[]">
  Wallet or contract addresses to remove from monitoring. Accepts [valid TON address formats](/llms/foundations/addresses/formats/content.md).
</ParamField>

<ParamField path="trace_external_hash_norms" type="string[]">
  List of normalized external message hashes to remove from monitoring.
</ParamField>

<ParamField path="id" type="string">
  Optional request identifier to match responses with requests.
</ParamField>

```json title="Request example"
{
  "operation": "unsubscribe",
  "addresses": ["<ACCOUNT_ADDRESS>"],
  "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
  "id": "2"
}
```

```json title="Successful response"
{"id": "2", "status": "unsubscribed"}
```

#### `ping` [#ping]

Ping operation serves as a `keepalive` or a connection health check.

<ParamField path="operation" type="string" required="true">
  Must be `"ping"`.
</ParamField>

<ParamField path="id" type="string">
  Optional request identifier to match responses with requests.
</ParamField>

It is recommended to send `ping` request every 15 seconds to keep the connection active.

```json title="Request example"
{
  "operation": "ping",
  "id": "ping-42"
}
```

```json title="Successful response"
{"id": "ping-42", "status": "pong"}
```

## Next steps [#next-steps]

* Skim the server [notification reference](/llms/ecosystem/api/toncenter/streaming/reference/content.md)
* [Get an API key](/llms/ecosystem/api/toncenter/get-api-key/content.md)