> ## 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.
# getTransfersByAddress 개요 및 튜토리얼
> 솔라나 주소의 읽기 쉬운 토큰 및 기본 SOL 전송 객체를 민트, 시간, 금액 및 상대방 필터로 쿼리합니다.
## 개요
[`getTransfersByAddress`](/docs/ko/api-reference/rpc/http/gettransfersbyaddress)는 지갑 주소에 대한 사람 친화적인 읽기 쉬운 토큰 및 기본 SOL 전송 객체를 반환하는 Helius 전용 RPC 메서드입니다. 표준 Solana RPC의 일부가 아닙니다.
전송 활동에 중점을 두어 전체 거래 페이로드 대신 간결한 전송 기록을 반환합니다. 각 기록은 소유자 및 토큰 계정, 민트, 원시 금액, 소수, UI 금액, 명령어 위치 및 확인 상태로 정규화되어 Solana 토큰 파싱을 다시 구현하지 않고도 균형 이동을 조정할 수 있습니다.
이 메서드는 [개발자 계획](/docs/ko/billing/plans) 이상이 필요하며 요청당 10 크레딧이 소모됩니다.
파싱된 계정, 금액, 소수 및 전송 유형과 함께 읽기 쉬운 전송 기록 반환.
SOL, WSOL, Token-2022 수수료, 민트, 소각 및 계정 소유자 변경을 모델링하여 정확한 잔액 조정 가능.
민트 주소, 블록 시간 범위 또는 원시 금액 범위로 전송 기록 제한.
`with` 및 `direction`로 발신자 또는 수신자로 필터링.
## 사용 시점
`getTransfersByAddress`를 사용해야 할 때:
* 결제 또는 전송 모니터링을 위한 지갑 전송 기록
* 포트폴리오 활동 및 토큰 이동 분석
* 신뢰할 수 있는 대차 대조를 위한 잔액 대조
* 상대방별 전송 보고서(누가 무엇을 보냈는지 또는 받았는지)
* 솔리드 파서 없이 정규화된 SOL/WSOL, Token-2022 수수료, 민트 및 소각 처리
전체 거래 데이터, 서명 전용 기록 또는 비전송 활동이 필요할 경우 [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)를 대신 사용합니다. 일반적인 패턴은 여기에서 전송을 페이지별로 확인한 후 [`getTransaction`](/docs/ko/api-reference/rpc/http/gettransaction) 호출을 일괄 처리하여 기본 전체 거래를 가져오는 것입니다 (참고: [전송 행에 대한 전체 거래 가져오기](#전송-행에-대한-전체-거래-가져오기)).
## 정확성과 대조
`getTransfersByAddress`는 회계 장부, 결제 추적, 포트폴리오 활동 및 잔액 대조를 위한 신뢰할 수 있는 전송 기록이 필요한 응용 프로그램을 위해 구축되었습니다. 원시 거래 페이로드를 반환하고 모든 가장자리를 파서에 맡기는 대신, API는 정규화된 전송 객체를 반환합니다.
응답은 Solana 기록을 조정하기 어렵게 만드는 일반적인 전송 사례를 명시적으로 모델링합니다:
* 표준 SPL 토큰과 기본 SOL 전송.
* 평범한 `transfer` 행으로 대표되는 Token-2022 전송을 별도의 수수료 필드로 보유.
* 민트 및 소각, `null` 발신자 또는 수신자로 대표.
* 과도한 라이프사이클 행을 피하기 위해 기본 모드로 SOL 래핑 및 언래핑 행동.
* SetAuthority를 통한 토큰 계정 소유자 변경.
* 토큰-2022 보류 수수료 인출.
* 추측의 순운동으로 축소되지 않고 기본 전송 기록으로 반환된 중간 계정 흐름.
지원되는 보이는 전송 이벤트에 대해 이는 Solana 토큰 파싱 로직을 재구현하지 않고도 균형 이동을 조정할 수 있습니다. [제한 사항](#제한-사항)에 명시된 것처럼 잔액 변경에서만 추론된 숨겨진 SOL 움직임과 같은 알려진 제외 사항이 있습니다.
## 빠른 시작
```javascript 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: "getTransfersByAddress",
params: ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"]
})
});
const data = await response.json();
console.log(data.result.data);
```
## 요청 매개변수
지갑 소유자 주소를 전달하고 연결된 토큰 계정(ATA)은 전달하지 마세요. API는 해당 지갑이 소유한 토큰 계정의 전송 활동을 찾습니다.
쿼리할 전송의 Base58로 인코딩된 소유자 지갑 주소를 전달합니다. 연결된 토큰 계정(ATA)은 전달하지 마세요.
필터링, 페이지 매김, 커밋, 정렬 및 SOL/WSOL 동작을 위한 선택적 구성 객체.
상대방 주소로 필터링. 이 주소로의 전송만 반환.
`address`에 상대적인 전송 방향으로 필터링.
* `in`: `address`로 받은 전송
* `out`: `address`가 보낸 전송
* `any`: 들어오고 나가는 전송
토큰 민트 주소로 필터링. 기본 SOL을 위해 `So11111111111111111111111111111111111111111`를 사용하고 WSOL을 위해 `So11111111111111111111111111111111111111112`를 사용하십시오.
기본 SOL 및 WSOL이 나타나는 방법을 제어합니다.
* `merged`: WSOL은 기본 SOL로 처리됩니다. 랩 및 언랩 라이프사이클 행은 제외되며 WSOL 민트 값은 기본 SOL 민트에 다시 작성됩니다.
* `separate`: WSOL은 별도의 민트로 유지되며, 랩 및 언랩 라이프사이클 행은 포함됩니다.
금액, 블록 시간 및 슬롯에 대한 추가 필터.
반환할 최대 전송 수. 범위: 1에서 100.
페이지 매김을 위한 이전 응답에서의 커서.
데이터 커밋 수준.
* `finalized`
* `confirmed`
요청이 평가될 수 있는 최소 슬롯
결과 정렬.
* `desc`: 최신 순
* `asc`: 오래된 순
## 응답
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"data": [
{
"signature": "5GEX7Q3X5Q8yJGbKYoR7mtzQmG8tpoEwzjPgqVmn3y5xg3yKwqXcDdN5YVcc9V6vA4TuH5iM6FHRVhTxvz4AX2zG",
"slot": 315073428,
"blockTime": 1736159420,
"type": "transfer",
"fromUserAccount": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx",
"toUserAccount": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
"fromTokenAccount": "HcvK3EJ74iM9g11cUgsaPvLSrhCvCwcrWxBNd87LsC1x",
"toTokenAccount": "CBcYniR9G9CN3zGMnwNE4SWbqkYWvCFVreEob9xHnQCY",
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": "2500000",
"decimals": 6,
"uiAmount": "2.5",
"confirmationStatus": "finalized",
"transactionIdx": 35,
"instructionIdx": 1,
"innerInstructionIdx": 0
}
],
"paginationToken": "315073428:35:1:0:splTransfer"
}
}
```
### 응답 필드 세부사항
* `fromUserAccount` 및 `toUserAccount`는 항상 존재합니다. 측면이 존재하지 않으면 값은 `null`입니다.
* `fromTokenAccount` 및 `toTokenAccount`는 해당 행의 토큰-계정이 의미가 있을 때만 포함됩니다. 기본 SOL 전송의 경우 전혀 포함되지 않습니다.
* 민트 전송은 한 쪽입니다: `fromUserAccount`는 `null`이며, 수신자에 대한 인바운드 전송으로만 반환될 수 있습니다.
* 소각 전송은 한 쪽입니다: `toUserAccount`는 `null`이며, 소각 소유자에 대한 아웃바운드 전송으로만 반환될 수 있습니다.
## 필터
수치 범위 쿼리에 대해 비교 필터를 사용하십시오. 모든 비교 필드는 선택 사항이며 결합할 수 있습니다.
```json theme={"system"}
{
"gt": 1000000,
"gte": 1000000,
"lt": 1000000000,
"lte": 1000000000
}
```
| 필터 | 유형 | 설명 |
| ----------- | ------------------ | ------------------- |
| `amount` | `ComparisonFilter` | UI 금액이 아닌 원시 전송 금액. |
| `blockTime` | `ComparisonFilter` | 유닉스 초로의 블록 타임스탬프. |
| `slot` | `ComparisonFilter` | 슬롯 번호. |
## 전송 유형
`type` 필드는 각 행에서 나타내는 전송 동작을 식별합니다.
| 유형 | 설명 | `fromUserAccount` | `toUserAccount` |
| --------------------- | -------------------------------------------------------------------------- | ----------------- | ----------------- |
| `transfer` | 두 지갑 사이의 표준 토큰 또는 SOL 전송. | 발신자 | 수신자 |
| `mint` | 새 토큰이 지갑에 민트됨. | `null` | 수신자 |
| `burn` | 토큰이 영구적으로 파괴됨. | 발신자 | `null` |
| `wrap` | WSOL로 솔을 래핑함. 기본적으로 `solMode: "merged"`에 제외됨. | `null` | 소유자 |
| `unwrap` | WSOL이 기본 SOL로 래핑 해제되거나 토큰 계정을 닫아 임대료가 회수됨. 기본적으로 `solMode: "merged"`에 제외됨. | 소유자 | `null` 또는 라포트 목적지 |
| `changeOwner` | SetAuthority로 토큰 계정 소유권이 변경됨. | 이전 소유자 | 새 소유자 |
| `withdrawWithheldFee` | 민트 또는 계정에서 회수된 토큰-2022 보류 수수료. | `null` | 수수료 수령자 |
### 전송 유형 및 명령어
| 전송 유형 | 고려된 명령어 | 기본 가시성 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | 항상 |
| `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | 항상 |
| `transfer` | `Token-2022::TransferCheckedWithFee`, with `feeAmount` and `feeUiAmount` fields | 항상 |
| `mint` | `Token::MintTo`, `Token::MintToChecked` | 항상 |
| `burn` | `Token::Burn`, `Token::BurnChecked` | 항상 |
| `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` when used for WSOL lifecycle handling | `solMode: "separate"` only |
| `unwrap` | `Token::CloseAccount` on WSOL with balance greater than zero | `solMode: "separate"` only |
| `unwrap` | `Token::CloseAccount` rent recovery for non-WSOL token accounts, or WSOL accounts with zero token balance | `solMode: "separate"` only |
| `changeOwner` | `Token::SetAuthority(AccountOwner)` | 항상 |
| `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | 항상 |
## SOL 및 wSOL 동작
SOL은 실제 사용자 활동에서 종종 함께 나타나는 두 가지 형태로 Solana에 존재합니다:
* **기본 SOL**은 체인의 기본 자산입니다. 지갑이나 계정에 람포트로 직접 존재합니다. 하나의 SOL은 1,000,000,000 람포트입니다.
* \*\*래핑된 SOL (WSOL, 종종 wSOL로 작성됨)\*\*은 SPL 토큰으로의 SOL 표현입니다. WSOL 민트 `So11111111111111111111111111111111111111112`를 사용하며 USDC 또는 다른 SPL 토큰처럼 토큰 계정에 존재합니다.
사용자 및 응용 프로그램은 SOL을 SPL 토큰처럼 동작하도록 할 때 주로 DeFi, 스왑, 토큰-계정 기반 회계 또는 SPL 토큰만 수락하는 프로그램 인터페이스용으로 래핑합니다. 래핑은 일반적으로 기본 SOL로 토큰 계정을 펀딩하고 이를 WSOL에 동기화합니다. 언래핑은 WSOL 토큰 계정을 닫고 SOL을 라무지께 보냅니다.
그 라이프사이클은 단순히 "이 지갑과 다른 사람 사이에 얼마나 많은 SOL이 이동했나요?"라는 질문을 답하려 할 때 혼란스러운 역사가 될 수 있습니다. 래핑이나 언래핑은 동일 소유자가 제어하는 계정 간의 SOL 이동을 종종 나타냅니다. 이 라이프사이클 행이 기본적으로 일반적인 전송으로 표시되면, 앱은 활동을 이중 계수 하거나 내부 장부를 외부 결제로 표시할 수 있습니다.
기본적으로 `getTransfersByAddress`는 `solMode: "merged"`를 사용합니다. 이 모드에서는:
* 기본 SOL 및 WSOL은 `So11111111111111111111111111111111111111111`로 쿼리할 때 하나의 SOL 자산으로 취급됩니다.
* WSOL 전송 행은 SOL로 되돌려지도록 정규화되어 SOL로 된 역사를 더 쉽게 조정할 수 있습니다.
* 래핑 및 언래핑 라이프사이클 행은 일반적으로 동일 소유자가 제어하는 계정 간의 이동을 나타내지 않기 때문에 제외됩니다.
* 다른 소유자 간의 SOL 및 WSOL 전송은 여전히 전송으로 나타납니다.
* `CloseAccount`에서 회수된 임대료는 계정 닫기 라이프사이클 행이 반환될 때 기본 SOL `unwrap` 행으로 나타납니다.
`solMode: "separate"`를 사용하여 WSOL을 별도의 SPL 토큰 민트로 필요로 하거나 래핑 및 언래핑 라이프사이클 기록을 검사하려 할 때 사용하십시오. 이 모드에서는 WSOL이 민트 `So11111111111111111111111111111111111111112`를 유지하고, 랩/언랩 기록이 `type: "wrap"` 또는 `type: "unwrap"`로 반환됩니다.
`solMode: "separate"`에서의 WSOL 계정 폐쇄의 경우, WSOL 민트에 대한 `unwrap` 기록은 SOL로 반환된 남은 WSOL 토큰 잔액을 나타냅니다. 닫힌 토큰 계정에서 환급된 임대료는 별도의 기본 SOL `unwrap` 행으로 반환됩니다.
## Token-2022 전송 수수료
Token-2022 `TransferCheckedWithFee` 명령어는 `type: "transfer"`로 전송 기록 하나로 나타납니다. 대상 금액은 `amount`에 반환되며, 보류 수수료 세부사항은 `feeAmount` 및 `feeUiAmount`에 반환됩니다.
수수료가 있는 전송의 경우, 소스는 `amount + feeAmount`만큼 차감되며, 대상은 `amount`만큼 크레딧이 제공됩니다.
```json theme={"system"}
{
"signature": "WcvF2eFxArpqRJySzDuiP6Xw8BMprWytMpYCxk2ExBt5C1WyxWzDWcCWXW8iKQVYR9AtdQxPE1uu1SMEZvbbhdr",
"slot": 409259683,
"blockTime": 1774635210,
"type": "transfer",
"fromUserAccount": "5aZZ4duJUKiMsJN9vRsoAn4SDX7agvKu7Q3QdFWRfWze",
"toUserAccount": "FESSvM1cVUchc13XQY8e41oeYxMnyqQNYVZwoznfJsTo",
"fromTokenAccount": "3VUYGjYktCzNhDVymNb3Z1iHewtfPFRvdA53qSWuxdXy",
"toTokenAccount": "51cEFBA1virMuPqHXvNGs8FKKTMqeEVKzugv1hqPU2Zc",
"mint": "CKfatsPMUf8SkiURsDXs7eK6GWb4Jsd6UDbs7twMCWxo",
"amount": "48650000",
"decimals": 5,
"uiAmount": "486.5",
"feeAmount": "13450000",
"feeUiAmount": "134.5",
"confirmationStatus": "finalized",
"transactionIdx": 1315,
"instructionIdx": 4,
"innerInstructionIdx": 0
}
```
## 예시
### USDC로 필터링
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
]
}
```
### 발신자로부터의 수신 전송
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx",
"direction": "in"
}
]
}
```
### 금액 및 시간 범위
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"mint": "So11111111111111111111111111111111111111112",
"filters": {
"amount": {
"gte": 1000000000,
"lt": 10000000000
},
"blockTime": {
"gte": 1735718400,
"lt": 1738396800
}
}
}
]
}
```
### 페이지 나누기 요청
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"limit": 50,
"paginationToken": "315069220:308:2:1:splTransfer"
}
]
}
```
### 전송 행에 대한 전체 거래 가져오기
`getTransfersByAddress`는 전체 거래 페이로드가 아닌 파싱된 전송 행을 반환합니다. 각 전송에 대한 전체 거래가 필요할 경우 전송을 먼저 페이지별로 확인하고, `signature`로 중복 제거한 다음 배치된 [`getTransaction`](/docs/ko/api-reference/rpc/http/gettransaction) 호출로 전체 거래를 가져오세요.
`getTransfersByAddress`는 여러 소유자 주소에 대해 배치할 수 없습니다. 한 번에 한 소유자 주소씩 쿼리한 다음 방생된 `getTransaction` 요청을 서명으로 일괄 처리합니다. 단일 거래가 여러 전송 행을 방출할 수 있으므로 거래를 가져오기 전에 반드시 서명을 중복 제거하십시오.
```javascript theme={"system"}
const API_KEY = "YOUR_API_KEY";
const RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${API_KEY}`;
const OWNER_ADDRESS = "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY";
async function rpc(method, params) {
const response = await fetch(RPC_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
jsonrpc: "2.0",
id: "1",
method,
params
})
});
const body = await response.json();
if (body.error) {
throw new Error(body.error.message);
}
return body.result;
}
async function getAllTransfers(address) {
const transfers = [];
let paginationToken;
do {
const result = await rpc("getTransfersByAddress", [
address,
{
limit: 100,
...(paginationToken ? { paginationToken } : {})
}
]);
transfers.push(...result.data);
paginationToken = result.paginationToken;
} while (paginationToken);
return transfers;
}
async function getTransactionsInBatches(signatures, batchSize = 100) {
const transactions = [];
for (let i = 0; i < signatures.length; i += batchSize) {
const batch = signatures.slice(i, i + batchSize).map((signature, index) => ({
jsonrpc: "2.0",
id: `${i + index}`,
method: "getTransaction",
params: [
signature,
{
encoding: "jsonParsed",
maxSupportedTransactionVersion: 0
}
]
}));
const response = await fetch(RPC_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(batch)
});
const results = await response.json();
for (const item of results) {
if (item.error) {
throw new Error(item.error.message);
}
transactions.push(item.result);
}
}
return transactions;
}
const transfers = await getAllTransfers(OWNER_ADDRESS);
const signatures = [...new Set(transfers.map((transfer) => transfer.signature))];
const transactions = await getTransactionsInBatches(signatures);
console.log(`Fetched ${transfers.length} transfer rows`);
console.log(`Fetched ${transactions.length} unique transactions`);
```
## 제한 사항
* 실패한 거래는 V1에 포함되지 않습니다.
* 잔액 변화에서만 추론된 숨겨진 SOL 움직임은 V1에서 지원되지 않습니다.
* `harvestWithheldTokensToMint`는 수집된 금액을 나타내지 않기 때문에 V1에서 지원되지 않습니다.
* 중간 계정 흐름은 줄어들지 않습니다. 거래가 중간 계정을 통해 자금을 이동할 경우, 기본 전송 기록이 반환됩니다.
* 여러 소유자 주소에 대해 배치할 수 없습니다. 한 번에 한 소유자를 쿼리하세요.
## 다음 단계
필터링, 정렬 및 토큰-계정 지원이 있는 전체 거래 기록.
getTransfersByAddress에 대한 전체 요청 및 응답 스키마.
전송 데이터를 백필하고 자체 인덱스로 동기화.
모든 Solana 역사적 데이터 방법 비교.