# Streaming API: Server-Sent Events (https://docs-fpm2731fy-ton-core-docs.vercel.app/llms/ecosystem/api/toncenter/streaming/sse/content.md)



[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) transport of the [Streaming API](/llms/ecosystem/api/toncenter/streaming/overview/content.md) uses a single `POST` request to establish the connection and specify the subscription. No further messages are sent by the client on this connection.

## Usage [#usage]

Send one `POST` request to the SSE endpoint with a JSON body that defines the subscription.

### Endpoints [#endpoints]

* Mainnet: `https://toncenter.com/api/streaming/v2/sse`
* Testnet: `https://testnet.toncenter.com/api/streaming/v2/sse`

<Callout type="note" title="TonAPI endpoint compatibility">
  TonAPI supports the same SSE subscription format on different endpoints:

  * Mainnet: `https://tonapi.io/streaming/v2/sse`
  * Testnet: `https://testnet.tonapi.io/streaming/v2/sse`

  Authentication uses a [Ton Console API key](https://tonconsole.com/tonapi/api-keys).
</Callout>

### Request fields [#request-fields]

<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). Optional when subscribing only to a `"trace"`, otherwise required.
</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>

<Callout type="note" title="SSE subscription rules">
  Streaming API does not expose separate `"pending_transactions"` or `"pending_actions"` event types. Subscribe to `"transactions"` or `"actions"`, then use `min_finality` to control delivery timing.
</Callout>

* Include `"trace"` in `types` and provide `trace_external_hash_norms` to subscribe to a specific trace.
* Omit `addresses` when subscribing only to a `"trace"`.

### Examples [#examples]

Lowest-latency stream of `"pending"` → `"confirmed"` → `"finalized"` finality levels:

```http
POST https://toncenter.com/api/streaming/v2/sse
Content-Type: application/json
Accept: text/event-stream

{
  "types": ["transactions", "actions"],
  "addresses": ["EQC...ACCOUNT_ADDRESS", "0:abc...RAW_ADDRESS"],
  "min_finality": "pending",
  "include_address_book": true,
  "include_metadata": false,
  "action_types": ["jetton_transfer", "ton_transfer"]
}
```

Subscribing to a specific trace:

```http
POST https://toncenter.com/api/streaming/v2/sse
Content-Type: application/json
Accept: text/event-stream

{
  "types": ["trace"],
  "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"],
  "min_finality": "pending",
  "include_address_book": true,
  "include_metadata": true
}
```

Successful SSE subscriptions receive the following message from the server:

```json
{"status": "subscribed"}
```

To keep the subscription alive, the server sends the following `keepalive` line every 15 seconds:

```text
: keepalive\n\n
```

Ignore SSE lines that begin with `:`.

## Known limitations [#known-limitations]

### Rate limit on reconnect (429 error) [#rate-limit-on-reconnect-429-error]

If a client reconnects immediately after a disconnect, the previous connection may still be open for \~1 minute. The reconnect attempt receives a 429 error. Use exponential backoff or [an enterprise plan API key](/llms/ecosystem/api/toncenter/get-api-key/content.md).

### POST-only subscription [#post-only-subscription]

Despite SSE typically using `GET` requests, Streaming API endpoints require a `POST` with the subscription JSON in the request body.

<Callout type="note">
  `GET` requests are not supported yet.
</Callout>

### No invalidation signal for `account_state_change` or `jettons_change` [#no-invalidation-signal-for-account_state_change-or-jettons_change]

If a `"confirmed"` account state or jetton balance update is later rolled back, no `"trace_invalidated"` notification is sent for these event types.

When using `"account_state_change"` or `"jettons_change"` at `"confirmed"` finality, consider waiting for `"finalized"` for balance-critical flows.

## 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)