解析流快速入门

刚接触解析流？首先阅读心理模型 - 它解释了过滤器为何如此设计。

快速入门

Get Access

Parsed Streams 适用于所有套餐，每交付一个事件消耗 1 个额度。从 Helius 控制面板获取你的 API 密钥，并连接到 wss://beta.helius-rpc.com 上的 Gatekeeper 端点。该端点与 Helius RPC 和 WebSocket 流量使用相同的主机。使用作为api-key查询参数（或x-api-key头）的项目API密钥进行身份验证。

连接

wscat

wscat -c "wss://beta.helius-rpc.com/?api-key=YOUR_API_KEY"

缺失或无效的密钥会被拒绝，返回 HTTP 401。达到连接上限的项目会返回 HTTP 429。

使用过滤器订阅

发送 parsedTransactionSubscribe 和一个过滤器及可选选项：

{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

响应result是一个整数订阅ID：

{ "jsonrpc": "2.0", "id": 1, "result": 23 }

读取通知

每个匹配的交易作为已解码的parsedTransactionNotification到达，具有指向您过滤器命中的指令的matchedIndexes。有关完整格式，请参见通知。

取消订阅

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

或者只需关闭连接——它将删除所有订阅。

指南

跟踪Jupiter交换

在订阅之前，使用describeProgram构建您可以信任的过滤器。

跟踪Pump.fun铸造

一个安全的重连监听器记录每一个新的Pump.fun代币部署。

处理重连

经受住空闲超时和部署，然后精准回填您错过的内容。

协议参考

解析流通过单个WebSocket连接使用JSON-RPC 2.0。每个请求都会收到具有相同id的响应。订阅然后推送parsedTransactionNotification消息，直到您取消订阅或断开连接。

方法	用途
`parsedTransactionSubscribe`	使用过滤器启动订阅
`parsedTransactionUnsubscribe`	停止订阅
`describeProgram`	列出程序的指令、事件和账户角色

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "parsedTransactionSubscribe",
  "params": [
    {
      "programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
      "instructionNames": ["route", "shared_accounts_route"],
      "accounts": {
        "include": ["So11111111111111111111111111111111111111112"],
        "roles": { "user_transfer_authority": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" }
      },
      "includeFailed": false,
      "includeCpi": true
    },
    { "commitment": "confirmed", "details": "full" }
  ]
}

Response

{ "jsonrpc": "2.0", "id": 1, "result": 23 }

过滤字段

至少需要 programs 或 accounts.include 之一。您设置的字段与 AND 组合：指令必须满足所有条件才能匹配。

string[]

要匹配的程序 ID（base58 地址，而不是名称）。如果其程序在此列表中，则指令匹配。或在列表中。

string[]

解码的指令名称，如 route。首先精确匹配，然后不区分大小写和分隔符进行回退匹配，因此 sharedAccountsRoute 也匹配线路名称 shared_accounts_route。或在列表中。只有目录可以识别其名称的指令才能匹配，因此请从 describeProgram 获取名称。

string[]

账户地址。如果在其账户列表中出现任何这些，则指令匹配。或在列表中。适用于每个指令，无论是否解码。程序 ID 本身在此不算作账户。

object

解码账户角色名称到地址的映射，例如 { "user_transfer_authority": "<pubkey>" }。每个条目都必须成立（条目之间为且关系），并且指令必须解码才能适用。角色名称完全匹配，无大小写折叠，因此请从 describeProgram 复制而不是推测。

boolean

默认值:"false"

包含失败交易的指令。

boolean

默认值:"true"

内部（CPI）指令有资格匹配。设置 false 仅匹配顶级指令。

过滤器或选项中的任何位置的未知字段都将被拒绝，而不是被静默忽略，因此拼写错误会响亮地失败，而不是不匹配任何内容。

选项

第二个参数是可选的。

string

默认值:"confirmed"

仅支持 confirmed。

string

默认值:"full"

每个通知携带的内容。full：完整交易，每个指令，以及指向过滤命中项的 matchedIndexes。matched：仅匹配的指令，无索引列表。raw：仅匹配的指令，每个指令简化为其位置，programId，以及 base58 data blob，无解码字段和无需 accountKeys 数组。当带宽比上下文更重要时，使用 matched（完整负载的平均大小大约是三个大小），当您自己解码指令数据且只需要字节时使用 raw。

每个项目的并发连接数取决于你的套餐：免费版为 5，开发者版为 10，商业版和专业版为 50。项目的所有 API 密钥共享此限制。请参阅速率限制。

通知

每个匹配的交易每个订阅一个通知。默认情况下details: "full"：

{
  "jsonrpc": "2.0",
  "method": "parsedTransactionNotification",
  "params": {
    "subscription": 23,
    "result": {
      "context": { "slot": 430172053 },
      "value": {
        "transaction": {
          "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
          "slot": 430172053,
          "blockTime": null,
          "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
          "fee": 5000,
          "accountKeys": ["6jduWNCT...", "..."],
          "status": "ok",
          "error": null,
          "summary": {
            "type": "swap",
            "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
            "parsedData": {
              "type": "swap",
              "protocol": "jupiter",
              "kind": "swap",
              "in_amount": "1000000",
              "actual_out_amount": "183985",
              "input_mint": "So11111111111111111111111111111111111111112",
              "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          },
          "nativeTransfers": [
            { "fromUserAccount": "6jduWNCT...", "toUserAccount": "DfXygSm4...", "amount": 1000000 }
          ],
          "tokenTransfers": [
            {
              "fromUserAccount": "6jduWNCT...",
              "toUserAccount": "AeUfFU6L...",
              "fromTokenAccount": "HLaEoW1s...",
              "toTokenAccount": "G13P9kSY...",
              "rawTokenAmount": 183985,
              "decimals": 6,
              "tokenStandard": "Fungible",
              "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          ]
        },
        "instructions": [
          {
            "instructionIndex": 4,
            "innerInstructionIndex": null,
            "stackHeight": 1,
            "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
            "programName": "jupiter",
            "instructionName": "route",
            "summary": {
              "type": "swap",
              "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
              "parsedData": {
                "type": "swap",
                "protocol": "jupiter",
                "kind": "swap",
                "in_amount": "1000000",
                "actual_out_amount": "183985",
                "input_mint": "So11111111111111111111111111111111111111112",
                "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
              }
            },
            "decoded": {
              "args": { "in_amount": "1000000", "slippage_bps": 50 },
              "accounts": [
                { "name": "user_transfer_authority", "pubkey": "9xQe...", "isSigner": true, "isWritable": false }
              ]
            }
          }
        ],
        "matchedIndexes": [8, 13]
      }
    }
  }
}

阅读它：

transaction 是完整上下文。fee 以 lamports 为单位。accountKeys 是完整的密钥列表，包括从地址查找表加载的密钥，其顺序与链报告的顺序相同。feePayer 始终为 accountKeys[0]。当 status 为 "error" 时，error 会以结构化 JSON 的形式携带交易错误，例如 {"InstructionError": [2, {"Custom": 6001}]}。
summary 在所有出现位置都采用相同结构：一个 type（例如 swap 或 transfer）、一个便于阅读的 description，以及解析器识别出操作时提供的结构化 parsedData 载荷——对于兑换，其中包含协议、数量和铸币地址。transaction.summary 标记交易的主要操作；每条已识别的指令都有自己的 summary，且结构相同。要收集一笔交易中的所有兑换，请遍历 instructions，并读取 summary.type 为 "swap" 的 summary.parsedData。
兑换数量以交易场所报告的数据为准。 in_amount、actual_out_amount 以及 parsedData 中的内部兑换数量，均为交易场所报告的数据，而不是用户钱包实际发送或收到的数量。它们未计入 Token-2022 转账费用，也未计入兑换之外收取的其他费用。要获取实际收到的确切数量，请比较交易前后用户的代币账户余额。
nativeTransfers 和 tokenTransfers 列出了由解析器从整笔交易中提取的 SOL 和代币流动，其结构与 Parsed Events API 返回的结构相同，因此流消费者和 API 消费者可以共享处理代码。两者始终存在，但可能为空。
instructions 包含交易中的每条指令，并按执行顺序排列：每条顶层指令后面紧跟其内部指令。每个条目都带有自己的位置信息：instructionIndex 表示它属于哪条顶层指令（从 0 开始），innerInstructionIndex 表示它在该指令的内部调用中的位置（null 表示它就是顶层指令本身），stackHeight 表示调用深度（顶层为 1）。请使用这些值，而不是数组位置。
matchedIndexes 是指向 instructions 的索引，指明筛选器实际命中了哪些指令。其余指令用于提供上下文。使用 details: "matched" 时，该数组仅包含命中的指令，并且不存在 matchedIndexes。
decoded 名称采用 snake_case（in_amount、user_transfer_authority），与程序 IDL 中发布的名称一致。整数参数通常为字符串（"1000000"），因为 u64 值无法用 JavaScript 数字表示。
blockTime 目前始终为 null。请勿依赖它进行构建。
一笔交易中可能同时包含已解码和未解码的指令：一条完全解码的兑换指令旁边可能是一条无法识别的备注指令。请根据 decoded 进行分支处理：当它为 null 时，该指令会改为携带 rawData（base58 字节）和 rawAccounts（普通公钥列表），因此你始终有可供处理的数据。

使用 details: "raw"，value 缩减为交易元信息和 blob。accountKeys、nativeTransfers、tokenTransfers、matchedIndexes 以及所有解码字段都消失了（交易 summary 仍被包含）；每个匹配的指令是其位置，其程序及其 data 字节在 base58 中，完全如链上所示（即使是目录可能已经解码的指令也是如此）：

"value": {
  "transaction": {
    "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
    "slot": 430172053,
    "blockTime": null,
    "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
    "fee": 5000,
    "status": "ok",
    "error": null,
    "summary": {
      "type": "swap",
      "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
      "parsedData": {
        "type": "swap",
        "protocol": "jupiter",
        "kind": "swap",
        "in_amount": "1000000",
        "actual_out_amount": "183985",
        "input_mint": "So11111111111111111111111111111111111111112",
        "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    }
  },
  "instructions": [
    { "instructionIndex": 4, "innerInstructionIndex": null, "stackHeight": 1, "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", "data": "3Bxs4h24hBtQy9rw" }
  ]
}

取消订阅

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

如果订阅存在并且是您的，则返回 true。通知立即停止。关闭连接会移除其所有订阅。

发现

使用此类 API 时，最常见的问题是过滤器虽然有效，但未匹配到任何内容，通常是因为猜测了指令或角色名称。describeProgram 会返回匹配器用于比较的确切名称，从而避免此问题。目前，它仅在 wss://fs-beta.helius-rpc.com/?api-key=<API_KEY> 上可用，因此请通过与你的订阅不同的单独连接发送它：

Request

{ "jsonrpc": "2.0", "id": 1, "method": "describeProgram", "params": [{ "program": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" }] }

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
    "name": "jupiter",
    "instructions": ["route", "shared_accounts_route", "exact_out_route"],
    "events": ["SwapEvent"],
    "roles": ["user_transfer_authority", "destination_token_account"]
  }
}

您可以传递程序地址或目录名称，但优先使用地址：名称在不同版本的程序中可能会有歧义（多个目录项被命名为 jupiter，并且名字查找可能解析到旧版本）。如果按名称查找，请确保 result.id 是您打算订阅的程序。推荐流程：使用 describeProgram 获取确切的指令和角色名称，使用这些名称构建过滤器，然后订阅。Track Jupiter Swaps 指南从头到尾进行演示。

限制

限制	值
每个项目的并发连接数	5（免费版）、10（开发者版）、50（商业版和专业版）
每个连接的订阅数	25
客户端消息	每秒 10 条，突发上限为 20 条
客户端消息大小	64 KiB
每个过滤器的 `programs`	10
每个过滤器的 `instructionNames`	50，每个最多 64 个字符
每个过滤器的 `accounts.include`	100
每个过滤器的 `accounts.roles`	20，每个名称最多 64 个字符
每个连接的出站缓冲区	2048 条通知，达到上限后连接将关闭

错误

错误遵循 JSON-RPC 2.0: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }。消息准确指出了问题所在。

Code	意义
`-32700`	解析错误（无效JSON）
`-32600`	无效请求
`-32601`	方法未找到
`-32602`	无效参数：错误的公钥，未知字段，不支持的承诺或详细值
`-32000`	超出过滤器限制
`-32001`	服务器未准备好；使用回退重试
`-32002`	速率限制（每秒10条消息）
`-32006`	订阅过多（每个连接25个）

连接也可以使用 WebSocket 关闭代码关闭——查看处理重连了解其含义和如何恢复。

客户端示例

wscat -c "wss://beta.helius-rpc.com/?api-key=<API_KEY>"
# then send:
{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

import WebSocket from "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: "parsedTransactionSubscribe",
    params: [{ programs: ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"] }],
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.method === "parsedTransactionNotification") {
    const { transaction, instructions, matchedIndexes } = msg.params.result.value;
    for (const i of matchedIndexes ?? instructions.keys()) {
      const ix = instructions[i];
      console.log(transaction.signature, ix.programName, ix.instructionName, ix.decoded?.args);
    }
  }
});

import asyncio, json, websockets

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

async def main():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1, "method": "parsedTransactionSubscribe",
            "params": [{"programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}],
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("method") == "parsedTransactionNotification":
                value = msg["params"]["result"]["value"]
                for i in value.get("matchedIndexes") or range(len(value["instructions"])):
                    ix = value["instructions"][i]
                    print(ix.get("programName"), ix.get("instructionName"), (ix.get("decoded") or {}).get("args"))

asyncio.run(main())

开始使用

数据流与事件监听

数据 API 与 RPC

交易

发送交易

钱包即服务

隐私

资源

解析流快速入门

快速入门

指南

跟踪Jupiter交换

跟踪Pump.fun铸造

处理重连

协议参考

订阅

过滤字段

选项

通知

取消订阅

发现

限制

错误

客户端示例

​快速入门

​指南

跟踪Jupiter交换

跟踪Pump.fun铸造

处理重连

​协议参考

​订阅

​过滤字段

​选项

​通知

​取消订阅

​发现

​限制

​错误

​客户端示例

快速入门

指南

协议参考

订阅

过滤字段

选项

通知

取消订阅

发现

限制

错误

客户端示例