> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# transactionSubscribe

> transactionSubscribe truyền phát các sự kiện giao dịch Solana theo thời gian thực qua WebSocket với bộ lọc tùy chỉnh — theo dõi tài khoản, loại trừ phiếu bầu và thiết lập mức độ chi tiết.

## Điểm cuối

WebSocket nâng cao khả dụng trên mainnet và devnet:

* **Mainnet** `wss://mainnet.helius-rpc.com/?api-key=<api-key>`
* **Devnet** `wss://devnet.helius-rpc.com/?api-key=<api-key>`

<Note>WebSocket có bộ hẹn giờ ngắt sau 10 phút không hoạt động; bạn nên triển khai kiểm tra tình trạng và gửi ping mỗi phút để duy trì kết nối WebSocket.</Note>

## Xác thực

<ParamField query="api-key" type="string" required>
  Khóa API Helius của bạn. Bạn có thể nhận khóa miễn phí trong [bảng điều khiển](https://dashboard.helius.dev/api-keys).
</ParamField>

## Nội dung yêu cầu

<ParamField body="params" type="array" required>
  <Expandable title="TransactionSubscribeFilter" defaultOpen>
    <ParamField body="vote" type="boolean">
      Bao gồm hoặc loại trừ các giao dịch liên quan đến phiếu bầu.
    </ParamField>

    <ParamField body="failed" type="boolean">
      Bao gồm hoặc loại trừ các giao dịch thất bại.
    </ParamField>

    <ParamField body="signature" type="string">
      Lọc các bản cập nhật cho một giao dịch cụ thể theo chữ ký của giao dịch đó.
    </ParamField>

    <ParamField body="accountInclude" type="string[]">
      Danh sách tài khoản cần nhận bản cập nhật giao dịch. Một giao dịch phải bao gồm **ít nhất một** trong các tài khoản này. Hỗ trợ tối đa 50.000 địa chỉ.
    </ParamField>

    <ParamField body="accountExclude" type="string[]">
      Danh sách tài khoản cần loại trừ khỏi các bản cập nhật giao dịch. Hỗ trợ tối đa 50.000 địa chỉ.
    </ParamField>

    <ParamField body="accountRequired" type="string[]">
      Danh sách tài khoản **tất cả đều phải** có trong giao dịch để giao dịch đó khớp. Hỗ trợ tối đa 50.000 địa chỉ.
    </ParamField>

    <ParamField body="tokenAccounts" type="string">
      Bật tính năng mở rộng tài khoản token liên kết (ATA) để ví `accountInclude` cũng khớp với các giao dịch mà ví đó **sở hữu** số dư token SPL — ví dụ: các lượt chuyển token đến tác động đến tài khoản token của ví thay vì pubkey của ví. Chấp nhận:

      * `"balanceChanged"` — khớp khi ví sở hữu một số dư token có số lượng thay đổi (hoặc tài khoản token tương ứng đã bị đóng) trong giao dịch.
      * `"all"` — khớp với mọi giao dịch tham chiếu đến số dư token mà ví sở hữu, ngay cả khi số dư không thay đổi. Lưu lượng cao hơn.
      * `"none"` — giống như khi bỏ qua trường này (không mở rộng). Đây là giá trị mặc định.

      Giá trị không hợp lệ sẽ trả về lỗi JSON-RPC `-32602`: `Invalid tokenAccounts value '<x>', expected one of: none, balanceChanged, all`.
    </ParamField>
  </Expandable>

  <Expandable title="TransactionSubscribeOptions">
    <ParamField body="commitment" type="string">
      Mức cam kết để truy xuất dữ liệu. Có thể là `processed`, `confirmed` hoặc `finalized`.
    </ParamField>

    <ParamField body="encoding" type="string">
      Định dạng mã hóa cho dữ liệu được trả về. Có thể là `base58`, `base64` hoặc `jsonParsed`.
    </ParamField>

    <ParamField body="transactionDetails" type="string">
      Mức độ chi tiết của dữ liệu giao dịch được trả về. Có thể là `full`, `signatures`, `accounts` hoặc `none`.
    </ParamField>

    <ParamField body="showRewards" type="boolean">
      Có bao gồm dữ liệu phần thưởng trong các bản cập nhật hay không.
    </ParamField>

    <ParamField body="maxSupportedTransactionVersion" type="integer">
      Phiên bản giao dịch cao nhất cần nhận bản cập nhật. Đặt thành `1` để nhận các giao dịch legacy, v0 và v1.

      <Note>Bắt buộc khi `transactionDetails` được đặt thành `"accounts"` hoặc `"full"`.</Note>
    </ParamField>
  </Expandable>
</ParamField>

## Phản hồi

<ResponseField name="result" type="integer">
  ID đăng ký (cần để hủy đăng ký)
</ResponseField>

<RequestExample>
  ```json Request theme={"system"}
  {
    "jsonrpc": "2.0",
    "id": 420,
    "method": "transactionSubscribe",
    "params": [
      {
        "accountInclude": ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"]
      },
      {
        "commitment": "processed",
        "encoding": "jsonParsed",
        "transactionDetails": "full",
        "showRewards": true,
        "maxSupportedTransactionVersion": 1
      }
    ]
  }
  ```

  ```json Watch a wallet incl. token transfers theme={"system"}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "transactionSubscribe",
    "params": [
      {
        "accountInclude": ["<WALLET_PUBKEY>"],
        "tokenAccounts": "balanceChanged"
      },
      { "commitment": "confirmed", "encoding": "jsonParsed" }
    ]
  }
  ```

  ```javascript Code Example theme={"system"}
  const WebSocket = require("ws");

  const ws = new WebSocket("wss://mainnet.helius-rpc.com/?api-key=<API_KEY>");

  ws.on("open", () => {
    ws.send(JSON.stringify({
      jsonrpc: "2.0",
      id: 420,
      method: "transactionSubscribe",
      params: [
        { accountInclude: ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"] },
        {
          commitment: "processed",
          encoding: "jsonParsed",
          transactionDetails: "full",
          maxSupportedTransactionVersion: 1,
        },
      ],
    }));

    // Keep connection alive
    setInterval(() => ws.ping(), 30_000);
  });

  ws.on("message", (data) => {
    console.log(JSON.parse(data.toString()));
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "jsonrpc": "2.0",
    "result": 4743323479349712,
    "id": 420
  }
  ```

  ```json Notification theme={"system"}
  {
    "jsonrpc": "2.0",
    "method": "transactionNotification",
    "params": {
      "subscription": 4743323479349712,
      "result": {
        "transaction": {
          "transaction": [
            "Ae6zfSExLsJ/E1+q0jI+3ueAtSoW+6HnuDohmuFwagUo2BU4OpkSdUKYNI1dJfMOonWvjaumf4Vv1ghn9f3Avg0BAAEDGycH0OcYRpfnPNuu0DBQxTYPWpmwHdXPjb8y2P200JgK3hGiC2JyC9qjTd2lrug7O4cvSRUVWgwohbbefNgKQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA0HcpwKokfYDDAJTaF/TWRFWm0Gz5/me17PRnnywHurMBAgIAAQwCAAAAoIYBAAAAAAA=",
            "base64"
          ],
          "meta": {
            "err": null,
            "status": {
              "Ok": null
            },
            "fee": 5000,
            "preBalances": [
              28279852264,
              158122684,
              1
            ],
            "postBalances": [
              28279747264,
              158222684,
              1
            ],
            "innerInstructions": [],
            "logMessages": [
              "Program 11111111111111111111111111111111 invoke [1]",
              "Program 11111111111111111111111111111111 success"
            ],
            "preTokenBalances": [],
            "postTokenBalances": [],
            "rewards": null,
            "loadedAddresses": {
              "writable": [],
              "readonly": []
            },
            "computeUnitsConsumed": 0
          }
        },
        "signature": "5moMXe6VW7L7aQZskcAkKGQ1y19qqUT1teQKBNAAmipzdxdqVLAdG47WrsByFYNJSAGa9TByv15oygnqYvP6Hn2p",
        "slot": 224341380,
        "transactionIndex": 42
      }
    }
  }
  ```
</ResponseExample>

## Quản lý đăng ký

### ID đăng ký

Khi `transactionSubscribe` thành công, máy chủ trả về một ID đăng ký trong trường `result`. Đây cũng là số xuất hiện trong `params.subscription` trên mọi thông báo từ đăng ký đó:

<CodeGroup>
  ```json Subscribe Response theme={"system"}
  {
    "jsonrpc": "2.0",
    "result": 4743323479349712,
    "id": 420
  }
  ```

  ```json Notification theme={"system"}
  {
    "jsonrpc": "2.0",
    "method": "transactionNotification",
    "params": {
      "subscription": 4743323479349712,
      "result": {}
    }
  }
  ```
</CodeGroup>

Lưu ID đăng ký từ phản hồi. Bạn cần ID này để hủy đăng ký.

### Hủy đăng ký

Để ngừng nhận thông báo, hãy gọi `transactionUnsubscribe` với ID đăng ký. Mỗi lệnh gọi `transactionSubscribe` trên cùng một kết nối sẽ tạo một đăng ký riêng với ID riêng, vì vậy hãy nhớ hủy đăng ký trước khi đăng ký lại để tránh nhận thông báo trùng lặp.

<CodeGroup>
  ```json Request theme={"system"}
  {
    "jsonrpc": "2.0",
    "id": 421,
    "method": "transactionUnsubscribe",
    "params": [4743323479349712]
  }
  ```

  ```json Response theme={"system"}
  {
    "jsonrpc": "2.0",
    "result": true,
    "id": 421
  }
  ```
</CodeGroup>

Một vài thông báo đang được truyền có thể vẫn đến trong thời gian ngắn sau khi gọi `transactionUnsubscribe`. Đây là hành vi bình thường.