> ## 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.

# Transaction History

> 어떤 Solana 주소에 대한 사람이 읽을 수 있는 거래 내역을 필터링, 시간 및 슬롯 범위, 페이지 매김 기능과 함께 가져옵니다.

<Warning>
  Enhanced Transactions API는 유지 모드의 레거시 제품입니다. 여전히 작동하며 이 페이지들은 사용 가능하지만 새로운 파서 유형 또는 기능 작업을 받지는 않습니다. 후속 제품은 [Parsed Events](/docs/ko/parsed-events)로 IDL 카탈로그를 통해 명령어를 디코딩하며 클로즈드 베타 상태입니다. 거래 내역 및 백필을 위해 [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)를 사용할 수 있으며, 사람이 읽을 수 있는 지갑 데이터를 위해 [Wallet API](/docs/ko/wallet-api/overview)를 사용할 수 있습니다.
</Warning>

## 개요

Transaction History 엔드포인트는 어떤 Solana 주소에 대한 사람이 읽을 수 있는 거래 내역을 반환합니다. 원시 명령어 데이터 및 계정 목록을 다루는 대신 다음과 같은 구조화된 정보를 제공합니다:

* 거래에서 발생한 내용(전송, 스왑, NFT 활동).
* 관련된 계정.
* 전송된 SOL 또는 토큰의 양.
* 관련 메타데이터(토큰 민트 주소, 토큰 이름, 토큰 심볼 등).

`GET` 요청을 `/v0/addresses/{address}/transactions`로 보내십시오. 이 엔드포인트는 [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress) RPC 메소드에 의해 지원됩니다.

## 사용할 때

* 사용자에게 주소의 거래 내역을 표시할 때(지갑, 포트폴리오 트래커, 탐색기).
* 자체 디코더를 작성하지 않고 사전 파싱된 사람이 읽을 수 있는 내역이 필요할 때.
* 거래 유형, 시간 범위 또는 슬롯 범위로 내역을 필터링해야 할 때.
* 관련 토큰 계정(ATA)을 포함하여 지갑의 전체 토큰 내역이 필요할 때 — 아래를 참조하십시오.

새 빌드에서는 서버 측 필터링 및 토큰 계정 조회가 가능한 현대적인 [`getTransactionsForAddress`](/docs/ko/rpc/gettransactionsforaddress)가 Helius 네이티브 경로입니다.

## 빠른 시작

<Steps>
  <Step title="API 키 받기">
    [dashboard.helius.dev](https://dashboard.helius.dev)에 가입하고 API 키를 복사하세요.
  </Step>

  <Step title="주소 거래 엔드포인트 가져오기">
    어떤 Solana 주소의 거래 내역을 검색하세요.

    <Tabs>
      <Tab title="JavaScript">
        ```javascript theme={"system"}
        const fetchWalletTransactions = async () => {
          const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Replace with target wallet
          const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY`;

          const response = await fetch(url);
          const transactions = await response.json();
          console.log("Wallet transactions:", transactions);
        };

        fetchWalletTransactions();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        import requests

        def fetch_wallet_transactions():
            wallet_address = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"  # Replace with target wallet
            url = f"https://mainnet.helius-rpc.com/v0/addresses/{wallet_address}/transactions?api-key=YOUR_API_KEY"

            response = requests.get(url)
            transactions = response.json()
            print("Wallet transactions:", transactions)

        fetch_wallet_transactions()
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="필터링 및 페이지 매김">
    아래의 `type`, 시간 및 슬롯 필터로 결과를 좁히고 서명 커서를 통해 높은 볼륨의 주소를 페이지 매김하세요.
  </Step>
</Steps>

## 네트워크 지원

| 네트워크    | 지원되는가 | 보존 기간 |
| ------- | ----- | ----- |
| Mainnet | 예     | 무제한   |
| Devnet  | 예     | 2주    |
| Testnet | 아니오   | N/A   |

## 요청 파라미터

