> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/events/streaming.md).

# 即時串流

除了 Webhook 之外，你也可以透過 **WebSocket** 建立一條長連線，即時接收事件推送。當你需要持續、低延遲的串流（而非逐筆 HTTP 回呼）時，這是更合適的選擇。

## 連線

端點為 `GET /v1/stream`，升級為 WebSocket。連線需通過 API key 認證——在升級請求的 header 帶上 `X-API-Key`。

{% tabs %}
{% tab title="JavaScript" %}

```javascript
// 以支援自訂 header 的 WebSocket client 為例
const ws = new WebSocket("wss://api.blockchainsecurity.asia/v1/stream", {
  headers: { "X-API-Key": "ak_live_YOUR_KEY" },
});

ws.on("message", (data) => {
  console.log("event:", data.toString());
});
```

{% endtab %}

{% tab title="Python" %}

```python
import websocket

ws = websocket.create_connection(
    "wss://api.blockchainsecurity.asia/v1/stream",
    header=["X-API-Key: ak_live_YOUR_KEY"],
)
print(ws.recv())  # welcome 訊息
```

{% endtab %}
{% endtabs %}

## 連線後的訊息

連線建立後，伺服器會先送一則 **welcome** 訊息，確認連線與身分：

```json
{ "type": "welcome", "key": "ak_live_3f9a2c7b" }
```

之後，符合你訂閱條件的事件會以 JSON 訊息推送到這條連線上。

## 保持連線

* 送出文字訊息 `ping`，伺服器會回 `pong`，可用於保活與偵測斷線。
* 收到 `Close` 或連線中斷時，請以退避策略重新連線。

{% hint style="info" %}
WebSocket 與 Webhook 可擇一或併用：Webhook 適合無狀態、可水平擴展的接收端；WebSocket 適合需要持續低延遲串流的場景。
{% endhint %}