解析流快速入门

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

快速入门

获取访问权限

Parsed Streams 目前处于封闭测试阶段。Helius 团队会将您的项目 ID 加入白名单，并与您共享连接端点。要加入封闭测试，请在此申请。使用作为api-key查询参数（或x-api-key头）的项目API密钥进行身份验证。

连接

wscat

wscat -c "wss://<ENDPOINT>/?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`	停止订阅
`ping`	活性检查；返回当前槽位
`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。

一个项目可以持有最多100个并发连接，在其所有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": [
          {
            "topIndex": 4,
            "innerIndex": 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]。error 以结构化 JSON 承载交易错误，例如 {"InstructionError": [2, {"Custom": 6001}]}，当 status 是 "error" 时。
summary 在其出现的每个地方都有一个形状：type（例如 swap 或 transfer），一个人类可读的 description，以及一个结构化的 parsedData 负载，当解析器识别操作时——对于交换：协议、数量和铸币。transaction.summary 标记了交易的标题操作；每个识别的指令都有其自己的 summary，形状相同。要收集交易中的每个交换，请迭代 instructions 并读取 summary.parsedData，在 summary.type 是 "swap" 时。
nativeTransfers 和 tokenTransfers 列出了解析器从整个交易中提取的 SOL 和代币移动，形状与 Parsed Events API 返回的一样，因此流和 API 用户可以共享处理代码。两者始终存在，可能为空。
instructions 是每个执行顺序的交易指令：每个顶级指令后跟其内部指令。每个条目都有其自己的位置：topIndex 属于哪个顶级指令（从 0 开始），innerIndex 是其在该指令内部调用中的位置（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": [
    { "topIndex": 4, "innerIndex": null, "stackHeight": 1, "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", "data": "3Bxs4h24hBtQy9rw" }
  ]
}

取消订阅

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

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

发现

这种 API 最常见的失败是过滤器有效但没有匹配内容，通常是猜测的指令或角色名称。describeProgram 通过返回匹配器进行比较的确切名称来防止这种情况：

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 指南从头到尾进行演示。

限制

限制	值
每个项目的并发连接	100
每个连接的订阅	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://<ENDPOINT>/?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://<ENDPOINT>/?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://<ENDPOINT>/?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铸造

处理重连

​协议参考

​订阅

​过滤字段

​选项

​通知

​取消订阅

​发现

​限制

​错误

​客户端示例

快速入门

指南

协议参考

订阅

过滤字段

选项

通知

取消订阅

发现

限制

错误

客户端示例