> ## 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 에이전트 프롬프트를 포함합니다. ## 왜 마이그레이션해야 하나요? [Enhanced Transactions API](/docs/ko/enhanced-transactions/overview)는 유지 관리 모드의 구식 제품입니다: 여전히 작동하지만 새로운 파서 유형이나 기능 작업은 받지 않습니다. 그 후속 제품은 [Parsed Events](/docs/ko/parsed-events)로, [Parsed Streams](/docs/ko/parsed-streams)를 지원하는 IDL 카탈로그를 통해 명령을 디코딩합니다. 차이점은 거래를 디코딩하는 방식에 있습니다. Enhanced Transactions는 거래를 고정된 이벤트 유형 목록 중 하나로 분류하고, 알고 있는 유형에 대한 미리 작성된 요약을 반환합니다. Parsed Events는 **모든 명령**을 프로그램의 IDL(3,600개 이상의 프로그램)에 대해 디코딩하여 명명된 인수 및 계정으로 요약을 구축합니다. | | Enhanced Transactions | Parsed Events | | ------------ | --------------------- | ------------------------------------ | | 디코딩 모델 | 고정 이벤트 유형, 큐레이팅된 파서 | IDL 카탈로그, 3,600개 이상의 프로그램 | | 명령 세부사항 | 이벤트 요약만 | 모든 명령, 디코딩된 인수 및 계정, CPIs 포함 | | 파서가 없는 프로그램 | 일반 `UNKNOWN` 출력 | 원시 데이터 및 계정은 항상 명령별로 반환 | | 쿼리 인터페이스 | REST | REST 및 GraphQL | | 페이지 매김 | 서명 커서, 런타임-검색 오류 처리 | `paginationToken` (서명 커서는 여전히 사용 가능) | | 디코딩된 프로그램 오류 | 없음 | 있음 (`decodedError`) | | 원시 거래 페이로드 | 없음 | 선택사항 (`includeRawTransaction`) | | 상태 | 구식, 유지 관리 모드 | 오픈 베타, 활성 개발 중 | Parsed Events는 유료 플랜에서 오픈 베타 단계에 있습니다. API는 일반 공개 이전에 여전히 변경될 수 있으며, Enhanced Transactions는 그동안 계속 작동하므로 원하는 속도로 마이그레이션할 수 있습니다. ## 엔드포인트 매핑 두 Parsed Events 메서드는 `POST` 요청이며, 동일한 `api-key` 쿼리 매개변수로 인증됩니다. | Enhanced Transactions | Parsed Events | | ------------------------------------------ | -------------------------------------------- | | `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`의 기본값은 10에서 100으로 변경됩니다. * `commitment`의 기본값은 `finalized` 대신 `confirmed`로 설정됩니다; `processed`은 지원되지 않습니다. * `sortOrder`는 동일한 `asc`/`desc` 값을 유지하며 기본값은 `desc`입니다. 페이지 매김을 위해, 이전 응답에서 `beforeSignature` 대신 `paginationToken`를 사용하는 것이 좋습니다 — 아래 [페이지 매김 간소화](#마이그레이션-단계)를 참조하세요. 이전 `type` 매개변수는 Parsed Events에 해당하는 것이 없으며, 서버 측 거래 유형 필터링도 없습니다. `parsed.summary.type` (`swap`, `transfer`, `add_liquidity`, ...) 또는 이전 고정 유형보다 정확하게 디코딩된 명령어 자체에서 클라이언트 측 필터링하세요. 실시간 유형별 피드의 경우, [Parsed Streams](/docs/ko/parsed-streams)는 서버 측에서 명령어 수준으로 필터링합니다. ## 응답 필드 매핑 Enhanced Transactions는 강화된 거래의 평면 배열을 반환합니다. Parsed Events는 각 결과를 `{ signature, parserStatus, parsed }`로 감싸고, 히스토리 응답은 배열을 `paginationToken`가 있는 페이지 객체로 감쌉니다. 파싱된 필드는 다음과 같이 매핑됩니다. | 기존 필드 | 새로운 필드 | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `description` | `parsed.summary.description` — 거래 수준 요약이 적용되지 않을 경우 `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에서 명명됩니다. Enhanced Transactions가 거래당 하나의 이벤트 요약을 제공했다면, Parsed Events는 요약과 함께 전체 디코딩된 명령 목록을 제공합니다. 각 필드에 대한 내용은 [Parsed Response](/docs/ko/parsed-events/parsed-response)를 참조하세요. ## 마이그레이션 단계 Parse Transactions 호출을 `POST /v1/parsed-events/transactions`로, 히스토리 호출을 `POST /v1/parsed-events/transaction-history`로 지정합니다. 동일한 호스트, 동일한 `api-key` 쿼리 매개변수를 사용합니다. 히스토리 요청은 쿼리 매개변수가 있는 `GET`에서 JSON 본문이 있는 `POST`로 변경됩니다 — 각 매개 변수를 [위 매핑](#매개변수-매핑)대로 이동하십시오. 새로운 봉투를 풀어냅니다: `parserStatus === "OK"`을 확인한 다음, 최상위 수준 대신 `parsed`에서 필드를 읽습니다. `timestamp`를 `blockTime`로 이름을 변경하고, `description` 및 `type`를 `summary`에서 읽습니다 (`null`를 확인합니다), 그리고 `tokenAmount`를 읽었던 이전 코드 대신 `rawTokenAmount`를 `10^decimals`로 나누십시오. 이전 코드가 `type=...`를 전달한 경우, 반환된 항목을 클라이언트 측에서 `parsed.summary.type` 또는 `parsed.instructions[]`로 필터링하십시오 — 예를 들어, "명령어가 `programId`일 때 Jupiter이고 `instructionName`가 `route`인 경우"는 검증할 수 있는 것으로 `type=SWAP`를 대체합니다. 유형 필터가 실시간 피드를 구동하기 위해 존재했다면, 해당 소비자를 [Parsed Streams](/docs/ko/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에서 동일한 페이지를 가져와 서명 세트, 수수료 및 전송 금액을 비교합니다. 그런 다음 배포하고 이전 코드 경로를 제거합니다. Enhanced Transactions는 마이그레이션하는 동안 계속 작동합니다 — 강제 종료는 없습니다. ## 검토할 동작 차이점 * **Commitment 기본값.** 히스토리는 이전 엔드포인트가 `finalized`로 기본 설정된 곳에서 `confirmed`로 기본 설정됩니다. 파이프라인이 최종성에 따라 달라진다면 `commitment: "finalized"`를 명시적으로 전달하십시오. `processed`는 지원되지 않습니다. * **아이템별 오류.** 파싱할 수 없는 서명은 더 이상 요청을 실패시키지 않으며, `parserStatus: "ERROR"` 및 `parserError`와 함께 아이템으로 돌아옵니다. 요청별이 아닌 아이템별로 이를 처리하십시오. * **요약 적용범위.** `summary`는 인식된 거래 수준 작업이 없는 거래에 대해 `null`입니다. 기존 API는 그러한 경우 `type: "UNKNOWN"`를 반환했습니다. 새 API는 여전히 모든 디코딩된 명령어를 제공합니다. * **접근 권한.** Parsed Events는 유료 플랜에서 오픈 베타 단계에 있으며, 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/ko/agents/overview)를 참조하세요. ## 다음 단계 첫 번째 거래를 파싱하고, 주소 기록을 가져오며, 결과를 페이지로 나눕니다. 파싱된 거래, 전송 및 명령어에 대한 필드 참조. 서버 측에서 필터링된 WebSocket을 통한 실시간 디코딩. 토큰 계정 지원 및 서버 측 필터가 있는 원시 거래 기록.