왜 마이그레이션해야 하나요?
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/transactions → POST /v1/parsed-events/transactions
기존에 없던 새로운 옵션:
includeRawTransaction은 파싱된 결과와 함께 원래 Solana 거래 페이로드를 반환합니다.
거래 히스토리
GET /v0/addresses/{address}/transactions → POST /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.args 및 decoded.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에서 필드를 읽습니다. timestamp를 blockTime로 이름을 변경하고, description 및 type를 summary에서 읽습니다 (null를 확인합니다), 그리고 tokenAmount를 읽었던 이전 코드 대신 rawTokenAmount를 10^decimals로 나누십시오.3
유형 필터링 교체
이전 코드가
type=...를 전달한 경우, 반환된 항목을 클라이언트 측에서 parsed.summary.type 또는 parsed.instructions[]로 필터링하십시오 — 예를 들어, “명령어가 programId일 때 Jupiter이고 instructionName가 route인 경우”는 검증할 수 있는 것으로 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 또는 다른 코딩 에이전트를 사용하는 경우, 아래 프롬프트를 리포지토리의 에이전트 세션에 붙여 넣으세요. 이것은 향상된 거래 호출 지점을 찾아서 재작성합니다.다음 단계
Parsed Events 빠른 시작
첫 번째 거래를 파싱하고, 주소 기록을 가져오며, 결과를 페이지로 나눕니다.
파싱된 응답
파싱된 거래, 전송 및 명령어에 대한 필드 참조.
Parsed Streams
서버 측에서 필터링된 WebSocket을 통한 실시간 디코딩.
getTransactionsForAddress
토큰 계정 지원 및 서버 측 필터가 있는 원시 거래 기록.