从增强交易迁移到解析事件

为什么要迁移？

增强交易API是一个处于维护模式的遗留产品：它仍然有效，但不再接受新的解析器类型或功能工作。其继任者是解析事件，通过IDL目录解码指令，该目录也支持解析流。区别在于交易的解码方式。增强交易将交易分类为固定列表的事件类型之一（TRANSFER，SWAP，NFT_SALE，…）并返回其已知类型的预构建摘要。解析事件针对程序的IDL——超过3600个程序——解码每个指令到命名参数和命名账户，并在其上构建摘要：

	增强交易	解析事件
解码模型	固定事件类型，精心策划的解析器	IDL目录，3600+程序
指令细节	仅事件摘要	每个指令，解码参数和账户，包括CPI
没有解析器的程序	泛型`UNKNOWN`输出	每个指令始终返回原始数据和账户
查询接口	REST	REST和GraphQL
分页	签名游标，需要处理运行时搜索错误	`paginationToken`（仍然可用签名游标）
解码的程序错误	否	是（`decodedError`）
原始交易负载	否	可选（`includeRawTransaction`）
状态	遗留，维护模式	开放测试版，积极开发中

解析事件在付费计划中处于开放测试版。在全面上市前，API可能仍会更改；增强交易在此期间仍然有效，因此您可以按自己的节奏迁移。

端点映射

两个解析事件方法都是POST请求到https://mainnet.helius-rpc.com，使用您已经在使用的api-key查询参数进行身份验证。

增强交易	解析事件
`POST /v0/transactions`	`POST /v1/parsed-events/transactions`
`GET /v0/addresses/{address}/transactions`	`POST /v1/parsed-events/transaction-history`

历史端点将所有输入从查询字符串参数移入JSON体。请求体拒绝未知字段，因此拼写错误会被明显地拒绝，而不是被静默忽略。

前后对比

同一任务——在两个API中获取钱包的解析历史：

const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;

const response = await fetch(url);
const transactions = await response.json(); // flat array of enriched transactions

for (const tx of transactions) {
  console.log(tx.signature, tx.type, tx.description);
}

const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";

const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
    limit: 100,
    sortOrder: "desc",
  }),
});
const page = await response.json(); // { data: [...], paginationToken }

for (const item of page.data) {
  if (item.parserStatus !== "OK") continue;
  console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
}

参数映射

解析交易

POST /v0/transactions → POST /v1/parsed-events/transactions

旧	新
`transactions`（体）	`transactions` — 未变
`commitment`	`commitment` — `confirmed`（默认）或`finalized`；不支持`processed`

新选项没有旧选项等效：includeRawTransaction返回原始Solana交易负载和解析结果。

交易历史

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history。每个查询参数成为JSON体字段：

旧查询参数	新体字段
`{address}`（路径）	`address`
`limit`	`limit`
`before-signature`	`beforeSignature`
`after-signature`	`afterSignature`
`sort-order`	`sortOrder`
`commitment`	`commitment`
`gt-time`	`time.gt`
`gte-time`	`time.gte`
`lt-time`	`time.lt`
`lte-time`	`time.lte`
`gt-slot`	`slot.gt`
`gte-slot`	`slot.gte`
`lt-slot`	`slot.lt`
`lte-slot`	`slot.lte`

在此过程中，三个默认值发生变化：

limit默认为100而不是10。
commitment默认为confirmed而不是finalized；不支持processed。
sortOrder保持相同的asc/desc值，以desc作为默认值。

对于分页，建议从上一个响应中过滤paginationToken而不是beforeSignature——请参见下文的简化分页。旧的type参数没有解析事件等效——没有服务器端交易类型过滤。客户端侧在parsed.summary.type上过滤（swap，transfer，add_liquidity，…），或者在解码指令本身上过滤，这比旧的固定类型更精确。对于实时特定类型的订阅，解析流在服务器端指令级别进行过滤。

响应字段映射

增强交易返回一个丰富交易的平面数组。解析事件将每个结果包装在一个信封中——{ signature, parserStatus, parsed }——历史响应将数组包装在一个包含paginationToken的页面对象中。解析字段映射如下：

旧字段	新字段
`description`	`parsed.summary.description` ——当不适用交易级别总结时，`summary`为`null`
`type`（`TRANSFER`，`SWAP`，…）	`parsed.summary.type`（`transfer`，`swap`，…）——较小的集合；每个指令详情转移到`parsed.instructions[]`
`source`（`SYSTEM_PROGRAM`，`JUPITER`，…）	`parsed.summary.parsedData.protocol`，或每个指令作为`instructions[].programName`
`events`（`events.swap`，`events.nft`，…）	`parsed.summary.parsedData` ——由总结类型键控的结构化负载
`fee` / `feePayer`	`parsed.fee` / `parsed.feePayer` ——未变
`signature`	`signature`（信封层级）
`slot`	`parsed.slot`
`timestamp`	`parsed.blockTime`
`transactionError`	`parsed.error`，加上`parsed.decodedError`，包含程序的错误名称（如果元数据可用）
`nativeTransfers`	`parsed.nativeTransfers`——同样的形状（`fromUserAccount`，`toUserAccount`，`amount`为lamports）
`tokenTransfers`	`parsed.tokenTransfers`——相同的账户字段，但`tokenAmount`（预缩放小数）变为`rawTokenAmount`（原始整数）加上`decimals`

最大的变化是一个没有旧等效项的新字段：parsed.instructions[]包含执行顺序中的每个顶级和内层指令，其中decoded.args和decoded.accounts从程序的IDL中命名。增强交易为每个交易提供一个事件摘要，解析事件提供摘要和完整解码指令列表。有关每个字段，请参见解析响应。