| 파라미터               | 설명                                            | 기본값         | 예                                |
| ------------------ | --------------------------------------------- | ----------- | -------------------------------- |
| `limit`            | 반환할 거래 수 (1-100)                              | 10          | `&limit=25`                      |
| `before-signature` | 이 서명 이전의 거래를 가져옵니다 (`sort-order=desc`와 함께 사용) | -           | `&before-signature=sig123...`    |
| `after-signature`  | 이 서명 이후의 거래를 가져옵니다 (`sort-order=asc`와 함께 사용)  | -           | `&after-signature=sig456...`     |
| `type`             | 거래 유형별 필터링                                    | -           | `&type=NFT_SALE`                 |
| `sort-order`       | 결과에 대한 정렬 순서                                  | `desc`      | `&sort-order=asc`                |
| `token-accounts`   | 관련 토큰 계정에 대한 거래 필터링                           | `none`      | `&token-accounts=balanceChanged` |
| `commitment`       | 커밋 수준                                         | `finalized` | `&commitment=confirmed`          |

### 시간 기반 필터링

| 파라미터       | 설명                  | 예                      |
| ---------- | ------------------- | ---------------------- |
| `gt-time`  | 이 Unix 타임스탬프 이후의 거래 | `&gt-time=1656442333`  |
| `gte-time` | 이 Unix 타임스탬프부터의 거래  | `&gte-time=1656442333` |
| `lt-time`  | 이 Unix 타임스탬프 이전의 거래 | `&lt-time=1656442333`  |
| `lte-time` | 이 Unix 타임스탬프까지의 거래  | `&lte-time=1656442333` |

### 슬롯 기반 필터링

| 파라미터       | 설명          | 예                     |
| ---------- | ----------- | --------------------- |
| `gt-slot`  | 이 슬롯 이후의 거래 | `&gt-slot=148277128`  |
| `gte-slot` | 이 슬롯부터의 거래  | `&gte-slot=148277128` |
| `lt-slot`  | 이 슬롯 이전의 거래 | `&lt-slot=148277128`  |
| `lte-slot` | 이 슬롯까지의 거래  | `&lte-slot=148277128` |

필터링 노트:

* 시간 매개변수는 Unix 타임스탬프(초 단위), 슬롯 매개변수는 Solana 슬롯 번호를 사용합니다.
* 동일한 요청에서 시간 기반 및 슬롯 기반 필터를 결합할 수 없습니다.
* `sort-order=asc`는 오름차순(가장 오래된 첫 번째), `sort-order=desc`는 내림차순(가장 최근 첫 번째)을 사용하십시오.
* 대략적인 기간을 알고 있을 때 시간 또는 슬롯 필터를 사용하여 검색 범위를 줄이고, `limit`와 함께 사용하여 페이지 크기를 제어하세요.

## 관련 토큰 계정

Solana에서 지갑은 직접적으로 토큰을 보유하지 않습니다. 대신 지갑은 토큰 계정을 소유하며, 해당 토큰 계정이 토큰을 보유합니다. 누군가가 USDC를 보내면, 이는 메인 지갑 주소가 아닌 USDC 토큰 계정으로 갑니다.

이 엔드포인트는 관련 토큰 계정(ATA)를 포함한 지갑의 **전체 토큰 내역**을 쿼리할 수 있기 때문에 독특합니다. `getSignaturesForAddress`와 같은 기본 RPC 메서드는 ATA를 포함하지 않습니다.

`token-accounts` 필터는 이 동작을 제어합니다:

* **`none`** (기본값) — 지갑 주소를 직접 참조하는 거래만 반환합니다. 직접적인 지갑 상호작용만 관심이 있을 때 사용하세요.
* **`balanceChanged`** (권장) — 지갑 주소를 참조하거나 지갑이 소유한 토큰 계정의 잔액을 수정하는 거래를 반환합니다. 스팸 및 수수료 수집 또는 위임과 같은 관련 없는 작업을 제거하여 의미 있는 지갑 활동의 깨끗한 보기를 제공합니다.
* **`all`** — 지갑 주소나 지갑이 소유한 모든 토큰 계정을 참조하는 모든 거래를 반환합니다.

