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

# preconfSubscribe

> 검증자가 Solana 거래를 실행하기로 확정하는 순간 예약된 거래에 가입하세요 — 그리고 나서 분할되기 전입니다. 상태, 지역 및 계정별로 선택적 서버 측 필터링 가능합니다.

[사전 확인](/docs/ko/pre-confirmations/overview)에 대한 구독 시작 — 트랜잭션이 항목으로 수집되고 조각으로 변환되기 전에 예약된 트랜잭션 단계에서 전달됩니다. 이는 Helius가 제공하는 가장 낮은 대기 시간의 거래 신호입니다.

## 엔드포인트

`preconfSubscribe`는 Helius [Gatekeeper](/docs/ko/gatekeeper/overview) 엔드포인트에서 제공됩니다:

* `wss://beta.helius-rpc.com/?api-key=<API_KEY>`

`beta` 호스트 이름은 Preconfirmations의 성숙도가 아닌 Gatekeeper 출시를 나타냅니다 — 트래픽이 Gatekeeper로 이동됨에 따라 표준 엔드포인트가 될 것입니다.

<Note>
  스트림은 연속적이지 않습니다. Helius로 전달되는 네트워크 지분의 비율에 따라 커버리지가 조정되므로 메시지가 없는 슬롯이 있을 수 있습니다 — 이러한 간격을 원활하게 처리하세요. [Coverage](/docs/ko/pre-confirmations/overview#커버리지)를 참조하세요.
</Note>

## 권한

<ParamField query="api-key" type="string" required>
  `api-key` 쿼리 매개변수로 전달되는 Helius API 키입니다. 프로페셔널 플랜 이상이 필요합니다.
</ParamField>

## 본문

<ParamField body="params" type="array">
  선택 사항입니다. `params`를 생략하여 예약된 모든 트랜잭션을 받을 수 있습니다. 스트림을 좁히려면 첫 번째 요소로 필터 객체를 전달하세요 — 필터링은 서버 측에서 이루어지므로 관심 있는 트랜잭션만 비용을 지불하고 받습니다.

  <Expandable title="Filter" defaultOpen>
    모든 필드는 선택 사항입니다 — 필드가 없으면 해당 조건자가 "제약 없음"을 의미하므로 빈 필터는 모든 트랜잭션과 일치합니다. 설정된 필드는 **AND**로 결합되어 `regionInclude` → `accountExclude` → `accountRequired` → `accountInclude` 순서로 평가됩니다.

    <ParamField body="failed" type="boolean">
      `false` 실패한(되돌려진) 트랜잭션을 삭제합니다. 성공 및 알 수 없는 상태의 트랜잭션은 계속 통과합니다. 필드를 생략한 것처럼 `true`는 모든 상태를 유지합니다.
    </ParamField>

    <ParamField body="regionInclude" type="string[]">
      비어 있지 않으면, 트랜잭션은 이러한 [지역](#지역-코드) 중 하나에서만 발생해야 합니다. 지역 정보가 없는 트랜잭션은 설정 시 삭제됩니다.
    </ParamField>

    <ParamField body="accountInclude" type="string[]">
      비어 있지 않으면, 트랜잭션은 이러한 계정 중 **하나 이상**을 참조해야 합니다(base58 공개 키). 500개 항목으로 제한됩니다.
    </ParamField>

    <ParamField body="accountExclude" type="string[]">
      트랜잭션이 이러한 계정 중 **하나라도** 참조하면 삭제됩니다. `accountInclude`보다 우선합니다. 500개 항목으로 제한됩니다.
    </ParamField>

    <ParamField body="accountRequired" type="string[]">
      트랜잭션은 이러한 모든 계정을 참조해야 합니다. 500개 항목으로 제한됩니다.
    </ParamField>
  </Expandable>
</ParamField>

잘못된 계정 값이나 인식되지 않는 지역 코드는 JSON-RPC 오류 `-32602`(잘못된 매개변수)를 반환합니다.

계정 필터는 트랜잭션의 정적 계정 키 이상과 일치합니다 — Helius는 서버 측에서 v0 [주소 조회 테이블](/docs/ko/glossary#address-lookup-table-alt)을 확인하므로 `accountInclude`, `accountExclude`, 그리고 `accountRequired` 또한 ALT를 통해 트랜잭션이 로드한 계정과 일치합니다.

### 지역 코드

| 코드    | 위치       | 코드    | 위치     |
| ----- | -------- | ----- | ------ |
| `slc` | 솔트레이크 시티 | `tyo` | 도쿄     |
| `fra` | 프랑크푸르트   | `ams` | 암스테르담  |
| `lon` | 런던       | `dal` | 댈러스    |
| `pit` | 피츠버그     | `dub` | 더블린    |
| `sgp` | 싱가포르     | `mia` | 마이애미   |
| `ewr` | 뉴어크      | `lax` | 로스앤젤레스 |
| `iad` | 애시번      | `sea` | 시애틀    |

## 응답

<ResponseField name="result" type="integer">
  구독 id(구독 취소에 필요합니다)
</ResponseField>

<RequestExample>
  ```json Request theme={"system"}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "preconfSubscribe",
    "params": [
      {
        "failed": false,
        "regionInclude": ["ewr", "fra"],
        "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
      }
    ]
  }
  ```

  ```javascript JavaScript theme={"system"}
  const WebSocket = require('ws');

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

  ws.on('open', () => {
    ws.send(JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'preconfSubscribe'
      // Optional filter:
      // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
    }));

    setInterval(() => ws.ping(), 30_000);
  });

  ws.on('message', (data, isBinary) => {
    // The subscribe acknowledgement arrives as a JSON text frame
    if (!isBinary) {
      const msg = JSON.parse(data.toString());
      if (msg.id === 1) console.log('Subscribed, ID:', msg.result);
      return;
    }

    // Notifications arrive as binary frames:
    // version (u8) | slot (u64 LE) | tx_index (u64 LE) | status (u8) | bincode(VersionedTransaction)
    const buf = Buffer.from(data);
    const version = buf.readUInt8(0);
    if (version !== 1) return; // unknown schema version; update your decoder
    const slot = buf.readBigUInt64LE(1);
    const txIndex = buf.readBigUInt64LE(9);
    const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
    const txBytes = buf.subarray(18); // bincode-serialized VersionedTransaction

    console.log('Scheduled transaction:', { slot, txIndex, status, bytes: txBytes.length });
  });
  ```
</RequestExample>

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

  ```text Notification (binary frame) theme={"system"}
  version   u8              payload schema version, currently 1
  slot      u64 (LE)        slot the transaction is scheduled in
  tx_index  u64 (LE)        index of the transaction within the slot
  status    u8              0 = failed, 1 = success, 2 = unknown
  tx        bincode bytes   bincode(VersionedTransaction)
  ```
</ResponseExample>

## 알림

JSON 확인 후 알림은 **바이너리** WebSocket 프레임으로 전달됩니다(JSON 아님). 각 프레임은 단일 예약된 트랜잭션을 전달하는 패킹된 바이트 레이아웃입니다:

| 바이트  | 필드            | 타입                              | 설명                                                                                     |
| ---- | ------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
| 0    | `version`     | `u8`                            | 페이로드 스키마 버전. 현재 `1`.                                                                   |
| 1–8  | `slot`        | `u64` (리틀 엔디안)                  | 트랜잭션이 예약된 슬롯.                                                                          |
| 9–16 | `tx_index`    | `u64` (리틀 엔디안)                  | 슬롯 내에서 트랜잭션의 인덱스.                                                                      |
| 17   | `status`      | `u8`                            | 트랜잭션 상태: `0` = 실패, `1` = 성공, `2` = 알 수 없음. 실행 상태는 검증자가 최선을 다해 보고합니다 — 사용할 수 없는 경우 `2`. |
| 18+  | `transaction` | `bincode(VersionedTransaction)` | 예약된 트랜잭션, 바이너리코드로 직렬화됨.                                                                |

필드를 순서대로 읽은 다음 남은 바이트를 [`bincode`](https://docs.rs/bincode)로 역직렬화하여 명령, 계정, 서명을 읽습니다.

<Warning>
  **항상 `version` 바이트를 먼저 읽고 확인하세요.** 현재 `1`입니다. Helius가 페이로드 형식을 업데이트해야 할 경우 버전이 증가할 것입니다 — 분기하여 디코더가 스키마 변경에도 작동하도록 하세요.
</Warning>

사전 확인은 초기 신호일 뿐, 보증이 아닙니다. 거래가 아직 온체인에 도달하지 않았고 실패하거나 삭제될 수 있습니다. 표준 커밋먼트 검사를 통해 거래가 최종인지 확인하세요.

## 가격

사전 확인은 **프로페셔널 플랜 이상**이 필요하며 **메시지당 10 크레딧**이 소요됩니다 — 스트리밍된 거래당 하나의 메시지입니다. 자세한 내용은 [Credits](/docs/ko/billing/credits)를 참조하세요.

## 관련 항목

<CardGroup cols={2}>
  <Card title="Preconfirmations Overview" icon="bolt" href="/docs/ko/pre-confirmations/overview">
    사전 확인이란 무엇이며 검증자 파이프라인에서의 위치입니다.
  </Card>

  <Card title="preconfUnsubscribe" icon="circle-stop" href="/docs/ko/api-reference/pre-confirmations/preconfunsubscribe">
    ID로 구독을 중지합니다.
  </Card>
</CardGroup>