迁移步骤

交换端点

将解析交易调用指向POST /v1/parsed-events/transactions，将历史记录调用指向POST /v1/parsed-events/transaction-history。同一主机，同一api-key查询参数。历史记录请求从GET带查询参数更改为带JSON体的POST——根据上面的映射移动每个参数。

更新响应处理

解开新信封：检查parserStatus === "OK"，然后从parsed而不是顶级读取字段。重命名timestamp为blockTime，从summary中读取description和type（保护null），并在旧代码读取tokenAmount的位置除以rawTokenAmount。

替换类型过滤

旧代码通过type=...时，在客户端侧对返回项进行parsed.summary.type或parsed.instructions[]过滤——例如，“指令中programId为Jupiter且instructionName为route”的位置替换type=SWAP为您可以实际验证的东西。如果类型过滤器存在是为了驱动实时订阅，将该消费者移动到解析流，该流在服务器端的指令级别进行过滤。

简化分页

用paginationToken替换before-signature光标循环：

let paginationToken = null;
const results = [];

do {
  const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: "YOUR_ADDRESS_HERE",
      limit: 100,
      ...(paginationToken && { paginationToken }),
    }),
  });
  const page = await response.json();
  results.push(...page.data);
  paginationToken = page.paginationToken;
} while (paginationToken);

当paginationToken缺失时，循环结束。旧的运行时搜索错误（“未能在搜索期内找到事件”）及其继续签名处理完全消失——删除该代码。

验证旧输出

对于一个示例地址，从两个API获取相同页面并比较签名集合、费用和转账金额。然后部署并删除旧代码路径。在您迁移期间，增强交易保留工作——没有强制截止。

行为差异审核

默认承诺。 历史默认为confirmed，而旧端点默认为finalized。如果您的管道依赖于最终性，请显式传递commitment: "finalized"。不支持processed。
逐项错误。 无法解析的签名不再导致请求失败——它作为一个带有parserStatus: "ERROR"和parserError的项返回。请逐项而不是逐请求处理。
摘要覆盖范围。 对于没有识别到的交易级动作的交易，summary为null。在这种情况下，旧API返回type: "UNKNOWN"；新API仍然提供每个解码指令供您使用。
访问。 解析事件在付费计划中处于开放测试版，并且在全面上市前，API可能仍会更改。

让AI代理进行迁移

如果您使用Claude Code、Cursor或其他编码代理，请将以下提示粘贴到您的代码库代理会话中。它会查找增强交易调用点并重写它们。

Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.

## Background

Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md

## Step 1: Find the old call sites

Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses/<address>/transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
  handlers for the "Failed to find events within the search period" error

## Step 2: Rewrite each call site

Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
  ("confirmed" default or "finalized") and includeRawTransaction.

Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
  POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
  limit -> limit (default is now 100, not 10);
  before-signature -> beforeSignature (prefer paginationToken, see below);
  after-signature -> afterSignature; sort-order -> sortOrder;
  commitment -> commitment (default is now "confirmed", not "finalized";
  "processed" unsupported);
  gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
  gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no server-side equivalent: filter returned items client-side
  on parsed.summary?.type (lowercase: "swap", "transfer", ...) or on
  parsed.instructions[] (programId / instructionName).

Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
  parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
  parsed.summary?.description; type -> parsed.summary?.type;
  source -> parsed.summary?.parsedData?.protocol or
  parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
  rawTokenAmount (raw integer string/number) plus decimals — divide by
  10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
  paginationToken is present, passing it back in the next request body.
  Delete continuation-signature error handling for the old runtime type
  search — it no longer exists.

## Step 3: Constraints and cleanup

- Keep the same Helius API key and host; only paths, methods, bodies, and
  response handling change.
- Never hardcode an API key; keep reading it from the existing config or
  environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
  migration covers only the /v0/transactions and /v0/addresses REST calls.

## Step 4: Verify

- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
  (e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
  history for an address from both APIs — the old
  GET /v0/addresses/{address}/transactions and the new
  POST /v1/parsed-events/transaction-history — and prints whether the
  signature sets, fees, and native transfer amounts match, listing any
  differences. Read the API key from an environment variable and the address
  from a CLI argument.
- Tell the user how to run it, for example:
  HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs <address>
- Summarize every call site changed and flag any you were unsure about.

该提示是自包含的——代理不需要访问此页面。有关代理就绪文档、MCP搜索和技能，请参见Helius for AI agents。

下一步

解析事件快速入门

解析您的第一笔交易，获取地址历史，并分页浏览结果。

解析响应

解析交易、转账和指令的字段参考。

解析流

实时通过WebSocket进行相同解码，服务器端过滤。

getTransactionsForAddress

带令牌账户支持和服务器端过滤的原始交易历史。

快速入门

数据流和事件监听

数据 API 和 RPC

交易

发送交易

钱包即服务

隐私

指南

资源

从增强交易迁移到解析事件

为什么要迁移？

端点映射

前后对比

参数映射

解析交易

交易历史

响应字段映射

迁移步骤

行为差异审核

让AI代理进行迁移

下一步

解析事件快速入门

解析响应

解析流

getTransactionsForAddress

​为什么要迁移？

​端点映射

​前后对比

​参数映射

​解析交易

​交易历史

​响应字段映射

​迁移步骤

​行为差异审核

​让AI代理进行迁移

​下一步

解析事件快速入门

解析响应

解析流

getTransactionsForAddress

为什么要迁移？

端点映射

前后对比

参数映射

解析交易

交易历史

响应字段映射

迁移步骤

行为差异审核

让AI代理进行迁移

下一步