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

> 사용자 정의 필터로 실시간 거래 이벤트를 구독하세요. 특정 계정을 모니터링하고, 투표 거래를 제외하며, 구성 가능한 세부 수준으로 즉각적인 알림을 받으세요.

## 엔드포인트

향상된 WebSockets는 메인넷과 Devnet에서 사용할 수 있습니다:

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

<Note>WebSocket은 10분의 비활성 타이머가 있으며, WebSocket 연결을 유지하기 위해 1분마다 ping을 보내고 상태 검사를 구현하는 것이 강력히 권장됩니다.</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 토큰 잔액을 **소유**하는 거래에서도 일치하도록 합니다. 예를 들어, 지갑의 토큰 계정이 아닌 pubkey에 접촉하는 수신 토큰 전송. 수락:

      * `"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>

## 구독 관리

### 구독 IDs

`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를 저장하세요. 구독 취소에 필요합니다.

### 구독 취소

알림을 받지 않으려면, `transactionUnsubscribe`에 구독 ID를 호출하세요. 동일한 연결에서 각 `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`를 호출한 후 잠시 동안 몇 개의 대기 메시지가 도착할 수 있습니다. 이는 예상된 동작입니다.