> ## 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. # 从增强交易迁移到解析事件 > 从增强交易API迁移到解析事件。包括端点和参数映射、响应字段映射、前后代码，以及复制粘贴AI代理提示。 ## 为什么要迁移？ [增强交易API](/docs/zh/enhanced-transactions/overview)是一个处于维护模式的遗留产品：它仍然有效，但不再接受新的解析器类型或功能工作。其继任者是[解析事件](/docs/zh/parsed-events)，通过IDL目录解码指令，该目录也支持[解析流](/docs/zh/parsed-streams)。 区别在于交易的解码方式。增强交易将交易分类为固定列表的事件类型之一（`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中获取钱包的解析历史： ```javascript Before (Enhanced Transactions) theme={"system"} 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); } ``` ```javascript After (Parsed Events) theme={"system"} 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`，...），或者在解码指令本身上过滤，这比旧的固定类型更精确。对于实时特定类型的订阅，[解析流](/docs/zh/parsed-streams)在服务器端指令级别进行过滤。 ## 响应字段映射 增强交易返回一个丰富交易的平面数组。解析事件将每个结果包装在一个信封中——`{ 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中命名。增强交易为每个交易提供一个事件摘要，解析事件提供摘要*和*完整解码指令列表。有关每个字段，请参见[解析响应](/docs/zh/parsed-events/parsed-response)。 ## 迁移步骤 将解析交易调用指向`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`为您可以实际验证的东西。如果类型过滤器存在是为了驱动实时订阅，将该消费者移动到[解析流](/docs/zh/parsed-streams)，该流在服务器端的指令级别进行过滤。 用`paginationToken`替换`before-signature`光标循环： ```javascript theme={"system"} 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或其他编码代理，请将以下提示粘贴到您的代码库代理会话中。它会查找增强交易调用点并重写它们。 ```markdown theme={"system"} 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/
/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
- Summarize every call site changed and flag any you were unsure about. ``` 该提示是自包含的——代理不需要访问此页面。有关代理就绪文档、MCP搜索和技能，请参见[Helius for AI agents](/docs/zh/agents/overview)。 ## 下一步 解析您的第一笔交易，获取地址历史，并分页浏览结果。 解析交易、转账和指令的字段参考。 实时通过WebSocket进行相同解码，服务器端过滤。 带令牌账户支持和服务器端过滤的原始交易历史。