> ## 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/ja/enhanced-transactions/overview)はメンテナンスモードのレガシープロダクトです：まだ機能しますが、新しいパーサータイプや機能作業は受け付けていません。その後継は[解析イベント](/docs/ja/parsed-events)であり、[解析ストリーム](/docs/ja/parsed-streams)を強化するIDLカタログを通じて命令をデコードします。 トランザクションのデコード方法に違いがあります。拡張トランザクションはトランザクションを固定されたイベントタイプのリストの1つに分類し、知っているタイプに対して事前に構築された概要を返します。解析イベントはプログラム自体のIDLに対して**すべての命令**をデコードし、名前付き引数と名前付きアカウントにし、上に概要を構築します： | | 拡張トランザクション | 解析イベント | | --------------- | ------------------------ | ----------------------------------- | | デコードモデル | 固定イベントタイプ、キュレーションされたパーサー | IDLカタログ、3,600+プログラム | | 命令の詳細 | イベントの概要のみ | すべての命令、デコードされた引数とアカウント、CPIを含む | | パーサーのないプログラム | 一般的な `UNKNOWN` 出力 | 生データとアカウントは命令ごとに常に返される | | クエリインターフェース | REST | RESTとGraphQL | | ページネーション | シグネチャカーソル、ランタイム検索エラーの処理 | `paginationToken`（シグネチャカーソルはまだ利用可能） | | デコードされたプログラムエラー | いいえ | はい（`decodedError`） | | 生トランザクションペイロード | いいえ | オプション（`includeRawTransaction`） | | ステータス | レガシー、メンテナンスモード | オープンベータ、アクティブ開発中 | 解析イベントは有料プランでオープンベータ中です。APIは一般提供前に変更される可能性がありますが、拡張トランザクションはその間も動作し続けるので、移行は自分のペースで進められます。 ## エンドポイントマッピング 解析イベントの両方のメソッドは、すでに使用しているのと同じ `api-key` クエリパラメータで認証され、 `POST` リクエストに送信されます： | 拡張トランザクション | 解析イベント | | ------------------------------------------ | -------------------------------------------- | | `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` (body) | `transactions` — 変更なし | | `commitment` | `commitment` — `confirmed` (デフォルト) または `finalized`；`processed` はサポートされていません | 旧に相当する新しいオプションなし： `includeRawTransaction` は解析結果とともに元のSolanaトランザクションペイロードを返します。 ### トランザクション履歴 `GET /v0/addresses/{address}/transactions` → `POST /v1/parsed-events/transaction-history`。すべてのクエリパラメータはJSONボディフィールドになります： | 古いクエリパラメータ | 新しいボディフィールド | | ------------------ | ----------------- | | `{address}` (path) | `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` | 道中で3つのデフォルトが変更されます： * `limit` は100にデフォルトし、10ではありません。 * `commitment` は `confirmed` にデフォルトし、 `finalized` ではありません；`processed` はサポートされていません。 * `sortOrder` は同じ `asc`/`desc` 値で保持し、デフォルトは `desc` です。 ページングには、前回のレスポンスから `paginationToken` を使用して、 `beforeSignature` を使用することをお勧めします — 以下を参照してください[ページネーションの簡素化](#移行手順)。 古い `type` パラメータには解析イベントに対応するものはありません — サーバー側のトランザクションタイプフィルターはありません。クライアント側で `parsed.summary.type` (`swap`, `transfer`, `add_liquidity`, ...) もしくは、その命令が持つデコード情報自体を使って精度の高いフィルタリングを行います。リアルタイムなタイプ特定のフィードの場合は、[解析ストリーム](/docs/ja/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`（事前スケーリングされた10進数）は`rawTokenAmount`（生の整数）と `decimals` に変わります | そして最大の変更は古いものに相当する新しいフィールドです： `parsed.instructions[]` はすべてのトップレベルと内部命令を実行順に含み、`decoded.args` と `decoded.accounts` がプログラムのIDLから名前付けされます。拡張トランザクションがトランザクションごとに1つのイベント概要を与えたのに対し、解析イベントは概要*と*完全にデコードされた命令リストを提供します。[解析レスポンス](/docs/ja/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` を読んだ場所で `10^decimals` で `rawTokenAmount` を割ります。 古いコードが `type=...` を渡した場所で、返されたアイテムをクライアント側で `parsed.summary.type` または `parsed.instructions[]` でフィルタリングします — 例えば、"命令で `programId` が Jupiter で `instructionName` が `route`"は、`type=SWAP` を実際に検証できる何かに置き換えます。タイプフィルターがリアルタイムフィードを駆動するために存在した場合、そのコンシューマーを[解析ストリーム](/docs/ja/parsed-streams)に移動し、サーバー側で命令レベルでフィルターします。 `before-signature` カーソルループを `paginationToken` に置き換えます： ```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から同じページをフェッチし、シグネチャセット、料金、転送額を比較します。その後、デプロイして古いコードパスを削除します。拡張トランザクションは移行中はそのまま動作します — 強制的なカットオフはありません。 ## レビューすべき動作の違い * **コミットメントのデフォルト。** 履歴は古いエンドポイントが `finalized` にデフォルトするところで `confirmed` にデフォルトします。パイプラインが最終性に依存する場合は `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検索、スキルについては、[AIエージェント向けHelius](/docs/ja/agents/overview)を参照してください。 ## 次のステップ 最初のトランザクションを解析し、アドレス履歴をフェッチし、結果をページングします。 解析されたトランザクション、転送、命令のフィールド参照。 サーバー側でフィルタリングされたWebSocketでリアルタイムの同じデコードを提供。 トークンアカウントサポート、サーバー側フィルターを伴う生トランザクション履歴。