> ## 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.
# getTransactionsForAddress 개요 및 튜토리얼
> 고급 필터링, 양방향 정렬, 효율적인 페이지 매김을 통해 이 Helius 전용 RPC 메서드를 사용하여 Solana 거래 내역을 조회하는 방법을 배우세요.
## 개요
[`getTransactionsForAddress`](/docs/ko/api-reference/rpc/http/gettransactionsforaddress)는 주소의 거래 내역을 고급 필터링, 유연한 정렬, 효율적인 페이지 매김과 함께 반환하는 Helius 전용 RPC 메서드입니다. 표준 Solana RPC의 일부가 아닙니다.
`getSignaturesForAddress`와는 달리, 이는 서명만 반환하고 연결된 토큰 계정을 건너뛰는 반면, `getTransactionsForAddress`는 지갑의 연결된 토큰 계정(ATA) 활동을 포함하여 전체 거래 데이터를 단일 호출로 반환할 수 있습니다. 이는 백필링, 인덱싱 및 분석을 위한 전체 주소 기록으로의 가장 빠른 경로를 제공합니다.
이 메서드는 호출 당 최대 1,000개의 전체 거래를 반환합니다.
시간순(오래된 것부터) 또는 역순(최신순)으로 정렬하세요.
시간 범위, 슬롯, 서명, 상태 및 토큰 전송으로 필터링합니다.
한 번의 호출로 전체 거래 세부정보를 얻고, 후속 getTransaction이 필요하지 않습니다.
주소의 연결된 토큰 계정의 거래를 포함하세요.
## 사용 시기
다음이 필요할 때 `getTransactionsForAddress`를 사용하세요.
* 연결된 토큰 계정을 포함한 전체 지갑 토큰 기록
* 인덱서나 데이터 파이프라인을 위한 빠른 단일 호출 백필링
* 시간 기반 또는 슬롯 기반 거래 분석 및 보고
* 성공 또는 실패한 거래만 유지하기 위한 상태 필터링
* 연대기적 역사 재생(이전 순서)
* 토큰 출시 분석: 첫 번째 발행 거래 및 초기 보유자
* 지갑 펀딩 내역 및 상대방 발견
* 특정 기간에 대한 컴플라이언스 및 감사 보고서
파싱된 이체 전용 기록(지불, 잔액 조정)의 경우 [`getTransfersByAddress`](/docs/ko/rpc/gettransfersbyaddress)를 대신 사용하십시오.
### 네트워크 지원
| 네트워크 | 지원 여부 | 보존 기간 |
| ------- | ----- | ----- |
| 메인넷 | 예 | 무제한 |
| Devnet | 예 | 2주 |
| Testnet | 아니오 | 해당 없음 |
## 빠른 시작
[Helius Dashboard](https://dashboard.helius.dev/api-keys)에서 API 키를 받으세요.
두 날짜 사이에 지갑의 모든 성공적인 거래를 시간 순으로 가져옵니다.
```javascript theme={"system"}
// Get successful transactions between Jan 1-31, 2025 in chronological order
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',
sortOrder: 'asc',
limit: 1000,
filters: {
blockTime: {
gte: 1735689600, // Jan 1, 2025
lt: 1738368000 // Before Feb 1, 2025
},
status: 'succeeded', // Only successful transactions
tokenAccounts: 'balanceChanged' // Include associated token accounts
}
}
]
})
});
const data = await response.json();
console.log('Successful transactions in January:', data.result.data);
```
이 예시는 주요 기능을 보여줍니다.
* **transactionDetails**: 전체 거래 데이터를 한 번의 호출로 얻기 위해 `'full'`로 설정
* **sortOrder**: OLD(오래된 것부터) 또는 NEW(최신 순) 정렬 사용
* **filters.blockTime**: `gte`(크거나 같은) 및 `lte`(작거나 같은)으로 시간 범위 설정
* **filters.status**: `'succeeded'` 또는 `'failed'` 거래만 필터링
* **filters.tokenAccounts**: 연결된 토큰 계정에 대한 전송, 발행 및 소각 포함
## 요청 매개변수
거래 내역을 쿼리할 계정의 Base-58로 인코딩된 공개 키
반환할 거래 세부정보 수준:
* `signatures`: 기본 서명 정보(더 빠름)
* `full`: 전체 거래 데이터(getTransaction 호출 불필요, 최대 1,000까지 지원)
결과 정렬 순서:
* `desc`: 최신순(기본값)
* `asc`: 오래된 것부터(연대기적, 역사 분석에 적합)
반환할 최대 거래 수:
* `transactionDetails: "signatures"` 시 최대 1000
* `transactionDetails: "full"` 시 최대 1000
이전 응답에서 받은 페이지 매김 토큰(형식: `"slot:position"`)
약정 수준: `finalized` 또는 `confirmed`. `processed` 약정은 지원하지 않습니다.
결과 범위를 좁히기 위한 고급 필터링 옵션입니다.
비교 연산자를 사용하여 슬롯 번호로 필터링: `gte`, `gt`, `lte`, `lt`
예제: `{ "slot": { "gte": 1000, "lte": 2000 } }`
Unix 타임스탬프를 사용하여 비교 연산자를 사용해 필터링: `gte`, `gt`, `lte`, `lt`, `eq`
예제: `{ "blockTime": { "gte": 1640995200, "lte": 1641081600 } }`
거래 서명을 비교 연산자를 사용해 필터링: `gte`, `gt`, `lte`, `lt`
예제: `{ "signature": { "lt": "SIGNATURE_STRING" } }`
거래 성공/실패 상태별로 필터링:
* `succeeded`: 성공한 거래만
* `failed`: 실패한 거래만
* `any`: 성공 및 실패 모두(기본값)
예제: `{ "status": "succeeded" }`
관련 토큰 계정의 거래를 필터링:
* `none`: 제공된 주소를 참조하는 거래만 반환(기본값)
* `balanceChanged`: 제공된 주소를 참조하거나 해당 주소가 소유한 토큰 계정의 잔액을 수정하는 거래를 반환(권장)
* `all`: 제공된 주소를 참조하거나 해당 주소가 소유한 모든 토큰 계정을 참조하는 거래를 반환
예제: `{ "tokenAccounts": "balanceChanged" }`
쿼리된 주소와 일치하는 상대방, 방향, 발행 또는 원시 금액 범위에 해당하는 토큰 전송에 참여한 거래로 결과를 좁힙니다. 모든 필드는 선택 사항이며 AND 논리로 결합됩니다.
예제: `{ "tokenTransfer": { "direction": "in", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }`
상대 주소. 다른 쪽이 이 주소인 전송과 일치합니다.
쿼리된 주소에 대한 전송 방향으로 필터링:
* `in`: 쿼리된 주소로 받은 전송
* `out`: 쿼리된 주소에서 보낸 전송
* `any`: 들어오는 전송 및 나가는 전송
필터링할 토큰 발행.
UI 또는 소수 조정 금액이 아닌 원시 온체인 금액을 사용하여 금액을 비교합니다. `gt`, `gte`, `lt` 및 `lte`을 지원합니다.
거래 데이터의 인코딩 형식(`transactionDetails: "full"`인 경우에만 적용). `getTransaction` API와 동일. 옵션: `json`, `jsonParsed`, `base64`, `base58`
반환할 최대 거래 버전을 설정합니다. 생략되면 레거시 거래만 반환됩니다. 모든 버전의 거래를 포함하려면 `0`로 설정하세요.
요청을 평가할 수 있는 최소 슬롯
### 계량
성공적인 응답은 반환된 내용에 따라 계량됩니다.
| 응답 유형 | 크레딧 |
| ---------- | ------------------------------- |
| 전체 거래 | 반환된 거래 100당 10크레딧, 올림; 최소 10크레딧 |
| 서명만 | 개수에 관계없이 10크레딧 일률 |
| 실패한 API 응답 | 무료 |
## 응답
응답 형식은 `transactionDetails`에 따라 다릅니다. 서명 모드는 가벼운 서명 기록을 반환하고, 전체 모드는 전체 거래 및 메타데이터 객체를 반환합니다.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"data": [
{
"signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv",
"slot": 1054,
"transactionIndex": 42,
"err": null,
"memo": null,
"blockTime": 1641038400,
"confirmationStatus": "finalized"
}
],
"paginationToken": "1055:5"
}
}
```
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"data": [
{
"slot": 1054,
"transactionIndex": 42,
"blockTime": 1641038400,
"transaction": {
"signatures": ["5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv"],
"message": {
"accountKeys": ["...", "..."],
"instructions": [...],
// Complete transaction structure
}
},
"meta": {
"err": null,
"fee": 5000,
"preBalances": [1000000, 2000000],
"postBalances": [999995000, 2000000],
"preTokenBalances": [
{
"accountIndex": 1,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "...",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "1500000",
"decimals": 6,
"uiAmount": 1.5,
"uiAmountString": "1.5"
}
}
],
"postTokenBalances": [
{
"accountIndex": 1,
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"owner": "...",
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"uiTokenAmount": {
"amount": "500000",
"decimals": 6,
"uiAmount": 0.5,
"uiAmountString": "0.5"
}
}
],
"innerInstructions": [...],
"logMessages": [...],
"computeUnitsConsumed": 2100
// Complete metadata — same shape as getTransaction
}
}
],
"paginationToken": "1055:5"
}
}
```
### 응답 필드
| 필드 | 타입 | 설명 |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `signature` | string | 거래 서명(base-58 인코딩). 서명 모드에서만. |
| `slot` | number | 이 거래가 포함된 블록의 슬롯. |
| `transactionIndex` | number | 블록 내에서 거래의 영(0) 기반 색인. 거래 정렬 및 블록 재구성에 유용. |
| `blockTime` | number \| null | Unix 타임스탬프(에포크 이후 초)로서의 예상 생성 시간. |
| `err` | object \| null | 거래가 실패한 경우 오류, 성공한 경우 null. 서명 모드에서만. |
| `memo` | string \| null | 거래와 연결된 메모. 서명 모드에서만. |
| `confirmationStatus` | string | 거래의 클러스터 확인 상태. 서명 모드에서만. |
| `transaction` | object | 전체 거래 데이터. 전체 모드에서만. |
| `meta` | object | 거래 상태 메타데이터 — `getTransaction`가 반환하는 것과 동일한 형식, `err`, `fee`, `preBalances`/`postBalances`, `preTokenBalances`/`postTokenBalances`, `innerInstructions`, `logMessages`, `computeUnitsConsumed` 포함. 전체 모드에서만. |
| `paginationToken` | string \| null | 다음 페이지를 가져올 토큰 또는 더 이상 결과가 없을 경우 null. |
`transactionIndex` 필드는 `getTransactionsForAddress`에만 있습니다. `getSignaturesForAddress`, `getTransaction`, `getTransactions`와 같은 다른 유사한 엔드포인트에는 이 필드가 없습니다.
전체 모드에서 `meta`는 `getTransaction`가 반환하는 것과 동일한 형식의 완전한 거래 메타데이터 객체입니다. 이는 `preTokenBalances` 및 `postTokenBalances`를 포함하므로, 후속 호출 없이 응답에서 직접 토큰 잔액 변경(예: 스왑 감지)을 계산할 수 있습니다.
## 필터
`slot`, `blockTime`, `signature`에 대해 비교 연산자 및 특별한 `status`, `tokenAccounts`, `tokenTransfer` 필터를 사용할 수 있습니다. 여러 필터를 결합하면 결과를 그 교차점으로 좁게 할 수 있습니다.
### 비교 연산자
이 연산자는 데이터 범위를 정확하게 제어할 수 있도록 데이터베이스 쿼리처럼 작동합니다.
| 연산자 | 전체 이름 | 설명 | 예제 |
| ----- | ------ | ----------------------------- | ------------------------------- |
| `gte` | 크거나 같음 | 지정된 값 이상을 포함 | `slot: { gte: 100 }` |
| `gt` | 크기 | 지정된 값보다 큼 포함 | `blockTime: { gt: 1641081600 }` |
| `lte` | 작거나 같음 | 지정된 값 이하를 포함 | `slot: { lte: 2000 }` |
| `lt` | 작음 | 지정된 값보다 작음 포함 | `blockTime: { lt: 1641168000 }` |
| `eq` | 같음 | 정확히 동일한 값을 포함(단지 `blockTime`) | `blockTime: { eq: 1641081600 }` |
### 열거형 필터
| 필터 | 설명 | 값 |
| --------------- | ----------------- | ---------------------------------- |
| `status` | 성공/실패로 거래 필터링 | `succeeded`, `failed`, 또는 `any` |
| `tokenAccounts` | 관련 토큰 계정으로 거래 필터링 | `none`, `balanceChanged`, 또는 `all` |
결합 필터 예제:
```javascript theme={"system"}
// Time range with successful transactions only
"filters": {
"blockTime": {
"gte": 1640995200,
"lte": 1641081600
},
"status": "succeeded"
}
// Slot range
"filters": {
"slot": {
"gte": 1000,
"lte": 2000
}
}
// Only failed transactions
"filters": {
"status": "failed"
}
```
### 연결된 토큰 계정
Solana에서는 지갑이 직접 토큰을 보유하지 않습니다. 대신 지갑이 토큰 계정을 소유하고, 이 토큰 계정이 토큰을 보유합니다. 누군가가 당신에게 USDC를 보내면, 이는 귀하의 주 지갑 주소가 아닌 귀하의 USDC 토큰 계정으로 갑니다.
이 메서드는 지갑의 연결된 토큰 계정(ATAs)을 포함한 **전체 토큰 기록**을 쿼리할 수 있기 때문에 독특합니다. `getSignaturesForAddress`와 같은 네이티브 RPC 메서드는 ATAs를 포함하지 않습니다.
`tokenAccounts` 필터는 이 동작을 제어합니다.
* **`none`** (기본값): 지갑 주소를 직접 참조하는 거래만 반환합니다. 직접적인 지갑 상호작용에만 관심이 있을 때 사용하세요.
* **`balanceChanged`** (권장됨): 지갑 주소를 참조하거나 지갑이 소유한 토큰 계정의 잔액을 수정하는 거래를 반환합니다. 수수료 수집이나 위임과 같은 스팸 및 관련 없는 작업을 필터링하여 의미 있는 지갑 활동의 깨끗한 뷰를 제공합니다.
* **`all`**: 지갑 주소를 참조하거나 지갑이 소유한 모든 토큰 계정을 참조하는 모든 거래를 반환합니다.
`tokenAccounts` 필터는 2022년 12월 이전의 거래를 지원하지 않습니다. 이는 슬롯 111,491,819에서 Solana에 도입된 토큰 전송 메타데이터에 의존합니다. 초기 활동을 포괄하려면 [historical token account workaround](#제한-사항-및-예외-사항)를 참조하세요.
### 토큰 전송 필터
`tokenTransfer` 필터는 쿼리된 주소가 특정 조건과 일치하는 토큰 전송(특정 상대방, 발행, 방향, 또는 금액 범위)에 참여한 거래로 결과를 좁힙니다.
이를 사용하여 다음과 같은 질문에 답할 수 있습니다.
* 이 지갑이 특정 상대방으로부터 USDC를 받은 시점은 언제입니까?
* 1,000 토큰 이상인 모든 발송 전송을 보여주세요.
* 이 지갑이 이 특정 발행을 처음으로 마친 시점은 언제입니까?
필터는 요청 구성의 `filters` 객체 내부의 선택적 필드입니다.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionsForAddress",
"params": [
"",
{
"filters": {
"tokenTransfer": {}
}
}
]
}
```
`tokenTransfer` 내부의 모든 필드는 선택 사항입니다. 여러 필드를 결합하면 AND로 처리됩니다.
| 필드 | 유형 | 기본값 | 설명 |
| ----------- | ---------------------------- | ------- | ------------------------------------------- |
| `with` | string (pubkey) | - | 상대방 주소입니다. 이 주소가 다른 쪽인 이전과 일치합니다. |
| `direction` | `"in"` \| `"out"` \| `"any"` | `"any"` | 쿼리된 주소가 송금, 수신, 또는 둘 중 어느 것인지 여부. |
| `mint` | string (pubkey) | - | 필터링할 토큰 발행. |
| `amount` | object | - | 금액 비교. UI 또는 소수 조정 금액이 아닌 원시 온체인 금액을 사용합니다. |
금액 범위 연산자:
| 연산자 | 의미 |
| ----- | ------ |
| `gt` | 엄격히 큼 |
| `gte` | 크거나 같음 |
| `lt` | 엄격히 작음 |
| `lte` | 작거나 같음 |
금액 연산자를 결합할 수 있습니다. 예: `{ "gte": 1000000, "lte": 5000000 }`는 닫힌 범위입니다. `tokenTransfer`는 다른 상위 레벨 필터(`slot`, `blockTime`, `status`, `tokenAccounts`)와 결합됩니다. 최종 결과는 교차점입니다.
## 예제
### 시간 기반 분석
월별 거래 보고서 생성하기:
```javascript theme={"system"}
// Get all successful transactions for January 2025
const startTime = Math.floor(new Date('2025-01-01').getTime() / 1000);
const endTime = Math.floor(new Date('2025-02-01').getTime() / 1000);
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionsForAddress",
"params": [
"WALLET_OR_PROGRAM_ADDRESS",
{
"transactionDetails": "signatures",
"filters": {
"blockTime": {
"gte": startTime,
"lt": endTime
},
"status": "succeeded"
},
"limit": 1000
}
]
}
```
분석을 위한 처리 과정:
```javascript theme={"system"}
// Calculate daily transaction volume
const dailyStats = {};
response.result.data.forEach(tx => {
const date = new Date(tx.blockTime * 1000).toISOString().split('T')[0];
dailyStats[date] = (dailyStats[date] || 0) + 1;
});
console.log('Daily Transaction Counts:', dailyStats);
```
### 토큰 발행 생성
특정 토큰에 대한 발행 생성 거래 찾기:
```javascript theme={"system"}
{
"jsonrpc": "2.0",
"id": "find-first-mints",
"method": "getTransactionsForAddress",
"params": [
MINT_ADDRESS, // Token mint address
{
"encoding": "jsonParsed",
"maxSupportedTransactionVersion": 0,
"sortOrder": "asc", // Chronological order from the beginning
"limit": 10,
"transactionDetails": "full"
}
]
}
```
유동성 풀 생성을 위해, 풀 주소를 쿼리하세요.
```javascript theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionsForAddress",
"params": [
"POOL_ADDRESS_HERE", // Raydium/Meteora pool address
{
"transactionDetails": "full",
"sortOrder": "asc", // First transaction is usually pool creation
"limit": 1
}
]
}
```
이는 토큰 발행 또는 유동성 풀이 생성된 정확한 순간을 찾아내며, 생성자 주소 및 초기 매개변수를 포함합니다.
### 펀딩 거래
특정 주소에 자금을 제공한 사람 찾기:
```javascript theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "getTransactionsForAddress",
"params": [
"TARGET_WALLET_ADDRESS",
{
"transactionDetails": "full",
"sortOrder": "asc", // Oldest first
"limit": 10
}
]
}
```
그런 다음 거래 데이터를 분석하여 SOL 전송을 찾습니다.
```javascript theme={"system"}
response.result.data.forEach(tx => {
// Look for SOL transfers in preBalances/postBalances
const balanceChanges = tx.meta.preBalances.map((pre, index) =>
tx.meta.postBalances[index] - pre
);
// Positive balance change = incoming SOL
balanceChanges.forEach((change, index) => {
if (change > 0) {
console.log(`Received ${change} lamports from ${tx.transaction.message.accountKeys[index]}`);
}
});
});
```
처음 몇 거래는 자금 제공원을 드러내며 관련 주소나 자금 패턴을 식별하는 데 도움이 될 수 있습니다.
### 토큰 전송
특정 토큰 동작을 격리하기 위해 `tokenTransfer`를 필터링합니다.
주소로의 USDC 유입:
```json theme={"system"}
{
"filters": {
"tokenTransfer": {
"direction": "in",
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
}
}
```
특정 상대방으로의 큰 발송 전송:
```json theme={"system"}
{
"filters": {
"tokenTransfer": {
"with": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
"direction": "out",
"amount": { "gte": 1000000000 }
}
}
}
```
슬롯 범위 및 상태와 결합:
```json theme={"system"}
{
"filters": {
"status": "succeeded",
"slot": { "gte": 100000000, "lte": 200000000 },
"tokenTransfer": {
"direction": "in",
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": { "gte": 5000000 }
}
}
}
```
## 페이지 매김
한도를 초과하는 거래가 있는 경우, 응답에서 받은 `paginationToken`를 사용하여 다음 페이지를 가져옵니다. 토큰은 API가 계속 진행할 위치를 알려주는 간단한 문자열 형식 `"slot:position"`입니다.
각 응답에서 페이지 매김 토큰을 사용하여 다음 페이지를 가져옵니다.
```javascript theme={"system"}
// First request
let paginationToken = null;
let allTransactions = [];
const getNextPage = async (paginationToken = null) => {
const params = [
'ADDRESS',
{
transactionDetails: 'signatures',
limit: 100,
...(paginationToken && { paginationToken })
}
];
const response = await fetch(rpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params
})
});
const data = await response.json();
return data.result;
};
// Paginate through all results
do {
const result = await getNextPage(paginationToken);
allTransactions.push(...result.data);
paginationToken = result.paginationToken;
console.log(`Fetched ${result.data.length} transactions, total: ${allTransactions.length}`);
} while (paginationToken);
```
### 여러 주소
하나의 요청에서 여러 주소를 쿼리할 수 없습니다. 각 주소 쿼리는 별도의 API 요청으로 처리되며, 이에 따라 계량됩니다. 여러 주소에 대한 거래를 가져오려면 동일한 시간 또는 슬롯 창 내에서 각 주소를 쿼리한 다음 병합하고 정렬합니다.
```javascript theme={"system"}
const addresses = ['Address1...', 'Address2...', 'Address3...'];
// Query all addresses in parallel with slot filter
const results = await Promise.all(
addresses.map(address =>
fetch(rpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params: [address, {
sortOrder: 'desc',
filters: { slot: { gt: 250000000 } }
}]
})
}).then(r => r.json())
)
);
// Merge and sort by slot
const allTransactions = results
.flatMap(r => r.result.data)
.sort((a, b) => b.slot - a.slot);
```
더 큰 기록 검색의 경우 시간 또는 슬롯 창(예: 1000 슬롯씩)을 반복하여 이 패턴을 반복하십시오.
## 모범 사례
**성능.** 전체 거래 데이터가 필요하지 않을 때는 `transactionDetails: "signatures"`를 사용하십시오. 더 나은 응답 시간을 위해 합리적인 페이지 크기를 사용하고, 더 타겟화된 쿼리를 위해 시간 범위 또는 특정 슬롯별로 필터링하십시오.
**필터링.** 광범위한 필터로 시작하여 점점 좁혀가세요. 분석 및 보고 워크플로를 위해 시간 기반 필터를 사용하고, 특정 거래 유형이나 시간 기간을 목표로 하는 정밀한 쿼리를 위해 여러 필터를 결합하십시오.
**페이지 매김.** 나중에 큰 쿼리를 다시 시작해야 할 경우 페이지 매김 토큰을 저장하십시오. 성능 계획을 위해 페이지 매김 깊이를 모니터링하고, 역사적인 이벤트를 연대순으로 재생해야 할 경우 오름차순을 사용하십시오.
**오류 처리.** 지수 백오프를 통해 속도 제한을 친절하게 처리하십시오. 요청 전에 주소를 검증하고, 적절할 때 결과를 캐시하여 API 사용을 줄이십시오.
## 제한 사항 및 예외 사항
일부 주소는 레거시 아카이브로 라우팅되고, 슬롯 스캔 백업으로 제한되거나 빈 값을 반환할 수 있습니다. 슬롯 111,491,819 이전의 토큰 계정 검색 또한 해결책이 필요합니다. 아래 섹션을 확장하여 전체 세부 정보를 확인하세요.
**옛 아카이브로 라우팅됨.** 이러한 주소에 대한 요청은 우리의 옛 아카이브 시스템으로 라우팅됩니다.
| 주소 | 이름 |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Stake11111111111111111111111111111111111111` | [스테이크 프로그램](https://orbmarkets.io/address/Stake11111111111111111111111111111111111111/history) |
| `StakeConfig11111111111111111111111111111111` | [스테이크 구성](https://orbmarkets.io/address/StakeConfig11111111111111111111111111111111/history) |
| `Sysvar1111111111111111111111111111111111111` | [Sysvar 소유자](https://orbmarkets.io/address/Sysvar1111111111111111111111111111111111111/history) |
| `AddressLookupTab1e1111111111111111111111111` | [주소 조회 테이블](https://orbmarkets.io/address/AddressLookupTab1e1111111111111111111111111/history) |
| `BPFLoaderUpgradeab1e11111111111111111111111` | [BPF 로더 업그레이드 가능](https://orbmarkets.io/address/BPFLoaderUpgradeab1e11111111111111111111111/history) |
**슬롯 스캔 백업.** 이러한 주소에 대한 요청은 우리의 새로운 아카이브 시스템으로 전달되며 슬롯별 스캔 접근 방식을 통해 쿼리가 가능합니다(최대 100 슬롯). 그러나 이 데이터는 인덱싱되지 않았습니다.
| 주소 | 이름 |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `11111111111111111111111111111111` | [시스템 프로그램](https://orbmarkets.io/address/11111111111111111111111111111111/history) |
| `ComputeBudget111111111111111111111111111111` | [컴퓨트 예산](https://orbmarkets.io/address/ComputeBudget111111111111111111111111111111/history) |
| `MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` | [메모 프로그램](https://orbmarkets.io/address/MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr/history) |
| `Vote111111111111111111111111111111111111111` | [투표 프로그램](https://orbmarkets.io/address/Vote111111111111111111111111111111111111111/history) |
**빈 반환(`is_reserved_address`).** 요청은 우리의 새로운 아카이브 시스템으로 전달되지만, 데이터는 인덱싱되지 않았며 쿼리는 빈 값을 반환합니다.
| 주소 | 이름 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `BPFLoader1111111111111111111111111111111111` | [BPF 로더(사용 중단됨)](https://orbmarkets.io/address/BPFLoader1111111111111111111111111111111111/history) |
| `BPFLoader2111111111111111111111111111111111` | [BPF 로더](https://orbmarkets.io/address/BPFLoader2111111111111111111111111111111111/history) |
| `Config1111111111111111111111111111111111111` | [구성 프로그램](https://orbmarkets.io/address/Config1111111111111111111111111111111111111/history) |
| `Ed25519SigVerify111111111111111111111111111` | [Ed25519 프로그램](https://orbmarkets.io/address/Ed25519SigVerify111111111111111111111111111/history) |
| `Feature111111111111111111111111111111111111` | [기능 프로그램](https://orbmarkets.io/address/Feature111111111111111111111111111111111111/history) |
| `KeccakSecp256k11111111111111111111111111111` | [Secp256k1 프로그램](https://orbmarkets.io/address/KeccakSecp256k11111111111111111111111111111/history) |
| `LoaderV411111111111111111111111111111111111` | [로더 V4](https://orbmarkets.io/address/LoaderV411111111111111111111111111111111111/history) |
| `NativeLoader1111111111111111111111111111111` | [네이티브 로더](https://orbmarkets.io/address/NativeLoader1111111111111111111111111111111/history) |
| `SysvarC1ock11111111111111111111111111111111` | [시계 Sysvar](https://orbmarkets.io/address/SysvarC1ock11111111111111111111111111111111/history) |
| `SysvarEpochSchedu1e111111111111111111111111` | [에포크 일정 Sysvar](https://orbmarkets.io/address/SysvarEpochSchedu1e111111111111111111111111/history) |
| `SysvarFees111111111111111111111111111111111` | [수수료 Sysvar](https://orbmarkets.io/address/SysvarFees111111111111111111111111111111111/history) |
| `Sysvar1nstructions1111111111111111111111111` | [지침 Sysvar](https://orbmarkets.io/address/Sysvar1nstructions1111111111111111111111111/history) |
| `SysvarRecentB1ockHashes11111111111111111111` | [최근 블록 해시 Sysvar](https://orbmarkets.io/address/SysvarRecentB1ockHashes11111111111111111111/history) |
| `SysvarRent111111111111111111111111111111111` | [임대 Sysvar](https://orbmarkets.io/address/SysvarRent111111111111111111111111111111111/history) |
| `SysvarRewards111111111111111111111111111111` | [보상 Sysvar](https://orbmarkets.io/address/SysvarRewards111111111111111111111111111111/history) |
| `SysvarS1otHashes111111111111111111111111111` | [슬롯 해시 Sysvar](https://orbmarkets.io/address/SysvarS1otHashes111111111111111111111111111/history) |
| `SysvarS1otHistory11111111111111111111111111` | [슬롯 기록 Sysvar](https://orbmarkets.io/address/SysvarS1otHistory11111111111111111111111111/history) |
| `SysvarStakeHistory1111111111111111111111111` | [스테이크 기록 Sysvar](https://orbmarkets.io/address/SysvarStakeHistory1111111111111111111111111/history) |
| `SysvarEpochRewards11111111111111111111111111` | [에포크 보상 Sysvar](https://orbmarkets.io/address/SysvarEpochRewards11111111111111111111111111/history) |
| `SysvarLastRestartS1ot1111111111111111111111` | [마지막 재시작 슬롯 Sysvar](https://orbmarkets.io/address/SysvarLastRestartS1ot1111111111111111111111/history) |
슬롯 111,491,819 이전에 토큰 계정 활동이 있는 주소의 경우 `tokenAccounts` 필터는 소유권을 결정할 수 없습니다. token balance metadata 내 `owner` 필드가 아직 존재하지 않았기 때문입니다. 완전한 결과를 얻기 위해, 초기 거래 지침을 파싱하여 해당 토큰 계정을 수동으로 발견한 후 각 하나에 대해 `getTransactionsForAddress`를 병렬적으로 쿼리할 수 있습니다.
```javascript theme={"system"}
const HELIUS_RPC = "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY";
const OWNER_CUTOFF_SLOT = 111_491_819;
async function rpcCall(method, params) {
const res = await fetch(HELIUS_RPC, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: "1", method, params }),
});
const json = await res.json();
if (json.error) throw new Error(json.error.message);
return json.result;
}
// Step 1: Discover token accounts owned by the address before the cutoff slot
// by parsing initializeAccount instructions and transfer authorities.
async function discoverHistoricalTokenAccounts(address) {
const tokenAccounts = new Set();
let paginationToken = null;
do {
const result = await rpcCall("getTransactionsForAddress", [
address,
{
transactionDetails: "full",
encoding: "jsonParsed",
maxSupportedTransactionVersion: 0,
sortOrder: "asc",
limit: 100,
filters: { slot: { lt: OWNER_CUTOFF_SLOT } },
...(paginationToken && { paginationToken }),
},
]);
if (!result?.data?.length) break;
for (const entry of result.data) {
const tx = entry.transaction;
const meta = entry.meta;
if (!tx || !meta) continue;
const allInstructions = [
...(tx.message?.instructions ?? []),
...(meta.innerInstructions ?? []).flatMap((inner) => inner.instructions ?? []),
];
for (const ix of allInstructions) {
// AToken program "create" instruction
if (ix.program === "spl-associated-token-account") {
if (ix.parsed?.type === "create" && ix.parsed.info?.wallet === address && ix.parsed.info?.account) {
tokenAccounts.add(ix.parsed.info.account);
}
continue;
}
if (ix.program !== "spl-token" && ix.program !== "spl-token-2022") continue;
const type = ix.parsed?.type;
const info = ix.parsed?.info;
// Token account initialization
if (type === "initializeAccount" || type === "initializeAccount2" || type === "initializeAccount3") {
if (info?.owner === address && info?.account) tokenAccounts.add(info.account);
}
// Transfers where our address is the authority (source account is ours)
if (type === "transfer" || type === "transferChecked") {
if (info?.authority === address && info?.source) tokenAccounts.add(info.source);
}
}
}
paginationToken = result.paginationToken;
} while (paginationToken);
return Array.from(tokenAccounts);
}
// Step 2: Fetch all signatures for an address with pagination
async function fetchAllSignatures(address, filters) {
const allSignatures = [];
let paginationToken = null;
do {
const result = await rpcCall("getTransactionsForAddress", [
address,
{
transactionDetails: "signatures",
sortOrder: "asc",
limit: 1000,
...(filters && { filters }),
...(paginationToken && { paginationToken }),
},
]);
if (!result?.data?.length) break;
allSignatures.push(...result.data);
paginationToken = result.paginationToken;
} while (paginationToken);
return allSignatures;
}
// Step 3: Get complete history by combining tokenAccounts:"all" with
// individual queries for historical token accounts
async function getCompleteHistory(address) {
const historicalAccounts = await discoverHistoricalTokenAccounts(address);
if (historicalAccounts.length === 0) {
return fetchAllSignatures(address, { tokenAccounts: "all" });
}
// Query main address with tokenAccounts:"all" + each historical account in parallel
const results = await Promise.all([
fetchAllSignatures(address, { tokenAccounts: "all" }),
...historicalAccounts.map((addr) => fetchAllSignatures(addr)),
]);
// Merge and deduplicate by signature
const seen = new Set();
const merged = [];
for (const batch of results) {
for (const tx of batch) {
if (!seen.has(tx.signature)) {
seen.add(tx.signature);
merged.push(tx);
}
}
}
return merged.sort((a, b) => a.slot - b.slot);
}
```
## getSignaturesForAddress와 무엇이 다른가요?
표준 `getSignaturesForAddress` 메서드를 잘 알고 있다면, `getTransactionsForAddress`는 다단계 워크플로우를 단일 호출로 요약하고 필터링, 정렬, 토큰 계정 지원을 추가합니다.
### 한 번의 호출로 전체 거래 가져오기
`getSignaturesForAddress`를 사용하면 두 단계가 필요합니다.
```javascript theme={"system"}
// Step 1: Get signatures
const signatures = await connection.getSignaturesForAddress(address, { limit: 1000 });
// Step 2: Get transaction details (1,000 additional calls!)
const transactions = await Promise.all(
signatures.map(sig => connection.getTransaction(sig.signature))
);
```
`getTransactionsForAddress`를 사용하면 한 번의 호출입니다.
```javascript theme={"system"}
const response = await fetch(heliusRpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params: [
address,
{
transactionDetails: 'full',
limit: 1000
}
]
})
});
```
### 한 번의 호출로 토큰 기록 가져오기
`getSignaturesForAddress`를 사용하면 먼저 `getTokenAccountsByOwner`를 호출한 후 각 토큰 계정에 대해 쿼리해야 합니다.
```javascript theme={"system"}
// OLD WAY (with getSignaturesForAddress)
// Step 1: Get all token accounts owned by this wallet
const tokenAccounts = await connection.getTokenAccountsByOwner(
new PublicKey(walletAddress),
{ programId: TOKEN_PROGRAM_ID }
);
// Step 2: Fetch signatures for the wallet itself
const walletSignatures = await connection.getSignaturesForAddress(
new PublicKey(walletAddress),
{ limit: 1000 }
);
// Step 3: Fetch signatures for EVERY token account (this is the painful part)
const tokenAccountSignatures = await Promise.all(
tokenAccounts.value.map(async (account) => {
return connection.getSignaturesForAddress(
account.pubkey,
{ limit: 1000 }
);
})
);
// Step 4: Merge all results together
const allSignatures = [
...walletSignatures,
...tokenAccountSignatures.flat()
];
// Step 5: Deduplicate (many transactions touch multiple accounts)
const seen = new Set();
const uniqueSignatures = allSignatures.filter((sig) => {
if (seen.has(sig.signature)) {
return false;
}
seen.add(sig.signature);
return true;
});
// Step 6: Sort chronologically
const sortedSignatures = uniqueSignatures.sort(
(a, b) => a.slot - b.slot
);
return sortedSignatures;
```
`getTransactionsForAddress`를 사용하면 `filters.tokenAccounts`를 설정하기만 하면 됩니다.
```javascript theme={"system"}
// NEW WAY (with getTransactionsForAddress)
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: "helius-example",
method: "getTransactionsForAddress",
params: [
walletAddress,
{
filters: {
tokenAccounts: "all"
},
sortOrder: "asc",
limit: 100
}
]
})
});
const { result } = await response.json();
return result;
```
### 추가 기능
`sortOrder: 'asc'`로 오래된 것부터 최신순으로 거래 정렬.
`blockTime` 필터를 사용하여 시간 범위로 필터링.
`status` 필터로 성공한 거래 또는 실패한 거래만 가져오기.
혼란스러운 `before`/`until` 서명 대신 `paginationToken` 사용.
## 다음 단계
getTransactionsForAddress를 사용하여 Solana 인덱스를 백필링하고 동기화하십시오.
지불 및 화해를 위한 파싱된 이체 전용 기록.
getTransactionsForAddress에 대한 전체 요청 및 응답 스키마.
모든 Solana 역사적 데이터 메서드를 비교.