<Warning>
  `token-accounts` 필터는 토큰 잔액 메타데이터의 `owner` 필드에 의존하며, 이는 슬롯 111,491,819 (\~2022년 12월) 이전에는 사용할 수 없었습니다. 이 슬롯 이전에 활성화된 토큰 계정과 관련된 거래는 `balanceChanged` 및 `all` 결과에서 누락될 수 있습니다. 전체 코드 예제를 포함한 우회 방법은 [getTransactionsForAddress tutorial](/docs/ko/rpc/gettransactionsforaddress#제한-사항-및-예외-사항)를 참조하세요.
</Warning>

## 필터

### 거래 유형별 필터링

NFT 판매, 토큰 전송 또는 스왑 등의 특정 거래 유형만 가져옵니다:

<Tabs>
  <Tab title="NFT Sales">
    ```javascript theme={"system"}
    const fetchNftSales = async () => {
      const tokenAddress = "GjUG1BATg5V4bdAr1csKys1XK9fmrbntgb1iV7rAkn94"; // NFT mint address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${tokenAddress}/transactions?api-key=YOUR_API_KEY&type=NFT_SALE`;

      const response = await fetch(url);
      const nftSales = await response.json();
      console.log("NFT sale transactions:", nftSales);
    };
    ```
  </Tab>

  <Tab title="Token Transfers">
    ```javascript theme={"system"}
    const fetchTokenTransfers = async () => {
      const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Wallet address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=TRANSFER`;

      const response = await fetch(url);
      const transfers = await response.json();
      console.log("Transfer transactions:", transfers);
    };
    ```
  </Tab>

  <Tab title="Swaps">
    ```javascript theme={"system"}
    const fetchSwapTransactions = async () => {
      const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Wallet address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=SWAP`;

      const response = await fetch(url);
      const swaps = await response.json();
      console.log("Swap transactions:", swaps);
    };
    ```
  </Tab>
</Tabs>

지원되는 거래 유형의 전체 목록은 [Transaction History API reference](/docs/ko/api-reference/enhanced-transactions/gettransactionsbyaddress)를 참조하십시오.

### 런타임 유형 필터링

<Note>
  유형 필터링은 런타임에 발생합니다: API는 최소 50개의 일치 항목을 찾을 때까지 거래를 순차적으로 검색합니다. 검색 창 내에서 일치 항목을 찾지 못하면 검색을 계속할 수 있도록 서명과 함께 오류를 반환합니다. 이는 정상적인 동작이며 실패가 아닙니다.
</Note>

현재 검색 창 내에서 일치하는 거래를 찾지 못하면 API는 다음과 같은 오류 응답을 반환합니다:

```json theme={"system"}
{
  "error": "Failed to find events within the search period. To continue search, query the API again with the `before-signature` parameter set to 2UKbsu95YzxGjUGYRg2znozmmVADVgmnhHqzDxq8Xfb3V5bf2NHUkaXGPrUpQnRFVHVKbawdQXtm4xJt9njMDHvg."
}
```

계속하려면 오류 메시지에서 서명을 사용하여 다음 요청에 적절한 매개변수(`before-signature`는 내림차순, `after-signature`는 오름차순)를 사용하세요.

<Accordion title="유형 필터에 대한 계속 루프 (전체 예제)">
  ```javascript theme={"system"}
  const fetchFilteredTransactions = async (sortOrder = 'desc') => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const transactionType = "NFT_SALE";
    let continuationSignature = null;
    let allFilteredTransactions = [];
    let maxRetries = 10; // Prevent infinite loops
    let retryCount = 0;

    // Determine which parameter to use based on sort order
    const continuationParam = sortOrder === 'asc' ? 'after-signature' : 'before-signature';

    while (retryCount < maxRetries) {
      // Build URL with optional continuation parameter
      let url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=${transactionType}&sort-order=${sortOrder}`;

      if (continuationSignature) {
        url += `&${continuationParam}=${continuationSignature}`;
      }

      try {
        const response = await fetch(url);
        const data = await response.json();

        // Check if we received an error about search period
        if (data.error && data.error.includes("Failed to find events within the search period")) {
          // Extract the signature from the error message
          const signatureMatch = data.error.match(/parameter set to ([A-Za-z0-9]+)/);

          if (signatureMatch && signatureMatch[1]) {
            console.log(`No results in this period. Continuing search from: ${signatureMatch[1]}`);
            continuationSignature = signatureMatch[1];
            retryCount++;
            continue; // Continue searching with new signature
          } else {
            console.log("No more transactions to search");
            break;
          }
        }

        // Check if we received transactions
        if (Array.isArray(data) && data.length > 0) {
          console.log(`Found ${data.length} ${transactionType} transactions`);
          allFilteredTransactions = [...allFilteredTransactions, ...data];

          // Set continuation signature for next page
          continuationSignature = data[data.length - 1].signature;
          retryCount = 0; // Reset retry count since we found results
        } else {
          console.log("No more transactions found");
          break;
        }

      } catch (error) {
        console.error("Error fetching transactions:", error);
        break;
      }
    }

    console.log(`Total ${transactionType} transactions found: ${allFilteredTransactions.length}`);
    return allFilteredTransactions;
  };

  // Usage examples:
  // Descending order (newest first) - uses 'before-signature' parameter
  fetchFilteredTransactions('desc');

  // Ascending order (oldest first) - uses 'after-signature' parameter
  fetchFilteredTransactions('asc');
  ```

  주요 사항:

  * 유형 필터를 사용할 때 API는 한 번에 최대 50개의 거래를 검색합니다.
  * 일치 항목이 없으면 오류 메시지의 서명을 사용하여 검색을 계속하세요.
  * 내림차순으로 검색할 때는(`before-signature` 기본값, 가장 최근 것이 첫 번째) 사용합니다.
  * 오름차순으로 검색할 때는(`after-signature`, 가장 오래된 것이 첫 번째 — 순차적 검색에 필요) 사용합니다.
  * 무한 루프를 방지하기 위해 최대 재시도 제한을 구현하세요.
</Accordion>

## 예시

다음 시나리오는 시간 및 슬롯 범위, 정렬 순서, ATA 및 결합 필터를 다룹니다.

<Accordion title="시간 범위별 필터">
  특정 시간 창 내의 거래 가져오기:

  <Tabs>
    <Tab title="지난 24시간">
      ```javascript theme={"system"}
      const fetchRecentTransactions = async () => {
        const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
        const now = Math.floor(Date.now() / 1000);
        const oneDayAgo = now - (24 * 60 * 60);

        const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${oneDayAgo}&lte-time=${now}`;

        const response = await fetch(url);
        const transactions = await response.json();
        console.log("Transactions from last 24 hours:", transactions);
      };
      ```
    </Tab>

    <Tab title="특정 날짜 범위">
      ```javascript theme={"system"}
      const fetchTransactionsByDateRange = async () => {
        const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

        // January 1, 2024 to January 31, 2024
        const startTime = Math.floor(new Date('2024-01-01').getTime() / 1000);
        const endTime = Math.floor(new Date('2024-01-31').getTime() / 1000);

        const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${startTime}&lte-time=${endTime}`;

        const response = await fetch(url);
        const transactions = await response.json();
        console.log("Transactions in January 2024:", transactions);
      };
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="슬롯 범위별 필터">
  특정 슬롯 범위 내의 거래 가져오기:

  ```javascript theme={"system"}
  const fetchTransactionsBySlotRange = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const startSlot = 148000000;
    const endSlot = 148100000;

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-slot=${startSlot}&lte-slot=${endSlot}`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log(`Transactions between slots ${startSlot} and ${endSlot}:`, transactions);
  };
  ```
</Accordion>

<Accordion title="정렬 순서 변경">
  오름차순으로 거래 가져오기(가장 오래된 것부터):

  ```javascript theme={"system"}
  const fetchOldestTransactions = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&sort-order=asc&limit=10`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("10 oldest transactions:", transactions);
  };
  ```
</Accordion>

<Accordion title="관련 토큰 계정에 대한 전송 포함">
  연관된 토큰 주소(ATA)를 포함한 지갑의 전체 기록을 쿼리합니다:

  ```javascript theme={"system"}
  const fetchTransactionsWithATA = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&token-accounts=balanceChanged&sort-order=desc&limit=50`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("Most recent transactions (including ATA transfers)", transactions);
  };
  ```
