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

# 구독

> 고성능 gRPC API를 사용하여 계정, 거래, 블록 및 슬롯 업데이트를 실시간 알림으로 구독하세요.

<hide>
  ## 엔드포인트

  gRPC 서비스는 메인넷과 데브넷에서 다음 URL로 제공됩니다:

  * **메인넷** `https://laserstream-mainnet.helius-rpc.com:443`
  * **데브넷** `https://laserstream-devnet.helius-rpc.com:443`
</hide>

## 권한 부여

<ParamField query="x-token" type="string" required>
  귀하의 Helius API 키입니다. 무료로 [대시보드](https://dashboard.helius.dev/api-keys)에서 받을 수 있습니다.
</ParamField>

## 메시지

gRPC API는 여러 구독 유형을 지원하며 단일 요청으로 결합할 수 있습니다.

<ParamField body="accounts" type="object">
  계정 업데이트를 구독합니다. 지정된 계정이 수정되면 데이터를 반환합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="account" type="array">
      모니터링할 계정 pubkey 배열입니다.
    </ParamField>

    <ParamField body="owner" type="array">
      모니터링할 소유자 pubkey 배열입니다 (이 프로그램이 소유한 모든 계정).
    </ParamField>

    <ParamField body="filters" type="object">
      적용할 선택적 필터입니다.

      <Expandable title="필터 옵션">
        <ParamField body="memcmp" type="object">
          계정 데이터에서 특정 바이트를 오프셋으로 필터링합니다.

          <Expandable title="속성">
            <ParamField body="offset" type="integer">
              데이터를 비교하기 시작할 바이트 위치입니다.
            </ParamField>

            <ParamField body="bytes" type="string">
              비교할 데이터입니다 (바이트 형식).
            </ParamField>

            <ParamField body="base58" type="string">
              비교할 데이터입니다 (base58 형식).
            </ParamField>

            <ParamField body="base64" type="string">
              비교할 데이터입니다 (base64 형식).
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="datasize" type="integer">
          바이트 단위의 정확한 계정 데이터 크기로 필터링합니다.
        </ParamField>

        <ParamField body="token_account_state" type="boolean">
          토큰 계정만 필터링합니다.
        </ParamField>

        <ParamField body="lamports" type="object">
          SOL 잔액을 비교하여 필터링합니다.

          <Expandable title="비교 연산자">
            <ParamField body="eq" type="integer">
              지정된 금액과 동일합니다.
            </ParamField>

            <ParamField body="ne" type="integer">
              지정된 금액과 같지 않습니다.
            </ParamField>

            <ParamField body="lt" type="integer">
              지정된 금액보다 적습니다.
            </ParamField>

            <ParamField body="gt" type="integer">
              지정된 금액보다 많습니다.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="nonempty_txn_signature" type="boolean">
      만약 `true`, 거래로 인해 발생한 업데이트만 포함합니다. 만약 `false`, 거래로 인해 발생하지 않은 업데이트만 포함합니다. 만약 `undefined`, 모든 업데이트를 포함합니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="slots" type="object">
  슬롯 업데이트를 구독합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="filter_by_commitment" type="boolean">
      커밋 수준으로 슬롯을 필터링합니다.
    </ParamField>

    <ParamField body="interslot_updates" type="boolean">
      중간 슬롯 상태 업데이트를 포함합니다 (PROCESSED, CONFIRMED, FINALIZED,
      FIRST\_SHRED\_RECEIVED, COMPLETED, CREATED\_BANK, DEAD).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="transactions" type="object">
  거래 업데이트를 구독합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="vote" type="boolean">
      투표 거래를 포함합니다.
    </ParamField>

    <ParamField body="failed" type="boolean">
      실패한 거래를 포함합니다.
    </ParamField>

    <ParamField body="signature" type="string">
      특정 거래 서명을 모니터링합니다.
    </ParamField>

    <ParamField body="account_include" type="array">
      이러한 계정에 영향을 미치는 거래만 포함합니다.
    </ParamField>

    <ParamField body="account_exclude" type="array">
      이러한 계정에 영향을 미치는 거래를 제외합니다.
    </ParamField>

    <ParamField body="account_required" type="array">
      거래는 반드시 이 모든 계정에 영향을 미쳐야 합니다.
    </ParamField>

    <ParamField body="token_accounts" type="enum">
      선택적 ATA(Associated Token Account) 확장 (필드 태그 30, `TokenAccountExpansionControlFlag`). 설정 시, `account_include` 지갑은 SPL 토큰 잔액을 소유하는 거래도 매칭됩니다 — 예를 들어 지갑의 토큰 계정을 만지는 인바운드 토큰 전송. 두 가지 변형:

      * `ALL` (**0**) — 지갑이 소유한 토큰 잔액을 참조하는 모든 거래와 일치, 심지어 변경되지 않아도. 높은 볼륨.
      * `BALANCE_CHANGED` (**1**) — 지갑이 소유한 토큰 잔액이 변경된 (또는 토큰 계정이 닫힌) 거래와 일치합니다.

      확장 비활성화 시, **필드를 생략하세요** (`None`) — "off" 열거값이 없습니다. 범위를 초과한 정수는 구성 빌드에서 거부됩니다: `Invalid token_accounts value, expected ALL (0) or BALANCE_CHANGED (1)`.

      <Warning>
        `ALL`는 **0 값**입니다. "default/off"를 기대하며 열거값을 `0`로 설정한 클라이언트는 `ALL` — 가장 넓고, 높은 볼륨 모드를 얻습니다. "no expansion"을 의미하는 유일한 방법은 필드를 완전히 생략하는 것입니다.
      </Warning>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="transactions_status" type="object">
  거래 상태 업데이트를 구독합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="vote" type="boolean">
      투표 거래를 포함합니다.
    </ParamField>

    <ParamField body="failed" type="boolean">
      실패한 거래를 포함합니다.
    </ParamField>

    <ParamField body="signature" type="string">
      특정 거래 서명을 모니터링합니다.
    </ParamField>

    <ParamField body="account_include" type="array">
      이러한 계정에 영향을 미치는 거래만 포함합니다.
    </ParamField>

    <ParamField body="account_exclude" type="array">
      이러한 계정에 영향을 미치는 거래를 제외합니다.
    </ParamField>

    <ParamField body="account_required" type="array">
      거래는 반드시 이 모든 계정에 영향을 미쳐야 합니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="blocks" type="object">
  블록 업데이트를 구독합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="account_include" type="array">
      이러한 계정에 영향을 미치는 거래를 포함하는 블록만 포함합니다.
    </ParamField>

    <ParamField body="include_transactions" type="boolean">
      전체 거래 세부사항를 포함합니다.
    </ParamField>

    <ParamField body="include_accounts" type="boolean">
      계정 업데이트를 포함합니다.
    </ParamField>

    <ParamField body="include_entries" type="boolean">
      블록 항목을 포함합니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="blocks_meta" type="object">
  블록 메타데이터 업데이트를 구독합니다 (전체 블록 업데이트보다 가볍습니다).

  <Expandable title="returns" defaultOpen>
    <ParamField body="slot" type="integer">
      슬롯 번호입니다.
    </ParamField>

    <ParamField body="blockhash" type="string">
      블록해시입니다.
    </ParamField>

    <ParamField body="rewards" type="array">
      보상 정보입니다.
    </ParamField>

    <ParamField body="block_time" type="integer">
      블록 시간입니다.
    </ParamField>

    <ParamField body="block_height" type="integer">
      블록 높이입니다.
    </ParamField>

    <ParamField body="parent_slot" type="integer">
      상위 슬롯입니다.
    </ParamField>

    <ParamField body="parent_blockhash" type="string">
      상위 블록해시입니다.
    </ParamField>

    <ParamField body="executed_transaction_count" type="integer">
      거래 수입니다.
    </ParamField>

    <ParamField body="entries_count" type="integer">
      항목 수입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="entry" type="object">
  항목 업데이트를 구독합니다.

  <Expandable title="returns" defaultOpen>
    <ParamField body="slot" type="integer">
      슬롯 번호입니다.
    </ParamField>

    <ParamField body="index" type="integer">
      항목 인덱스입니다.
    </ParamField>

    <ParamField body="num_hashes" type="integer">
      해시 수입니다.
    </ParamField>

    <ParamField body="hash" type="string">
      해시입니다.
    </ParamField>

    <ParamField body="executed_transaction_count" type="integer">
      실행된 거래 수입니다.
    </ParamField>

    <ParamField body="starting_transaction_index" type="integer">
      시작 거래 인덱스입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="commitment" type="enum">
  구독의 커밋 수준입니다:

  <Expandable title="수준" defaultOpen>
    <ParamField body="PROCESSED" type="integer">
      (0): 현재 노드에 의해 처리됨.
    </ParamField>

    <ParamField body="CONFIRMED" type="integer">
      (1): 클러스터의 슈퍼다수에 의해 확인됨.
    </ParamField>

    <ParamField body="FINALIZED" type="integer">
      (2): 클러스터에 의해 완료됨.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="accounts_data_slice" type="array">
  수신할 부분 계정 데이터를 지정합니다:

  <Expandable title="속성" defaultOpen>
    <ParamField body="offset" type="integer">
      데이터를 읽기 시작할 바이트 위치입니다.
    </ParamField>

    <ParamField body="length" type="integer">
      읽을 바이트 수입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ping" type="object">
  연결 상태 모니터링을 위한 핑퐁 메시지를 활성화합니다.

  <Expandable title="속성" defaultOpen>
    <ParamField body="id" type="integer">
      핑의 숫자 식별자입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="from_slot" type="integer">
  업데이트를 수신할 시작 슬롯입니다. 이 값 이전의 슬롯에 대한 업데이트는 제외됩니다.
</ParamField>

<RequestExample>
  ```json Accounts Subscription theme={"system"}
  {
    "slots": {
        "slots": {}
    },
    "accounts": {
        "user-defined-label": {
            "account": [
                "DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu",
                "5U3bH5b6XtG99aVCE9ycvDgBKQx3fVT8WwTNbMToFuEr"
            ],
            "owner": [
                "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
            ],
            "filter": {
                "memcmp": {
                    "offset": 0,
                    "bytes": "0102030405"
                },
                "datasize": 165,
                "token_account_state": true,
                "lamports": {
                    "gt": 100000000
                }
            },
            "nonempty_txn_signature": true
        }
    },
    "transactions": {},
    "blocks": {},
    "blocks_meta": {},
    "accounts_data_slice": [],
    "commitment": 1
  }
  ```

  ```json Slots Subscription theme={"system"}
  {
    "slots": {
      "incoming_slots": {}
    },
    "commitment": 1
  }
  ```

  ```json Transactions Subscription theme={"system"}
  {
    "transactions": {
      "vote": false,
      "failed": true,
      "signature": "4RPMxKBhCBubFmZ1r9BC52ztjG3qBTW9Gp1PXfufUSATQaLKTW3Dj6vQBYyVrhfjgJ4PjZLzwYs4Z92KDCPw8Qym",
      "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
      "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "account_required": ["11111111111111111111111111111111"]
    },
    "commitment": 2
  }
  ```

  ```json Wallet + Token Transfers (ATA expansion) theme={"system"}
  {
    "transactions": {
      "wallet": {
        "vote": false,
        "failed": false,
        "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
        "account_exclude": [],
        "account_required": [],
        "token_accounts": 1
      }
    },
    "commitment": 1
  }
  ```

  ```json Transaction Status Subscription theme={"system"}
  {
    "transactions_status": {
      "vote": false,
      "failed": true,
      "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
      "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "account_required": ["11111111111111111111111111111111"]
    },
    "commitment": 2
  }
  ```

  ```json Blocks Subscription theme={"system"}
  {
    "blocks": {
      "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
      "include_transactions": 1,
      "include_accounts": 1,
      "include_entries": 0
    },
    "commitment": 2
  }
  ```

  ```json Block Metadata Subscription theme={"system"}
  {
    "blocks_meta": {},
    "commitment": 2,
    "from_slot": 139000000
  }
  ```

  ```json Entry Subscription theme={"system"}
  {
    "entry": {},
    "commitment": 1
  }
  ```

  ```json Partial Account Data Subscription theme={"system"}
  {
    "accounts": {
      "account": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"]
    },
    "accounts_data_slice": [
      {
        "offset": 0,
        "length": 64
      },
      {
        "offset": 128,
        "length": 32
      }
    ],
    "commitment": 2
  }
  ```

  ```json Ping Subscription theme={"system"}
  {
    "ping": {
      "id": 1
    }
  }
  ```

  ```json Combined Subscription theme={"system"}
  {
    "accounts": {
      "account": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
      "nonempty_txn_signature": true
    },
    "slots": {
      "filter_by_commitment": 1,
      "interslot_updates": 1
    },
    "commitment": 2,
    "from_slot": 139000000,
    "ping": {
      "id": 123
    }
  }
  ```
</RequestExample>

## 커밋 수준

모든 구독은 다음 커밋 수준을 지원합니다:

* `PROCESSED`: 현재 노드에 의해 처리됨 (0)
* `CONFIRMED`: 클러스터의 슈퍼다수에 의해 확인됨 (1)
* `FINALIZED`: 클러스터에 의해 완료됨 (2)

## 응답 구조

구독 응답에는 다음이 포함됩니다:

* `filters`: 이 업데이트와 일치하는 필터 이름
* 다음 업데이트 유형 중 하나:
  * `account`: 계정 데이터, 소유자, lamports, 실행 가능 상태 등
  * `slot`: 슬롯 정보 및 상태 업데이트
  * `transaction`: 전체 거래 세부사항, 서명 및 메타데이터
  * `transaction_status`: 거래 실행 상태 (성공/오류)
  * `block`: 거래, 계정, 보상 등을 포함한 전체 블록 데이터
  * `block_meta`: 전체 거래 세부사항 없이 경량 블록 메타데이터
  * `entry`: 블록 내 항목 세부사항
  * `ping`/`pong`: 연결 상태 확인 메시지
* `created_at`: 업데이트가 생성된 시간의 타임스탬프

<ResponseExample>
  ```json Account Update theme={"system"}
  {
    "filters": ["accounts"],
    "account": {
      "account": {
        "pubkey": "BASE58_ENCODED_PUBKEY",
        "lamports": 12345678,
        "owner": "BASE58_ENCODED_OWNER",
        "executable": false,
        "rent_epoch": 361,
        "data": "BASE64_ENCODED_DATA",
        "write_version": 123,
        "txn_signature": "BASE58_ENCODED_SIGNATURE"
      },
      "slot": 189554321,
      "is_startup": false
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```

  ```json Slot Update theme={"system"}
  {
    "filters": ["slots"],
    "slot": {
      "slot": 189554321,
      "parent": 189554320,
      "status": 2,
      "dead_error": null
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```

  ```json Transaction Update theme={"system"}
  {
    "filters": ["transactions"],
    "transaction": {
      "transaction": {
        "signature": "BASE58_ENCODED_SIGNATURE",
        "is_vote": false,
        "transaction": {
          "signatures": ["BASE58_ENCODED_SIGNATURE"],
          "message": {
            "header": {
              "num_required_signatures": 1,
              "num_readonly_signed_accounts": 0,
              "num_readonly_unsigned_accounts": 1
            },
            "account_keys": ["BASE58_ENCODED_PUBKEY1", "BASE58_ENCODED_PUBKEY2"],
            "recent_blockhash": "BASE58_ENCODED_BLOCKHASH",
            "instructions": [
              {
                "program_id_index": 1,
                "accounts": [0],
                "data": "BASE64_ENCODED_INSTRUCTION_DATA"
              }
            ]
          }
        },
        "meta": {
          "err": null,
          "fee": 5000,
          "pre_balances": [10000000, 1],
          "post_balances": [9995000, 1],
          "pre_token_balances": [],
          "post_token_balances": [],
          "log_messages": ["Program log: Instruction executed"],
          "rewards": []
        },
        "index": 2
      },
      "slot": 189554321
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```

  ```json Block Metadata Update theme={"system"}
  {
    "filters": ["blocks_meta"],
    "block_meta": {
      "slot": 189554321,
      "blockhash": "BASE58_ENCODED_BLOCKHASH",
      "rewards": [
        {
          "pubkey": "BASE58_ENCODED_PUBKEY",
          "lamports": 1785000,
          "post_balance": 48589432109,
          "reward_type": 0,
          "commission": 10
        }
      ],
      "block_time": 1682684096,
      "block_height": 185432109,
      "parent_slot": 189554320,
      "parent_blockhash": "BASE58_ENCODED_PARENT_BLOCKHASH",
      "executed_transaction_count": 2576,
      "entries_count": 16
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```

  ```json Entry Update theme={"system"}
  {
    "filters": ["entry"],
    "entry": {
      "slot": 189554321,
      "index": 5,
      "num_hashes": 8765432,
      "hash": "BASE58_ENCODED_HASH",
      "executed_transaction_count": 128,
      "starting_transaction_index": 1024
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```

  ```json Pong Response theme={"system"}
  {
    "filters": [],
    "pong": {
      "id": 1
    },
    "created_at": "2023-04-28T12:34:56.789Z"
  }
  ```
</ResponseExample>