> ## 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. # getSignaturesForAddress + getTransaction에서 getTransactionsForAddress로 마이그레이션 > getSignaturesForAddress + getTransaction 루프를 단일 getTransactionsForAddress 호출로 대체합니다. 매개변수 매핑, 전후 코드, 페이지 매김 변경 사항 및 마이그레이션을 자동화하는 복사-붙여넣기 AI 에이전트 프롬프트가 포함됩니다. ## 왜 마이그레이션할까요? Solana에서 주소의 거래 내역을 가져오는 표준 방법은 두 단계로 이루어집니다. 서명을 나열하기 위해 `getSignaturesForAddress`를 호출한 다음, 세부 정보를 가져오기 위해 서명당 `getTransaction`를 호출합니다. 1,000개의 거래의 경우, 이는 1,001개의 HTTP 요청을 의미합니다. [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)는 두 단계를 하나의 호출로 압축하는 Helius 전용 RPC 메서드입니다. 요청당 최대 1,000개의 전체 거래를 반환하며, 표준 메서드에는 없는 필터링, 양방향 정렬 및 토큰 계정 지원 기능을 제공합니다. | | `getSignaturesForAddress` + `getTransaction` | `getTransactionsForAddress` | | --------------------- | -------------------------------------------- | ------------------------------ | | 1,000개의 거래 요청 | 1,001 | 1 | | 1,000개의 전체 거래에 대한 크레딧 | \~1,001 (호출당 1 크레딧) | 100 (100개의 거래당 10 크레딧) | | 연관된 토큰 계정(ATA) 내역 | 미포함 | `filters.tokenAccounts`를 통해 포함 | | 시간 및 슬롯 범위 필터 | 없음 | 있음 | | 상태 필터(성공/실패) | 없음 | 있음 | | 정렬 순서 | 최신순만 가능 | 최신순 또는 오래된 순 가능 | | 페이지 매김 | `before`/`until` 서명 | `paginationToken` | 결과: 약 10배 적은 크레딧, 1,000배 적은 왕복 횟수, 그리고 `getTransaction` 팬 아웃에 대한 클라이언트 측 배칭, 속도 제한 처리 또는 재시도 로직이 필요하지 않습니다. ## 전후 비교 다음은 주소의 마지막 1,000개의 거래를 전체 세부 정보와 함께 가져오는 동일한 작업입니다: ```javascript Before (two methods) theme={"system"} const rpcUrl = 'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY'; // Step 1: Get signatures (1 request) const sigResponse = await fetch(rpcUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getSignaturesForAddress', params: ['YOUR_ADDRESS_HERE', { limit: 1000 }] }) }); const { result: signatures } = await sigResponse.json(); // Step 2: Get transaction details (1,000 additional requests) const transactions = await Promise.all( signatures.map(async (sig) => { const txResponse = await fetch(rpcUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransaction', params: [sig.signature, { maxSupportedTransactionVersion: 0 }] }) }); const { result } = await txResponse.json(); return result; }) ); ``` ```javascript After (one method) theme={"system"} const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ 'YOUR_ADDRESS_HERE', { transactionDetails: 'full', maxSupportedTransactionVersion: 0, limit: 1000 } ] }) }); const { result } = await response.json(); const transactions = result.data; // Full transactions, same shape as getTransaction ``` `getTransactionsForAddress`는 표준 Solana RPC의 일부가 아니므로 `@solana/web3.js`에는 이에 대한 `Connection` 헬퍼가 없습니다. 앞서 설명한 것처럼 원시 JSON-RPC 요청으로 호출하세요. 이는 귀하의 RPC 트래픽과 동일한 Helius 엔드포인트에서 작동합니다. ## 매개변수 매핑 이전의 2단계 흐름의 모든 옵션에는 직접적인 대응이 있습니다. 대부분의 이름은 변경되지 않으며, 페이지 매김만 다르게 작동합니다. ### From getSignaturesForAddress | Old option | New equivalent | | ---------------- | ------------------------------------------------------------------- | | `limit` | `limit` — 최대 1,000개 동일 | | `before` | `paginationToken` 이전 응답에서 | | `until` | `filters.signature.gt` | | `commitment` | `commitment` — `confirmed` 또는 `finalized`만 가능; `processed`는 지원되지 않음 | | `minContextSlot` | `minContextSlot` — 변경 없음 | ### From getTransaction | Old option | New equivalent | | -------------------------------- | ------------------------------------------------- | | `encoding` | `encoding` — `transactionDetails`가 `"full"`일 때 적용 | | `maxSupportedTransactionVersion` | `maxSupportedTransactionVersion` — 변경 없음 | | `commitment` | `commitment` — 위와 동일한 규칙 | 두 가지 기능은 이전에는 대응하는 것이 전혀 없었습니다: * `filters` — 결과를 `blockTime`, `slot`, `status`, `tokenTransfer` 또는 `tokenAccounts`로 좁혀주는 기능으로, 모든 것을 가져와서 코드에서 필터링하는 대신 서버 측에서 필터링합니다. * `sortOrder: "asc"` — 연대순(오래된 것부터) 결과로, 표준 메서드가 전체 내역을 가져오고 역순으로 반환하지 않고는 제공할 수 없는 기능입니다. ## 마이그레이션 단계 `getTransactionsForAddress`는 Helius 전용입니다. `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`(및 devnet)에서 작동합니다. 이는 Helius 고객이라면 기존 호출이 이미 사용하는 동일한 엔드포인트에서 작동합니다. API 키나 플랜 변경은 필요하지 않습니다. `getSignaturesForAddress` 호출과 `getTransaction` 루프를 삭제하세요. 하나의 `getTransactionsForAddress` 요청을 `transactionDetails: "full"`와 함께 수행하며, [매개변수 매핑](#매개변수-매핑)에 표시된 대로 `encoding`, `maxSupportedTransactionVersion`, `commitment` 값을 전달합니다. 서명만 필요한 경우(예: 기존 파이프라인에 전달하기 위해) `transactionDetails: "signatures"`를 대신 사용하세요. 이는 호출당 10개의 크레딧이 소요됩니다. 응답 구조는 세 가지 방식으로 변경됩니다: * 결과는 `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 처리 코드를 제거하세요. `before` 커서 루프를 `paginationToken`로 교체하세요: ```javascript theme={"system"} let paginationToken = null; const allTransactions = []; do { const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ 'YOUR_ADDRESS_HERE', { transactionDetails: 'full', maxSupportedTransactionVersion: 0, limit: 1000, ...(paginationToken && { paginationToken }) } ] }) }); const { result } = await response.json(); allTransactions.push(...result.data); paginationToken = result.paginationToken; } while (paginationToken); ``` 루프는 `paginationToken`가 `null`일 때 끝납니다. 더 이상 서명 목록을 비교하거나 마지막 서명을 스스로 추적할 필요가 없습니다. `until`를 사용하여 알려진 서명에서 중지하려는 경우, 이를 `filters.signature: { gt: "KNOWN_SIGNATURE" }`로 교체하세요. 특정 시점에서 중지하기 위해 사용한 경우, `filters.blockTime` 또는 `filters.slot`가 일반적으로 더 적합합니다. 이전 패턴은 모든 토큰 계정에 대한 서명을 가져오고 `getTokenAccountsByOwner`를 호출하지 않으면 연관된 토큰 계정(ATA) 활동을 전혀 감지하지 못합니다. 이를 포함하려면 다음 필터를 추가하세요: ```json theme={"system"} { "filters": { "tokenAccounts": "balanceChanged" } } ``` `balanceChanged`는 지갑을 참조하거나 해당 토큰 계정이 소유한 토큰 계정의 잔액을 변경하는 트랜잭션을 반환하여 스팸을 필터링합니다. [연관된 토큰 계정](/docs/ko/rpc/gettransactionsforaddress#연결된-토큰-계정)을 참조하여 `none`/`balanceChanged`/`all` 옵션 및 2022년 이전 주의 사항에 대한 정보를 확인하세요. 샘플 주소에 대해, 두 가지 방법을 모두 사용하여 내역을 가져오고 서명 집합을 비교하세요. `filters.tokenAccounts`이 설정되지 않은 상태(기본 `none`)에서 `getTransactionsForAddress`는 동일한 범위에 대해 `getSignaturesForAddress`와 동일한 거래를 반환합니다. 그런 다음 이전 코드 경로를 배포하고 제거하세요. ## 검토할 행동 차이 대부분의 마이그레이션은 쉽게 대체 가능하지만 출하 전에 다음을 확인하세요: * **커밋.** `processed`는 지원되지 않으므로 `confirmed` 또는 `finalized`를 사용하세요. 이전 코드가 `processed`에서 최근 내역을 폴링했다면 `confirmed`로 전환하세요. * **계량.** 전체 거래 응답은 반환된 100개의 거래당 10 크레딧(최소 10 크레딧)을 소모합니다. 서명 전용 응답은 호출당 10 크레딧이 소모됩니다. 이전 패턴은 호출당 1 크레딧의 비용이 들었으며, 요청당 저렴했지만 가져온 거래당 훨씬 더 비쌌습니다. 실패한 응답은 무료입니다. [계량](/docs/ko/rpc/gettransactionsforaddress#계량)을 참조하세요. * **네트워크 지원.** 메인넷은 무제한 보존을 지원합니다. Devnet은 2주 보존을 지원합니다. Testnet은 지원되지 않습니다. * **예약된 주소.** 시스템 주소(투표 프로그램, 시스템 프로그램, 시스템 변수)의 작은 집합은 백업 아카이브 경로로 라우팅되거나 비어 있는 상태로 반환됩니다. 이를 인덱싱하는 경우 [제한 사항 및 엣지 케이스](/docs/ko/rpc/gettransactionsforaddress#제한-사항-및-예외-사항)를 검토하세요. * **다중 주소.** 이전 흐름과 마찬가지로, 하나의 요청은 하나의 주소만 처리합니다. 주소를 병렬로 쿼리하고 병합합니다. [다중 주소](/docs/ko/rpc/gettransactionsforaddress#여러-주소)를 참조하세요. ## 자주 묻는 질문 ### 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 크레딧](/docs/ko/billing/credits)을 참조하세요. ## AI 에이전트를 통해 마이그레이션 수행하기 Claude Code, Cursor 또는 기타 코딩 에이전트를 사용하는 경우, 아래 프롬프트를 저장소의 에이전트 세션에 붙여넣으세요. 이는 코드베이스의 이전 패턴을 찾아서 재작성합니다. ````markdown theme={"system"} Migrate this codebase from the two-step Solana transaction history pattern (getSignaturesForAddress followed by getTransaction) to the single Helius RPC method getTransactionsForAddress. ## Background getTransactionsForAddress is a Helius-exclusive JSON-RPC method served on standard Helius RPC endpoints (https://mainnet.helius-rpc.com/?api-key=...). It returns up to 1,000 full transactions per call, replacing one getSignaturesForAddress call plus one getTransaction call per signature. Docs: https://www.helius.dev/docs/rpc/gettransactionsforaddress.md ## Step 1: Find the old pattern Search for: - getSignaturesForAddress calls (via @solana/web3.js Connection, raw JSON-RPC, or another SDK) whose signatures are then passed to getTransaction / getParsedTransaction / getTransactions - Pagination loops using `before` or `until` signature cursors - getTokenAccountsByOwner calls used only to fetch per-token-account signature history Leave standalone getTransaction calls (single-signature lookups with no address context) unchanged. ## Step 2: Rewrite each call site Replace the two-step flow with one raw JSON-RPC request (web3.js has no Connection helper for this method): ```javascript const response = await fetch(HELIUS_RPC_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getTransactionsForAddress', params: [ address, // base-58 string { transactionDetails: 'full', // or 'signatures' if only signatures were used maxSupportedTransactionVersion: 0, // carry over from the old getTransaction options encoding: 'json', // carry over ('json', 'jsonParsed', 'base64', 'base58') limit: 1000, // up to 1,000 // paginationToken: '...', // from the previous response, for page 2+ // sortOrder: 'desc', // 'desc' (default, newest first) or 'asc' // filters: { ... } // optional, see mapping below } ] }) }); const { result } = await response.json(); // result.data -> array of transactions // result.paginationToken -> string cursor, or null when done ``` Parameter mapping: - limit -> limit - before: -> paginationToken (preferred) or filters: { signature: { lt: } } - until: -> filters: { signature: { gt: } } - commitment -> commitment ('confirmed' or 'finalized' only; if the old code used 'processed', use 'confirmed') - minContextSlot -> minContextSlot - encoding / maxSupportedTransactionVersion (from getTransaction) -> same names, top level of the config object Response shape: - Full mode: each entry is { slot, transactionIndex, blockTime, transaction, meta }. transaction and meta are identical in shape to getTransaction results, so existing parsing code carries over. Entries are never null - remove null-handling that existed for missing getTransaction results. - Signatures mode: entries match getSignaturesForAddress output ({ signature, slot, err, memo, blockTime, confirmationStatus }) plus transactionIndex. Pagination: loop while result.paginationToken is non-null, passing it back as paginationToken. Remove manual last-signature tracking. If the old code fetched signatures for the wallet's token accounts too (getTokenAccountsByOwner + per-account getSignaturesForAddress), replace all of it with one call using filters: { tokenAccounts: 'balanceChanged' } and delete the merge/dedupe logic. ## Step 3: Constraints and cleanup - The endpoint must be a Helius RPC URL; other providers do not serve this method. Do not change endpoints for other RPC calls. - Remove now-unused batching, throttling, and retry helpers that existed only for the getTransaction fan-out. - One request covers one address; keep parallel queries for multi-address code. - Preserve the surrounding code style and error handling conventions. ## Step 4: Verify - Run the project's type checks and tests. - Do NOT make any RPC calls yourself. Instead, write a standalone script (e.g. scripts/verify-gtfa-migration.mjs) that fetches history for one address both ways - the old getSignaturesForAddress + getTransaction flow and the new getTransactionsForAddress call with default filters - and prints whether the signature sets match, listing any differences. Read the RPC URL from an environment variable and the address from a CLI argument; never hardcode an API key. - Tell the user how to run it, for example: HELIUS_RPC_URL="https://mainnet.helius-rpc.com/?api-key=..." \ node scripts/verify-gtfa-migration.mjs
- Summarize every call site changed and flag any you were unsure about. ```` 이 프롬프트는 독립적이므로 에이전트가 이 페이지에 접근할 필요가 없습니다. 에이전트 준비 문서, MCP 검색 및 기술에 대한 내용은 [AI 에이전트를 위한 Helius](/docs/ko/agents/overview)를 참조하세요. ## 다음 단계 필터, 정렬, 페이지 매김 및 토큰 계정에 대한 전체 튜토리얼입니다. 전체 요청 및 응답 스키마. getTransactionsForAddress를 사용하여 Solana 인덱스를 백필 및 동기화합니다. 모든 Solana 역사적 데이터 방법을 비교합니다.