> ## 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/zh/pre-confirmations/overview)——在事务被收集成条目并转换为碎片之前，在计划事务阶段交付的事务。这是 Helius 提供的最低延迟事务信号。

## 端点

`preconfSubscribe` 从 Helius [Gatekeeper](/docs/zh/gatekeeper/overview) 端点提供服务：

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

`beta` 主机名指的是 Gatekeeper 投放，而不是预确认的成熟程度——随着流量迁移到 Gatekeeper，它将成为标准端点。

<Note>
  流不是连续的。覆盖率随着网络股份转发至 Helius 的比例而扩展，因此预计会有没有消息的插槽——请优雅地处理这些间隙。请参阅[覆盖率](/docs/zh/pre-confirmations/overview#coverage)。
</Note>

## 授权

<ParamField query="api-key" type="string" required>
  您的 Helius API 密钥，作为 `api-key` 查询参数传递。需要专业计划或更高级别。
</ParamField>

## 正文

<ParamField body="params" type="array">
  可选。省略 `params` 以接收所有计划的事务。要缩小流范围，请传递一个过滤对象作为第一个元素——过滤发生在服务器端，因此您只需支付并接收您关心的事务。

  <Expandable title="筛选器" defaultOpen>
    每个字段都是可选的——缺少的字段意味着该谓词没有限制，因此空过滤器匹配每个事务。设置字段与 **AND** 组合，按照 `regionInclude` → `accountExclude` → `accountRequired` → `accountInclude` 的顺序计算。

    <ParamField body="failed" type="boolean">
      `false` 删除失败（回滚）的事务；成功和未知状态的事务仍然通过。`true`（如同省略字段）保留每种状态。
    </ParamField>

    <ParamField body="regionInclude" type="string[]">
      如果非空，事务必须来自这些[区域](#region-codes)之一。当设置此字段时，没有区域信息的事务将被丢弃。
    </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/zh/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 序列化。                                                   |

按顺序读取字段，然后[`bincode`](https://docs.rs/bincode)-反序列化剩余字节到一个 `VersionedTransaction`，以读取指令、账户和签名。

<Warning>
  \*\*始终首先读取并检查 `version` 字节。\*\*它目前是 `1`。如果 Helius 需要更新负载格式，版本将递增——根据其分支，这样你的解码器可以在模式更改时继续工作。
</Warning>

预确认是一个早期信号，不是保证。事务尚未上链，仍可能失败或被丢弃。在将其视为最终结果之前，通过标准的承诺检查确认上链。

## 价格

预确认需要**专业计划或更高**，每条消息费用**10 个信用**——每个流式事务一条消息。有关详细信息，请参阅[信用](/docs/zh/billing/credits)。

## 相关

<CardGroup cols={2}>
  <Card title="预确认概述" icon="bolt" href="/docs/zh/pre-confirmations/overview">
    什么是预确认以及它们在验证器管道中的位置。
  </Card>

  <Card title="preconfUnsubscribe" icon="circle-stop" href="/docs/zh/api-reference/pre-confirmations/preconfunsubscribe">
    通过 id 停止订阅。
  </Card>
</CardGroup>