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

> 通过自定义过滤器订阅实时交易事件。监控特定账户，排除投票交易，并使用可配置的详细级别接收即时通知。

## 端点

增强的 WebSocket 在主网和开发网可用：

* **主网** `wss://mainnet.helius-rpc.com/?api-key=<api-key>`
* **开发网** `wss://devnet.helius-rpc.com/?api-key=<api-key>`

<Note>WebSocket 具有 10 分钟不活动计时器；强烈建议实施健康检查并每分钟发送 ping 以保持 WebSocket 连接。</Note>

## 授权

<ParamField query="api-key" type="string" required>
  您的 Helius API 密钥。您可以在[仪表板](https://dashboard.helius.dev/api-keys)中免费获取一个。
</ParamField>

## 正文

<ParamField body="params" type="array" required>
  <Expandable title="TransactionSubscribeFilter" defaultOpen>
    <ParamField body="vote" type="boolean">
      包含或排除与投票相关的交易。
    </ParamField>

    <ParamField body="failed" type="boolean">
      包含或排除失败的交易。
    </ParamField>

    <ParamField body="signature" type="string">
      通过签名过滤特定交易的更新。
    </ParamField>

    <ParamField body="accountInclude" type="string[]">
      接收交易更新的账户列表。交易必须包括**至少一个**这些账户。最多支持 50,000 个地址。
    </ParamField>

    <ParamField body="accountExclude" type="string[]">
      排除交易更新的账户列表。最多支持 50,000 个地址。
    </ParamField>

    <ParamField body="accountRequired" type="string[]">
      必须全部包含在交易中的帐户列表，以便进行匹配。支持最多50,000个地址。
    </ParamField>

    <ParamField body="tokenAccounts" type="string">
      选择参与关联代币账户（ATA）扩展，因此一个`accountInclude`钱包也匹配其**拥有**一个SPL代币余额的交易，例如，涉及钱包代币账户的传入代币转账而不是其公钥的交易。接受：

      * `"balanceChanged"` — 当钱包拥有一个在交易中金额发生变化（或代币账户被关闭）的代币余额时进行匹配。
      * `"all"` — 匹配任何引用钱包所拥有代币余额的交易，即使没有变化。更高的流量。
      * `"none"` — 与省略该字段相同（无扩展）。这是默认值。

      无效值将返回JSON-RPC错误`-32602`: `Invalid tokenAccounts value '<x>', expected one of: none, balanceChanged, all`。
    </ParamField>
  </Expandable>

  <Expandable title="TransactionSubscribeOptions">
    <ParamField body="commitment" type="string">
      用于获取数据的承诺级别。可以是`processed`, `confirmed`, 或`finalized`。
    </ParamField>

    <ParamField body="encoding" type="string">
      返回数据的编码格式。可以是`base58`, `base64`, 或`jsonParsed`。
    </ParamField>

    <ParamField body="transactionDetails" type="string">
      返回交易数据的详细级别。可以是`full`, `signatures`, `accounts`, 或`none`。
    </ParamField>

    <ParamField body="showRewards" type="boolean">
      是否在更新中包含奖励数据。
    </ParamField>

    <ParamField body="maxSupportedTransactionVersion" type="integer">
      接收更新的最高交易版本。设置为`0`以获取旧版和版本化交易。

      <Note>当`transactionDetails`设置为`"accounts"` 或 `"full"`时是必需的。</Note>
    </ParamField>
  </Expandable>
</ParamField>

## 响应

<ResponseField name="result" type="integer">
  订阅ID（需要取消订阅）
</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": 0
      }
    ]
  }
  ```

  ```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: 0,
        },
      ],
    }));

    // 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>

## 管理订阅

### 订阅ID

当`transactionSubscribe`成功时，服务器会在`result`字段返回一个订阅ID。这与每个通知中出现的`params.subscription`数字相同：

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

从响应中存储订阅ID。您需要它来取消订阅。

### 取消订阅

要停止接收通知，请使用订阅ID调用`transactionUnsubscribe`。在同一连接上，每次调用`transactionSubscribe`都会创建一个具有自己ID的单独订阅，因此请确保在重新订阅之前取消订阅，以避免接收重复通知。

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

在调用`transactionUnsubscribe`后，可能会有一些正在传输的消息短暂到达。这是预期的行为。