왜 마이그레이션할까요?
Solana에서 주소의 거래 내역을 가져오는 표준 방법은 두 단계로 이루어집니다. 서명을 나열하기 위해getSignaturesForAddress를 호출한 다음, 세부 정보를 가져오기 위해 서명당 getTransaction를 호출합니다. 1,000개의 거래의 경우, 이는 1,001개의 HTTP 요청을 의미합니다.
getTransactionsForAddress는 두 단계를 하나의 호출로 압축하는 Helius 전용 RPC 메서드입니다. 요청당 최대 1,000개의 전체 거래를 반환하며, 표준 메서드에는 없는 필터링, 양방향 정렬 및 토큰 계정 지원 기능을 제공합니다.
결과: 약 10배 적은 크레딧, 1,000배 적은 왕복 횟수, 그리고
getTransaction 팬 아웃에 대한 클라이언트 측 배칭, 속도 제한 처리 또는 재시도 로직이 필요하지 않습니다.
전후 비교
다음은 주소의 마지막 1,000개의 거래를 전체 세부 정보와 함께 가져오는 동일한 작업입니다:getTransactionsForAddress는 표준 Solana RPC의 일부가 아니므로 @solana/web3.js에는 이에 대한 Connection 헬퍼가 없습니다. 앞서 설명한 것처럼 원시 JSON-RPC 요청으로 호출하세요. 이는 귀하의 RPC 트래픽과 동일한 Helius 엔드포인트에서 작동합니다.
매개변수 매핑
이전의 2단계 흐름의 모든 옵션에는 직접적인 대응이 있습니다. 대부분의 이름은 변경되지 않으며, 페이지 매김만 다르게 작동합니다.From getSignaturesForAddress
From getTransaction
두 가지 기능은 이전에는 대응하는 것이 전혀 없었습니다:
filters— 결과를blockTime,slot,status,tokenTransfer또는tokenAccounts로 좁혀주는 기능으로, 모든 것을 가져와서 코드에서 필터링하는 대신 서버 측에서 필터링합니다.sortOrder: "asc"— 연대순(오래된 것부터) 결과로, 표준 메서드가 전체 내역을 가져오고 역순으로 반환하지 않고는 제공할 수 없는 기능입니다.
마이그레이션 단계
1
Helius 엔드포인트 사용 확인
getTransactionsForAddress는 Helius 전용입니다. https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY(및 devnet)에서 작동합니다. 이는 Helius 고객이라면 기존 호출이 이미 사용하는 동일한 엔드포인트에서 작동합니다. API 키나 플랜 변경은 필요하지 않습니다.2
두 단계 가져오기 호출을 하나로 대체
getSignaturesForAddress 호출과 getTransaction 루프를 삭제하세요. 하나의 getTransactionsForAddress 요청을 transactionDetails: "full"와 함께 수행하며, 매개변수 매핑에 표시된 대로 encoding, maxSupportedTransactionVersion, commitment 값을 전달합니다.서명만 필요한 경우(예: 기존 파이프라인에 전달하기 위해) transactionDetails: "signatures"를 대신 사용하세요. 이는 호출당 10개의 크레딧이 소요됩니다.3
응답 처리 업데이트
응답 구조는 세 가지 방식으로 변경됩니다:
- 결과는
result.data(배열)에 있으며,result에 직접 포함되지 않습니다. - 각 전체 모드 항목은
{ slot, transactionIndex, blockTime, transaction, meta }입니다.transaction및meta객체는getTransaction가 반환하는 것과 동일한 형태를 가지고 있어, 파싱 코드를 변경할 필요가 없습니다. - 서명 모드 항목은
getSignaturesForAddress출력(signature,slot,err,memo,blockTime,confirmationStatus)과 일치하며 새로운transactionIndex필드를 추가합니다.
getTransaction 호출이 null를 반환할 수 있었습니다. getTransactionsForAddress에서는 result.data의 각 항목이 완전한 거래입니다. 누락된 세부 정보에 대한 null 처리 코드를 제거하세요.4
서명 기반 페이징 대체
before 커서 루프를 paginationToken로 교체하세요:paginationToken가 null일 때 끝납니다. 더 이상 서명 목록을 비교하거나 마지막 서명을 스스로 추적할 필요가 없습니다.until를 사용하여 알려진 서명에서 중지하려는 경우, 이를 filters.signature: { gt: "KNOWN_SIGNATURE" }로 교체하세요. 특정 시점에서 중지하기 위해 사용한 경우, filters.blockTime 또는 filters.slot가 일반적으로 더 적합합니다.5
선택 사항: 전체 토큰 내역 활성화
이전 패턴은 모든 토큰 계정에 대한 서명을 가져오고
getTokenAccountsByOwner를 호출하지 않으면 연관된 토큰 계정(ATA) 활동을 전혀 감지하지 못합니다. 이를 포함하려면 다음 필터를 추가하세요:balanceChanged는 지갑을 참조하거나 해당 토큰 계정이 소유한 토큰 계정의 잔액을 변경하는 트랜잭션을 반환하여 스팸을 필터링합니다. 연관된 토큰 계정을 참조하여 none/balanceChanged/all 옵션 및 2022년 이전 주의 사항에 대한 정보를 확인하세요.6
이전 출력과 비교 확인
샘플 주소에 대해, 두 가지 방법을 모두 사용하여 내역을 가져오고 서명 집합을 비교하세요.
filters.tokenAccounts이 설정되지 않은 상태(기본 none)에서 getTransactionsForAddress는 동일한 범위에 대해 getSignaturesForAddress와 동일한 거래를 반환합니다. 그런 다음 이전 코드 경로를 배포하고 제거하세요.검토할 행동 차이
대부분의 마이그레이션은 쉽게 대체 가능하지만 출하 전에 다음을 확인하세요:- 커밋.
processed는 지원되지 않으므로confirmed또는finalized를 사용하세요. 이전 코드가processed에서 최근 내역을 폴링했다면confirmed로 전환하세요. - 계량. 전체 거래 응답은 반환된 100개의 거래당 10 크레딧(최소 10 크레딧)을 소모합니다. 서명 전용 응답은 호출당 10 크레딧이 소모됩니다. 이전 패턴은 호출당 1 크레딧의 비용이 들었으며, 요청당 저렴했지만 가져온 거래당 훨씬 더 비쌌습니다. 실패한 응답은 무료입니다. 계량을 참조하세요.
- 네트워크 지원. 메인넷은 무제한 보존을 지원합니다. Devnet은 2주 보존을 지원합니다. Testnet은 지원되지 않습니다.
- 예약된 주소. 시스템 주소(투표 프로그램, 시스템 프로그램, 시스템 변수)의 작은 집합은 백업 아카이브 경로로 라우팅되거나 비어 있는 상태로 반환됩니다. 이를 인덱싱하는 경우 제한 사항 및 엣지 케이스를 검토하세요.
- 다중 주소. 이전 흐름과 마찬가지로, 하나의 요청은 하나의 주소만 처리합니다. 주소를 병렬로 쿼리하고 병합합니다. 다중 주소를 참조하세요.
자주 묻는 질문
getTransactionsForAddress는 표준 Solana RPC 메서드인가요?
아니요. 이는 Helius 전용 메서드로 Helius RPC 엔드포인트에서 제공됩니다. 표준 Solana RPC 및 기타 제공자는getSignaturesForAddress 및 getTransaction만 제공합니다. 다른 RPC 호출은 영향을 받지 않습니다. 이 메서드는 전체 표준 RPC 표면과 함께 동일한 엔드포인트에 있습니다.
마이그레이션 후에도 getTransaction이 필요한가요?
사용자가 붙여 넣은 특정 거래를 검증하는 등 이미 서명이 있는 상태에서 주소 컨텍스트 없이 한 번 조회하는 경우에만 필요합니다. 주소 기반 내역 — 백필, 인덱싱, 지갑 활동 피드 등 모든 경우에getTransactionsForAddress가 두 메서드를 대체합니다.
@solana/web3.js와 함께 작동하나요?
이 메서드는Connection 클래스에 포함되어 있지 않지만, 로컬 Helius RPC URL을 사용하여 HTTP 클라이언트와 함께 사용할 수 있습니다. 예제에서와 같이 표준 JSON-RPC 본문으로 fetch(또는 사용 언어에 맞는 방법)을 사용하세요. 나머지 RPC 호출에는 Connection를 계속 사용할 수 있습니다.
getSignaturesForAddress와 동일한 거래를 반환하나요?
예. 기본 설정(filters.tokenAccounts: "none")에서는 조회된 주소를 참조하는 거래를 반환합니다. 이는 getSignaturesForAddress와 동일한 집합입니다. tokenAccounts를 balanceChanged 또는 all로 설정하면 더 많은 활동을 추가로 표시합니다. 이는 표준 메서드가 볼 수 없는 지갑 관련 토큰 계정 활동을 추가합니다.
이전 패턴과 비교하여 비용이 어떻게 되나요?
1,000개의 전체 거래를 가져오면getTransactionsForAddress로 100 크레딧이 소모되며, getSignaturesForAddress + getTransaction로는 약 1,001 크레딧(및 1,001 요청)이 소모됩니다. 서명 전용 응답은 호출당 10 크레딧이 소모됩니다. 전체 가격은 Helius 크레딧을 참조하세요.
AI 에이전트를 통해 마이그레이션 수행하기
Claude Code, Cursor 또는 기타 코딩 에이전트를 사용하는 경우, 아래 프롬프트를 저장소의 에이전트 세션에 붙여넣으세요. 이는 코드베이스의 이전 패턴을 찾아서 재작성합니다.다음 단계
getTransactionsForAddress 가이드
필터, 정렬, 페이지 매김 및 토큰 계정에 대한 전체 튜토리얼입니다.
API 참조
전체 요청 및 응답 스키마.
인덱싱 가이드
getTransactionsForAddress를 사용하여 Solana 인덱스를 백필 및 동기화합니다.
역사적 데이터 개요
모든 Solana 역사적 데이터 방법을 비교합니다.