</Accordion>

<Accordion title="여러 필터 결합">
  거래 유형 필터링을 시간 범위 및 사용자 지정 정렬 순서와 결합하십시오:

  ```javascript theme={"system"}
  const fetchFilteredTransactionsAdvanced = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

    // Get NFT sales from the last 7 days, oldest first
    const now = Math.floor(Date.now() / 1000);
    const sevenDaysAgo = now - (7 * 24 * 60 * 60);

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=NFT_SALE&gte-time=${sevenDaysAgo}&sort-order=asc&limit=50`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("NFT sales from last 7 days (oldest first):", transactions);
  };
  ```
</Accordion>

## 페이지 매김

고용량 주소의 경우 각 배치에서 마지막 서명을 커서로 사용하여 결과를 페이지 매김하십시오:

```javascript theme={"system"}
const fetchAllTransactions = async () => {
  const walletAddress = "2k5AXX4guW9XwRQ1AKCpAuUqgWDpQpwFfpVFh3hnm2Ha"; // Replace with target wallet
  const baseUrl = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY`;
  let url = baseUrl;
  let lastSignature = null;
  let allTransactions = [];

  while (true) {
    if (lastSignature) {
      url = baseUrl + `&before-signature=${lastSignature}`;
    }

    const response = await fetch(url);

    // Check response status
    if (!response.ok) {
      console.error(`API error: ${response.status}`);
      break;
    }

    const transactions = await response.json();

    if (transactions && transactions.length > 0) {
      console.log(`Fetched batch of ${transactions.length} transactions`);
      allTransactions = [...allTransactions, ...transactions];
      lastSignature = transactions[transactions.length - 1].signature;
    } else {
      console.log(`Finished! Total transactions: ${allTransactions.length}`);
      break;
    }
  }

  return allTransactions;
};
```

시간 범위 내에서 페이지를 매길 때는 각 요청에 시간 필터를 유지하고 각 루프에 `before-signature` 커서를 진행하십시오:

```javascript theme={"system"}
const fetchAllTransactionsInTimeRange = async () => {
  const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
  const startTime = Math.floor(new Date('2024-01-01').getTime() / 1000);
  const endTime = Math.floor(new Date('2024-01-31').getTime() / 1000);

  let beforeSignature = null;
  let allTransactions = [];

  while (true) {
    let url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${startTime}&lte-time=${endTime}&limit=100`;

    if (beforeSignature) {
      url += `&before-signature=${beforeSignature}`;
    }

    const response = await fetch(url);
    const transactions = await response.json();

    if (!Array.isArray(transactions) || transactions.length === 0) {
      break;
    }

    allTransactions = [...allTransactions, ...transactions];
    beforeSignature = transactions[transactions.length - 1].signature;

    console.log(`Fetched ${transactions.length} transactions, total: ${allTransactions.length}`);
  }

  console.log(`Total transactions in time range: ${allTransactions.length}`);
  return allTransactions;
};
```

## 다음 단계

<CardGroup cols={2}>
  <Card title="getTransactionsForAddress" icon="clock-rotate-left" href="/docs/ko/rpc/gettransactionsforaddress">
    현대적이고 Helius 네이티브 거래 내역 및 백필의 대안입니다.
  </Card>

  <Card title="Wallet API" icon="wallet" href="/docs/ko/wallet-api/overview">
    잔액, 내역 및 전송에 대한 사람이 읽을 수 있는 지갑 데이터에 대한 REST 엔드포인트입니다.
  </Card>

  <Card title="Parse Transactions" icon="code" href="/docs/ko/enhanced-transactions/parse-transactions">
    하나 이상의 거래 서명을 사람이 읽을 수 있는 데이터로 파싱합니다.
  </Card>

  <Card title="Getting Data overview" icon="database" href="/docs/ko/getting-data">
    Solana 데이터를 쿼리하기 위한 모든 Helius 옵션을 비교합니다.
  </Card>
</CardGroup>