Skip to main content

왜 마이그레이션해야 하나요?

Enhanced Transactions API는 유지 관리 모드의 구식 제품입니다: 여전히 작동하지만 새로운 파서 유형이나 기능 작업은 받지 않습니다. 그 후속 제품은 Parsed Events로, Parsed Streams를 지원하는 IDL 카탈로그를 통해 명령을 디코딩합니다. 차이점은 거래를 디코딩하는 방식에 있습니다. Enhanced Transactions는 거래를 고정된 이벤트 유형 목록 중 하나로 분류하고, 알고 있는 유형에 대한 미리 작성된 요약을 반환합니다. Parsed Events는 모든 명령을 프로그램의 IDL(3,600개 이상의 프로그램)에 대해 디코딩하여 명명된 인수 및 계정으로 요약을 구축합니다. Parsed Events는 유료 플랜에서 오픈 베타 단계에 있습니다. API는 일반 공개 이전에 여전히 변경될 수 있으며, Enhanced Transactions는 그동안 계속 작동하므로 원하는 속도로 마이그레이션할 수 있습니다.

엔드포인트 매핑

두 Parsed Events 메서드는 POST 요청이며, 동일한 api-key 쿼리 매개변수로 인증됩니다. 히스토리 엔드포인트는 모든 입력을 쿼리 문자열 매개변수에서 JSON 본문으로 이동합니다. 요청 본문은 알 수 없는 필드를 거부하므로, 오타가 조용히 무시되지 않고 크게 실패합니다.

전후 비교

두 API에서 동일한 작업 — 지갑의 파싱된 히스토리 가져오기:

매개변수 매핑

거래 파싱

POST /v0/transactionsPOST /v1/parsed-events/transactions 기존에 없던 새로운 옵션: includeRawTransaction은 파싱된 결과와 함께 원래 Solana 거래 페이로드를 반환합니다.

거래 히스토리

GET /v0/addresses/{address}/transactionsPOST /v1/parsed-events/transaction-history. 모든 쿼리 매개변수가 JSON 본문 필드로 변경됩니다. 세 가지 기본값이 변경됩니다:
  • 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는 서버 측에서 명령어 수준으로 필터링합니다.

응답 필드 매핑

Enhanced Transactions는 강화된 거래의 평면 배열을 반환합니다. Parsed Events는 각 결과를 { signature, parserStatus, parsed }로 감싸고, 히스토리 응답은 배열을 paginationToken가 있는 페이지 객체로 감쌉니다. 파싱된 필드는 다음과 같이 매핑됩니다. 그리고 가장 큰 변화는 기존에 없던 새로운 필드입니다: parsed.instructions[]는 실행 순서에 따라 모든 상위 및 내부 명령어를 포함하며, decoded.argsdecoded.accounts는 프로그램의 IDL에서 명명됩니다. Enhanced Transactions가 거래당 하나의 이벤트 요약을 제공했다면, Parsed Events는 요약과 함께 전체 디코딩된 명령 목록을 제공합니다. 각 필드에 대한 내용은 Parsed Response를 참조하세요.

마이그레이션 단계

1

엔드포인트 교체

Parse Transactions 호출을 POST /v1/parsed-events/transactions로, 히스토리 호출을 POST /v1/parsed-events/transaction-history로 지정합니다. 동일한 호스트, 동일한 api-key 쿼리 매개변수를 사용합니다. 히스토리 요청은 쿼리 매개변수가 있는 GET에서 JSON 본문이 있는 POST로 변경됩니다 — 각 매개 변수를 위 매핑대로 이동하십시오.
2

응답 처리 업데이트

새로운 봉투를 풀어냅니다: parserStatus === "OK"을 확인한 다음, 최상위 수준 대신 parsed에서 필드를 읽습니다. timestampblockTime로 이름을 변경하고, descriptiontypesummary에서 읽습니다 (null를 확인합니다), 그리고 tokenAmount를 읽었던 이전 코드 대신 rawTokenAmount10^decimals로 나누십시오.
3

유형 필터링 교체

이전 코드가 type=...를 전달한 경우, 반환된 항목을 클라이언트 측에서 parsed.summary.type 또는 parsed.instructions[]로 필터링하십시오 — 예를 들어, “명령어가 programId일 때 Jupiter이고 instructionNameroute인 경우”는 검증할 수 있는 것으로 type=SWAP를 대체합니다. 유형 필터가 실시간 피드를 구동하기 위해 존재했다면, 해당 소비자를 Parsed Streams로 이동하십시오. 이는 서버 측에서 명령어 수준으로 필터링합니다.
4

페이지 매김 간소화

before-signature 커서 루프를 paginationToken로 교체하십시오.
루프는 paginationToken가 없을 때 종료됩니다. 이전의 런타임-검색 오류(“검색 기간 내 이벤트를 찾지 못했습니다”) 및 계속 서명 처리 오류는 전혀 사라집니다 — 해당 코드를 삭제하십시오.
5

이전 출력과의 비교 검증

샘플 주소에 대해 두 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 또는 다른 코딩 에이전트를 사용하는 경우, 아래 프롬프트를 리포지토리의 에이전트 세션에 붙여 넣으세요. 이것은 향상된 거래 호출 지점을 찾아서 재작성합니다.
프롬프트는 독립형입니다 — 에이전트는 이 페이지에 접근할 필요가 없습니다. 에이전트용 문서, MCP 검색 및 기술에 대한 내용은 Helius for AI agents를 참조하세요.

다음 단계

Parsed Events 빠른 시작

첫 번째 거래를 파싱하고, 주소 기록을 가져오며, 결과를 페이지로 나눕니다.

파싱된 응답

파싱된 거래, 전송 및 명령어에 대한 필드 참조.

Parsed Streams

서버 측에서 필터링된 WebSocket을 통한 실시간 디코딩.

getTransactionsForAddress

토큰 계정 지원 및 서버 측 필터가 있는 원시 거래 기록.