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

# Tổng quan và hướng dẫn về getTransactionsForAddress

> Tìm hiểu cách truy vấn lịch sử giao dịch Solana bằng tính năng lọc nâng cao, sắp xếp hai chiều và phân trang hiệu quả với phương thức RPC độc quyền của Helius này.

## Tổng quan

[`getTransactionsForAddress`](/docs/vi/api-reference/rpc/http/gettransactionsforaddress) là phương thức RPC độc quyền của Helius, trả về lịch sử giao dịch của một địa chỉ với khả năng lọc nâng cao, sắp xếp linh hoạt và phân trang hiệu quả. Phương thức này không thuộc RPC Solana tiêu chuẩn.

Không giống `getSignaturesForAddress` chỉ trả về chữ ký và bỏ qua các tài khoản token liên kết, `getTransactionsForAddress` có thể trả về toàn bộ dữ liệu giao dịch, bao gồm hoạt động của tài khoản token liên kết (ATA) của ví, chỉ trong một lệnh gọi. Vì vậy, đây là cách nhanh nhất để lấy toàn bộ lịch sử địa chỉ phục vụ việc nạp dữ liệu quá khứ, lập chỉ mục và phân tích.

Phương thức này trả về tối đa 1.000 giao dịch đầy đủ cho mỗi lệnh gọi.

<CardGroup cols={2}>
  <Card title="Flexible sorting" icon="arrows-up-down">
    Sắp xếp theo trình tự thời gian (cũ nhất trước) hoặc đảo ngược (mới nhất trước).
  </Card>

  <Card title="Advanced filtering" icon="filter">
    Lọc theo khoảng thời gian, slot, chữ ký, trạng thái và giao dịch chuyển token.
  </Card>

  <Card title="Full transaction data" icon="database">
    Lấy đầy đủ chi tiết giao dịch trong một lệnh gọi mà không cần gọi getTransaction tiếp theo.
  </Card>

  <Card title="Token accounts" icon="layer-group">
    Bao gồm giao dịch của các tài khoản token liên kết với một địa chỉ.
  </Card>
</CardGroup>

## Khi nào nên sử dụng

Sử dụng `getTransactionsForAddress` khi cần:

* Toàn bộ lịch sử token của ví, bao gồm các tài khoản token liên kết
* Nạp dữ liệu quá khứ nhanh chóng bằng một lệnh gọi cho trình lập chỉ mục hoặc quy trình dữ liệu
* Phân tích và báo cáo giao dịch dựa trên thời gian hoặc slot
* Lọc trạng thái để chỉ giữ lại giao dịch thành công hoặc chỉ giao dịch thất bại
* Phát lại lịch sử theo trình tự thời gian (thứ tự cũ nhất trước)
* Phân tích đợt ra mắt token: các giao dịch đúc đầu tiên và những người nắm giữ ban đầu
* Lịch sử cấp vốn cho ví và phát hiện đối tác giao dịch
* Báo cáo tuân thủ và kiểm toán trong một khoảng thời gian cụ thể

Đối với lịch sử đã phân tích cú pháp chỉ gồm giao dịch chuyển (thanh toán, đối soát số dư), hãy sử dụng [`getTransfersByAddress`](/docs/vi/rpc/gettransfersbyaddress).

### Hỗ trợ mạng

| Mạng    | Được hỗ trợ | Thời gian lưu giữ |
| ------- | ----------- | ----------------- |
| Mainnet | Có          | Không giới hạn    |
| Devnet  | Có          | 2 tuần            |
| Testnet | Không       | Không áp dụng     |

## Bắt đầu nhanh

<Steps>
  <Step title="Get your API key">
    Lấy khóa API từ [Bảng điều khiển Helius](https://dashboard.helius.dev/api-keys).
  </Step>

  <Step title="Query with advanced features">
    Lấy tất cả giao dịch thành công của một ví giữa hai ngày, được sắp xếp theo trình tự thời gian:

    ```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);
    ```
  </Step>

  <Step title="Understand the parameters">
    Ví dụ này minh họa các tính năng chính:

    * **transactionDetails**: đặt thành `'full'` để lấy toàn bộ dữ liệu giao dịch trong một lệnh gọi
    * **sortOrder**: sử dụng `'asc'` để sắp xếp theo trình tự thời gian (cũ nhất trước) hoặc `'desc'` để hiển thị mới nhất trước
    * **filters.blockTime**: đặt khoảng thời gian bằng `gte` (lớn hơn hoặc bằng) và `lte` (nhỏ hơn hoặc bằng)
    * **filters.status**: lọc để chỉ lấy giao dịch `'succeeded'` hoặc `'failed'`
    * **filters.tokenAccounts**: bao gồm các thao tác chuyển, đúc và đốt của tài khoản token liên kết
  </Step>
</Steps>

## Tham số yêu cầu

<ParamField body="address" type="string" required>
  Khóa công khai được mã hóa Base-58 của tài khoản cần truy vấn lịch sử giao dịch
</ParamField>

<ParamField body="transactionDetails" type="string" default="signatures">
  Mức độ chi tiết giao dịch cần trả về:

  * `signatures`: Thông tin chữ ký cơ bản (nhanh hơn)
  * `full`: Toàn bộ dữ liệu giao dịch (không cần gọi getTransaction, hỗ trợ giới hạn tối đa 1.000)
</ParamField>

<ParamField body="sortOrder" type="string" default="desc">
  Thứ tự sắp xếp kết quả:

  * `desc`: Mới nhất trước (mặc định)
  * `asc`: Cũ nhất trước (theo trình tự thời gian, phù hợp để phân tích lịch sử)
</ParamField>

<ParamField body="limit" type="number" default="1000">
  Số giao dịch tối đa cần trả về:

  * Tối đa 1000 khi `transactionDetails: "signatures"`
  * Tối đa 1000 khi `transactionDetails: "full"`
</ParamField>

<ParamField body="paginationToken" type="string">
  Token phân trang từ phản hồi trước (định dạng: `"slot:position"`)
</ParamField>

<ParamField body="commitment" type="string" default="finalized">
  Mức cam kết: `finalized` hoặc `confirmed`. Mức cam kết `processed` không được hỗ trợ.
</ParamField>

<ParamField body="filters" type="object">
  Các tùy chọn lọc nâng cao để thu hẹp kết quả.
</ParamField>

<ParamField body="filters.slot" type="object">
  Lọc theo số slot bằng các toán tử so sánh: `gte`, `gt`, `lte`, `lt`

  Ví dụ: `{ "slot": { "gte": 1000, "lte": 2000 } }`
</ParamField>

<ParamField body="filters.blockTime" type="object">
  Lọc theo dấu thời gian Unix bằng các toán tử so sánh: `gte`, `gt`, `lte`, `lt`, `eq`

  Ví dụ: `{ "blockTime": { "gte": 1640995200, "lte": 1641081600 } }`
</ParamField>

<ParamField body="filters.signature" type="object">
  Lọc theo chữ ký giao dịch bằng các toán tử so sánh: `gte`, `gt`, `lte`, `lt`

  Ví dụ: `{ "signature": { "lt": "SIGNATURE_STRING" } }`
</ParamField>

<ParamField body="filters.status" type="string">
  Lọc theo trạng thái thành công/thất bại của giao dịch:

  * `succeeded`: Chỉ giao dịch thành công
  * `failed`: Chỉ giao dịch thất bại
  * `any`: Cả giao dịch thành công và thất bại (mặc định)

  Ví dụ: `{ "status": "succeeded" }`
</ParamField>

<ParamField body="filters.tokenAccounts" type="string" default="none">
  Lọc giao dịch cho các tài khoản token liên quan:

  * `none`: Chỉ trả về giao dịch tham chiếu đến địa chỉ được cung cấp (mặc định)
  * `balanceChanged`: Trả về giao dịch tham chiếu đến địa chỉ được cung cấp hoặc thay đổi số dư của tài khoản token thuộc sở hữu của địa chỉ đó (khuyến nghị)
  * `all`: Trả về giao dịch tham chiếu đến địa chỉ được cung cấp hoặc bất kỳ tài khoản token nào thuộc sở hữu của địa chỉ đó

  Ví dụ: `{ "tokenAccounts": "balanceChanged" }`
</ParamField>

<ParamField body="filters.tokenTransfer" type="object">
  Lọc các giao dịch mà địa chỉ được truy vấn đã tham gia một giao dịch chuyển token khớp với đối tác, hướng, mint hoặc khoảng số lượng thô. Tất cả các trường đều không bắt buộc và được kết hợp theo ngữ nghĩa AND.

  Ví dụ: `{ "tokenTransfer": { "direction": "in", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }`
</ParamField>

<ParamField body="filters.tokenTransfer.with" type="string">
  Địa chỉ đối tác. Khớp với các giao dịch chuyển có phía còn lại là địa chỉ này.
</ParamField>

<ParamField body="filters.tokenTransfer.direction" type="string" default="any">
  Lọc theo hướng chuyển so với địa chỉ được truy vấn:

  * `in`: Giao dịch chuyển mà địa chỉ được truy vấn nhận được
  * `out`: Giao dịch chuyển do địa chỉ được truy vấn gửi đi
  * `any`: Giao dịch chuyển đến và đi
</ParamField>

<ParamField body="filters.tokenTransfer.mint" type="string">
  Mint token dùng để lọc.
</ParamField>

<ParamField body="filters.tokenTransfer.amount" type="object">
  So sánh số lượng bằng số lượng thô trên chuỗi, không phải số lượng trên UI hoặc số lượng đã điều chỉnh theo chữ số thập phân. Hỗ trợ `gt`, `gte`, `lt` và `lte`.
</ParamField>

<ParamField body="encoding" type="string">
  Định dạng mã hóa cho dữ liệu giao dịch (chỉ áp dụng khi `transactionDetails: "full"`). Giống với API `getTransaction`. Các tùy chọn: `json`, `jsonParsed`, `base64`, `base58`
</ParamField>

<ParamField body="maxSupportedTransactionVersion" type="number">
  Đặt phiên bản giao dịch tối đa cần trả về. Nếu bỏ qua, chỉ các giao dịch cũ mới được trả về. Đặt thành `1` để bao gồm giao dịch cũ, v0 và v1.
</ParamField>

<ParamField body="minContextSlot" type="number">
  Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá
</ParamField>

### Tính mức sử dụng

Các phản hồi thành công được tính theo nội dung trả về:

| Loại phản hồi         | Tín dụng                                                                           |
| --------------------- | ---------------------------------------------------------------------------------- |
| Giao dịch đầy đủ      | 10 tín dụng cho mỗi 100 giao dịch được trả về, làm tròn lên; tối thiểu 10 tín dụng |
| Chỉ chữ ký            | Cố định 10 tín dụng, bất kể số lượng                                               |
| Phản hồi API thất bại | Miễn phí                                                                           |

## Phản hồi

Cấu trúc phản hồi phụ thuộc vào `transactionDetails`. Chế độ chữ ký trả về các bản ghi chữ ký gọn nhẹ; chế độ đầy đủ trả về toàn bộ đối tượng giao dịch và siêu dữ liệu.

<Tabs>
  <Tab title="Signatures Response">
    ```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"
      }
    }
    ```
  </Tab>

  <Tab title="Full Transaction Response">
    ```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"
      }
    }
    ```
  </Tab>
</Tabs>

### Trường phản hồi

| Trường               | Kiểu           | Mô tả                                                                                                                                                                                                                                                            |
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signature`          | string         | Chữ ký giao dịch (được mã hóa base-58). Chỉ có trong chế độ chữ ký.                                                                                                                                                                                              |
| `slot`               | number         | Slot chứa khối có giao dịch này.                                                                                                                                                                                                                                 |
| `transactionIndex`   | number         | Chỉ mục bắt đầu từ 0 của giao dịch trong khối. Hữu ích cho việc sắp thứ tự giao dịch và tái tạo khối.                                                                                                                                                            |
| `blockTime`          | number \| null | Thời gian tạo ước tính dưới dạng dấu thời gian Unix (số giây kể từ epoch).                                                                                                                                                                                       |
| `err`                | object \| null | Lỗi nếu giao dịch thất bại, null nếu thành công. Chỉ có trong chế độ chữ ký.                                                                                                                                                                                     |
| `memo`               | string \| null | Ghi chú liên kết với giao dịch. Chỉ có trong chế độ chữ ký.                                                                                                                                                                                                      |
| `confirmationStatus` | string         | Trạng thái xác nhận trên cụm của giao dịch. Chỉ có trong chế độ chữ ký.                                                                                                                                                                                          |
| `transaction`        | object         | Toàn bộ dữ liệu giao dịch. Chỉ có trong chế độ đầy đủ.                                                                                                                                                                                                           |
| `meta`               | object         | Siêu dữ liệu trạng thái giao dịch — có cùng cấu trúc với `getTransaction`, bao gồm `err`, `fee`, `preBalances`/`postBalances`, `preTokenBalances`/`postTokenBalances`, `innerInstructions`, `logMessages` và `computeUnitsConsumed`. Chỉ có trong chế độ đầy đủ. |
| `paginationToken`    | string \| null | Token để truy xuất trang tiếp theo hoặc null nếu không còn kết quả.                                                                                                                                                                                              |

Trường `transactionIndex` chỉ có ở `getTransactionsForAddress`. Các endpoint tương tự khác như `getSignaturesForAddress`, `getTransaction` và `getTransactions` không bao gồm trường này.

Trong chế độ đầy đủ, `meta` là đối tượng siêu dữ liệu giao dịch hoàn chỉnh — có cấu trúc giống hệt nội dung `getTransaction` trả về. Đối tượng này bao gồm `preTokenBalances` và `postTokenBalances`, vì vậy bạn có thể tính trực tiếp thay đổi số dư token (ví dụ: để phát hiện giao dịch hoán đổi) từ phản hồi mà không cần lệnh gọi tiếp theo.

## Bộ lọc

Bạn có thể sử dụng các toán tử so sánh cho `slot`, `blockTime` và `signature`, cùng các bộ lọc đặc biệt `status`, `tokenAccounts` và `tokenTransfer`. Việc kết hợp nhiều bộ lọc sẽ thu hẹp kết quả xuống phần giao nhau của chúng.

### Toán tử so sánh

Các toán tử này hoạt động như truy vấn cơ sở dữ liệu, giúp bạn kiểm soát chính xác phạm vi dữ liệu.

| Toán tử | Tên đầy đủ        | Mô tả                                                | Ví dụ                           |
| ------- | ----------------- | ---------------------------------------------------- | ------------------------------- |
| `gte`   | Lớn hơn hoặc bằng | Bao gồm các giá trị ≥ giá trị được chỉ định          | `slot: { gte: 100 }`            |
| `gt`    | Lớn hơn           | Bao gồm các giá trị > giá trị được chỉ định          | `blockTime: { gt: 1641081600 }` |
| `lte`   | Nhỏ hơn hoặc bằng | Bao gồm các giá trị ≤ giá trị được chỉ định          | `slot: { lte: 2000 }`           |
| `lt`    | Nhỏ hơn           | Bao gồm các giá trị \< giá trị được chỉ định         | `blockTime: { lt: 1641168000 }` |
| `eq`    | Bằng              | Bao gồm các giá trị bằng chính xác (chỉ `blockTime`) | `blockTime: { eq: 1641081600 }` |

### Bộ lọc enum

| Bộ lọc          | Mô tả                                             | Giá trị                             |
| --------------- | ------------------------------------------------- | ----------------------------------- |
| `status`        | Lọc giao dịch theo trạng thái thành công/thất bại | `succeeded`, `failed` hoặc `any`    |
| `tokenAccounts` | Lọc giao dịch cho các tài khoản token liên quan   | `none`, `balanceChanged` hoặc `all` |

Ví dụ về bộ lọc kết hợp:

```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"
}
```

### Tài khoản token liên kết

Trên Solana, ví không trực tiếp giữ token. Thay vào đó, ví sở hữu các tài khoản token và những tài khoản này giữ token. Khi ai đó gửi USDC cho bạn, token sẽ được chuyển vào tài khoản token USDC của bạn chứ không phải địa chỉ ví chính.

Phương thức này đặc biệt vì có thể truy vấn **toàn bộ lịch sử token**, bao gồm các tài khoản token liên kết (ATA) của ví. Các phương thức RPC gốc như `getSignaturesForAddress` không bao gồm ATA.

Bộ lọc `tokenAccounts` kiểm soát hành vi này:

* **`none`** (mặc định): Chỉ trả về các giao dịch tham chiếu trực tiếp đến địa chỉ ví. Sử dụng tùy chọn này khi bạn chỉ quan tâm đến các tương tác trực tiếp với ví.
* **`balanceChanged`** (khuyến nghị): Trả về các giao dịch tham chiếu đến địa chỉ ví hoặc thay đổi số dư của tài khoản token thuộc sở hữu của ví. Tùy chọn này loại bỏ thư rác và các thao tác không liên quan như thu phí hoặc ủy quyền, giúp bạn có cái nhìn rõ ràng về hoạt động có ý nghĩa của ví.
* **`all`**: Trả về tất cả giao dịch tham chiếu đến địa chỉ ví hoặc bất kỳ tài khoản token nào thuộc sở hữu của ví.

Bộ lọc `tokenAccounts` không hỗ trợ các giao dịch trước tháng 12 năm 2022. Bộ lọc này phụ thuộc vào siêu dữ liệu chuyển token được đưa vào Solana tại slot 111,491,819. Để xử lý hoạt động trước đó, hãy xem [giải pháp thay thế cho tài khoản token lịch sử](#hạn-chế-và-trường-hợp-biên).

### Bộ lọc chuyển token

Bộ lọc `tokenTransfer` thu hẹp kết quả xuống các giao dịch mà địa chỉ được truy vấn đã tham gia một giao dịch chuyển token khớp với tiêu chí cụ thể: một đối tác, mint, hướng hoặc khoảng số lượng nhất định.

Sử dụng bộ lọc này để trả lời các câu hỏi như:

* Ví này nhận USDC từ một đối tác cụ thể vào thời điểm nào?
* Hiển thị mọi giao dịch chuyển đi trên 1.000 token.
* Ví này từng tương tác với mint cụ thể này vào thời điểm nào?

Bộ lọc là một trường không bắt buộc bên trong đối tượng `filters` của cấu hình yêu cầu:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress",
  "params": [
    "<address>",
    {
      "filters": {
        "tokenTransfer": {}
      }
    }
  ]
}
```

Tất cả các trường trong `tokenTransfer` đều không bắt buộc. Việc kết hợp nhiều trường được xử lý theo phép AND.

| Trường      | Kiểu                         | Mặc định | Mô tả                                                                                                                             |
| ----------- | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `with`      | string (pubkey)              | -        | Địa chỉ đối tác. Khớp với các giao dịch chuyển có phía còn lại là địa chỉ này.                                                    |
| `direction` | `"in"` \| `"out"` \| `"any"` | `"any"`  | Địa chỉ được truy vấn đã nhận, gửi hay thuộc một trong hai trường hợp.                                                            |
| `mint`      | string (pubkey)              | -        | Mint token dùng để lọc.                                                                                                           |
| `amount`    | object                       | -        | So sánh số lượng. Sử dụng số lượng thô trên chuỗi, không phải số lượng trên UI hoặc số lượng đã điều chỉnh theo chữ số thập phân. |

Toán tử phạm vi số lượng:

| Toán tử | Ý nghĩa             |
| ------- | ------------------- |
| `gt`    | Lớn hơn nghiêm ngặt |
| `gte`   | Lớn hơn hoặc bằng   |
| `lt`    | Nhỏ hơn nghiêm ngặt |
| `lte`   | Nhỏ hơn hoặc bằng   |

Bạn có thể kết hợp các toán tử số lượng, chẳng hạn như `{ "gte": 1000000, "lte": 5000000 }` cho một khoảng đóng. `tokenTransfer` kết hợp với các bộ lọc cấp cao nhất khác (`slot`, `blockTime`, `status` và `tokenAccounts`); kết quả cuối cùng là phần giao nhau.

## Ví dụ

### Phân tích dựa trên thời gian

Tạo báo cáo giao dịch hằng tháng:

```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
    }
  ]
}
```

Xử lý để phân tích:

```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);
```

### Tạo mint token

Tìm giao dịch tạo mint cho một token cụ thể:

```javascript theme={"system"}
{
  "jsonrpc": "2.0",
  "id": "find-first-mints",
  "method": "getTransactionsForAddress",
  "params": [
    MINT_ADDRESS, // Token mint address
    {
      "encoding": "jsonParsed",
      "maxSupportedTransactionVersion": 1,
      "sortOrder": "asc",  // Chronological order from the beginning
      "limit": 10,
      "transactionDetails": "full"
    }
  ]
}
```

Để tìm thao tác tạo pool thanh khoản, hãy truy vấn địa chỉ pool:

```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
    }
  ]
}
```

Thao tác này tìm chính xác thời điểm mint token hoặc pool thanh khoản được tạo, bao gồm địa chỉ người tạo và các tham số ban đầu.

### Giao dịch cấp vốn

Tìm người đã cấp vốn cho một địa chỉ cụ thể:

```javascript theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress",
  "params": [
    "TARGET_WALLET_ADDRESS",
    {
      "transactionDetails": "full",
      "sortOrder": "asc",  // Oldest first
      "limit": 10
    }
  ]
}
```

Sau đó phân tích dữ liệu giao dịch để tìm các giao dịch chuyển 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]}`);
    }
  });
});
```

Một vài giao dịch đầu tiên thường cho biết nguồn cấp vốn và có thể giúp xác định các địa chỉ liên quan hoặc mô hình cấp vốn.

### Chuyển token

Lọc theo `tokenTransfer` để tách riêng các hoạt động di chuyển token cụ thể.

Luồng USDC vào một địa chỉ:

```json theme={"system"}
{
  "filters": {
    "tokenTransfer": {
      "direction": "in",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  }
}
```

Các giao dịch chuyển đi lớn tới một đối tác cụ thể:

```json theme={"system"}
{
  "filters": {
    "tokenTransfer": {
      "with": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "direction": "out",
      "amount": { "gte": 1000000000 }
    }
  }
}
```

Kết hợp với phạm vi slot và trạng thái:

```json theme={"system"}
{
  "filters": {
    "status": "succeeded",
    "slot": { "gte": 100000000, "lte": 200000000 },
    "tokenTransfer": {
      "direction": "in",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": { "gte": 5000000 }
    }
  }
}
```

## Phân trang

Khi số lượng giao dịch vượt quá giới hạn, hãy sử dụng `paginationToken` từ phản hồi để truy xuất trang tiếp theo. Token là một chuỗi đơn giản có định dạng `"slot:position"`, cho API biết vị trí cần tiếp tục.

Sử dụng token phân trang từ mỗi phản hồi để truy xuất trang tiếp theo:

```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);
```

### Nhiều địa chỉ

Bạn không thể truy vấn nhiều địa chỉ trong một yêu cầu. Mỗi truy vấn địa chỉ được tính là một yêu cầu API riêng và được tính mức sử dụng tương ứng. Để truy xuất giao dịch cho nhiều địa chỉ, hãy truy vấn từng địa chỉ trong cùng một khoảng thời gian hoặc slot, sau đó hợp nhất và sắp xếp:

```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);
```

Đối với các lượt quét lịch sử lớn hơn, hãy lặp qua các khoảng thời gian hoặc slot (ví dụ: mỗi lần 1000 slot) và lặp lại mẫu này.

## Phương pháp hay nhất

**Hiệu suất.** Sử dụng `transactionDetails: "signatures"` khi không cần toàn bộ dữ liệu giao dịch. Sử dụng kích thước trang hợp lý để cải thiện thời gian phản hồi và lọc theo khoảng thời gian hoặc các slot cụ thể để truy vấn có mục tiêu hơn.

**Lọc.** Bắt đầu với các bộ lọc rộng rồi thu hẹp dần. Sử dụng bộ lọc dựa trên thời gian cho quy trình phân tích và báo cáo, đồng thời kết hợp nhiều bộ lọc để tạo truy vấn chính xác, nhắm đến các loại giao dịch hoặc khoảng thời gian cụ thể.

**Phân trang.** Lưu token phân trang khi cần tiếp tục các truy vấn lớn sau này. Theo dõi độ sâu phân trang để lập kế hoạch hiệu suất và sử dụng thứ tự tăng dần khi cần phát lại các sự kiện lịch sử theo trình tự thời gian.

**Xử lý lỗi.** Xử lý giới hạn tốc độ bằng chiến lược lùi theo cấp số nhân. Xác thực địa chỉ trước khi gửi yêu cầu và lưu kết quả vào bộ nhớ đệm khi phù hợp để giảm mức sử dụng API.

## Hạn chế và trường hợp biên

Một nhóm nhỏ địa chỉ được định tuyến đến kho lưu trữ cũ, bị giới hạn ở cơ chế dự phòng quét slot hoặc trả về kết quả trống. Việc phát hiện tài khoản token trước slot 111,491,819 cũng cần một giải pháp thay thế. Mở rộng các phần bên dưới để xem đầy đủ chi tiết.

<Accordion title="Unsupported and specially-routed addresses">
  **Được định tuyến đến kho lưu trữ cũ.** Yêu cầu cho các địa chỉ này được định tuyến đến hệ thống lưu trữ cũ của chúng tôi.

  | Địa chỉ                                       | Tên                                                                                                             |
  | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
  | `Stake11111111111111111111111111111111111111` | [Chương trình Stake](https://orbmarkets.io/address/Stake11111111111111111111111111111111111111/history)         |
  | `StakeConfig11111111111111111111111111111111` | [Cấu hình Stake](https://orbmarkets.io/address/StakeConfig11111111111111111111111111111111/history)             |
  | `Sysvar1111111111111111111111111111111111111` | [Chủ sở hữu Sysvar](https://orbmarkets.io/address/Sysvar1111111111111111111111111111111111111/history)          |
  | `AddressLookupTab1e1111111111111111111111111` | [Bảng tra cứu địa chỉ](https://orbmarkets.io/address/AddressLookupTab1e1111111111111111111111111/history)       |
  | `BPFLoaderUpgradeab1e11111111111111111111111` | [BPF Loader có thể nâng cấp](https://orbmarkets.io/address/BPFLoaderUpgradeab1e11111111111111111111111/history) |

  **Cơ chế dự phòng quét slot.** Yêu cầu cho các địa chỉ này được chuyển tiếp đến hệ thống lưu trữ mới và có thể được truy vấn bằng cách quét từng slot (tối đa 100 slot). Tuy nhiên, dữ liệu này chưa được lập chỉ mục.

  | Địa chỉ                                       | Tên                                                                                                      |
  | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
  | `11111111111111111111111111111111`            | [Chương trình hệ thống](https://orbmarkets.io/address/11111111111111111111111111111111/history)          |
  | `ComputeBudget111111111111111111111111111111` | [Ngân sách tính toán](https://orbmarkets.io/address/ComputeBudget111111111111111111111111111111/history) |
  | `MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` | [Chương trình Memo](https://orbmarkets.io/address/MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr/history)   |
  | `Vote111111111111111111111111111111111111111` | [Chương trình Vote](https://orbmarkets.io/address/Vote111111111111111111111111111111111111111/history)   |

  **Trả về trống (`is_reserved_address`).** Yêu cầu được chuyển tiếp đến hệ thống lưu trữ mới, tuy nhiên dữ liệu chưa được lập chỉ mục nên truy vấn trả về kết quả trống.

  | Địa chỉ                                        | Tên                                                                                                              |
  | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
  | `BPFLoader1111111111111111111111111111111111`  | [BPF Loader (không còn dùng)](https://orbmarkets.io/address/BPFLoader1111111111111111111111111111111111/history) |
  | `BPFLoader2111111111111111111111111111111111`  | [BPF Loader](https://orbmarkets.io/address/BPFLoader2111111111111111111111111111111111/history)                  |
  | `Config1111111111111111111111111111111111111`  | [Chương trình Config](https://orbmarkets.io/address/Config1111111111111111111111111111111111111/history)         |
  | `Ed25519SigVerify111111111111111111111111111`  | [Chương trình Ed25519](https://orbmarkets.io/address/Ed25519SigVerify111111111111111111111111111/history)        |
  | `Feature111111111111111111111111111111111111`  | [Chương trình Feature](https://orbmarkets.io/address/Feature111111111111111111111111111111111111/history)        |
  | `KeccakSecp256k11111111111111111111111111111`  | [Chương trình Secp256k1](https://orbmarkets.io/address/KeccakSecp256k11111111111111111111111111111/history)      |
  | `LoaderV411111111111111111111111111111111111`  | [Loader V4](https://orbmarkets.io/address/LoaderV411111111111111111111111111111111111/history)                   |
  | `NativeLoader1111111111111111111111111111111`  | [Native Loader](https://orbmarkets.io/address/NativeLoader1111111111111111111111111111111/history)               |
  | `SysvarC1ock11111111111111111111111111111111`  | [Clock Sysvar](https://orbmarkets.io/address/SysvarC1ock11111111111111111111111111111111/history)                |
  | `SysvarEpochSchedu1e111111111111111111111111`  | [Epoch Schedule Sysvar](https://orbmarkets.io/address/SysvarEpochSchedu1e111111111111111111111111/history)       |
  | `SysvarFees111111111111111111111111111111111`  | [Fees Sysvar](https://orbmarkets.io/address/SysvarFees111111111111111111111111111111111/history)                 |
  | `Sysvar1nstructions1111111111111111111111111`  | [Instructions Sysvar](https://orbmarkets.io/address/Sysvar1nstructions1111111111111111111111111/history)         |
  | `SysvarRecentB1ockHashes11111111111111111111`  | [Recent Blockhashes Sysvar](https://orbmarkets.io/address/SysvarRecentB1ockHashes11111111111111111111/history)   |
  | `SysvarRent111111111111111111111111111111111`  | [Rent Sysvar](https://orbmarkets.io/address/SysvarRent111111111111111111111111111111111/history)                 |
  | `SysvarRewards111111111111111111111111111111`  | [Rewards Sysvar](https://orbmarkets.io/address/SysvarRewards111111111111111111111111111111/history)              |
  | `SysvarS1otHashes111111111111111111111111111`  | [Slot Hashes Sysvar](https://orbmarkets.io/address/SysvarS1otHashes111111111111111111111111111/history)          |
  | `SysvarS1otHistory11111111111111111111111111`  | [Slot History Sysvar](https://orbmarkets.io/address/SysvarS1otHistory11111111111111111111111111/history)         |
  | `SysvarStakeHistory1111111111111111111111111`  | [Stake History Sysvar](https://orbmarkets.io/address/SysvarStakeHistory1111111111111111111111111/history)        |
  | `SysvarEpochRewards11111111111111111111111111` | [Epoch Rewards Sysvar](https://orbmarkets.io/address/SysvarEpochRewards11111111111111111111111111/history)       |
  | `SysvarLastRestartS1ot1111111111111111111111`  | [Last Restart Slot Sysvar](https://orbmarkets.io/address/SysvarLastRestartS1ot1111111111111111111111/history)    |
</Accordion>

<Accordion title="Workaround: historical token account discovery (before slot 111,491,819)">
  Đối với các địa chỉ có hoạt động tài khoản token trước slot 111,491,819, bộ lọc `tokenAccounts` không thể xác định quyền sở hữu vì trường `owner` trong siêu dữ liệu số dư token chưa tồn tại. Để nhận kết quả đầy đủ, bạn có thể tự phát hiện các tài khoản token đó bằng cách phân tích cú pháp các lệnh giao dịch ban đầu, sau đó truy vấn song song `getTransactionsForAddress` cho từng tài khoản.

  ```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: 1,
          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);
  }
  ```
</Accordion>

## Phương thức này khác getSignaturesForAddress như thế nào?

Nếu đã quen với phương thức tiêu chuẩn `getSignaturesForAddress`, bạn sẽ thấy `getTransactionsForAddress` gộp quy trình nhiều bước thành một lệnh gọi, đồng thời bổ sung khả năng lọc, sắp xếp và hỗ trợ tài khoản token. Để chuyển đổi mã hiện có theo từng bước, hãy xem [hướng dẫn di chuyển](/docs/vi/rpc/migrate-to-gettransactionsforaddress).

### Lấy giao dịch đầy đủ trong một lệnh gọi

Với `getSignaturesForAddress`, bạn cần hai bước:

```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))
);
```

Với `getTransactionsForAddress`, bạn chỉ cần một lệnh gọi:

```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
      }
    ]
  })
});
```

### Lấy lịch sử token trong một lệnh gọi

Với `getSignaturesForAddress`, trước tiên bạn cần gọi `getTokenAccountsByOwner` rồi truy vấn từng tài khoản token:

```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;
```

Với `getTransactionsForAddress`, bạn chỉ cần đặt `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;
```

### Khả năng bổ sung

<CardGroup cols={2}>
  <Card title="Chronological sorting" icon="arrow-up">
    Sắp xếp giao dịch từ cũ nhất đến mới nhất bằng `sortOrder: 'asc'`.
  </Card>

  <Card title="Time-based filtering" icon="clock">
    Lọc theo khoảng thời gian bằng các bộ lọc `blockTime`.
  </Card>

  <Card title="Status filtering" icon="filter">
    Chỉ lấy giao dịch thành công hoặc thất bại bằng bộ lọc `status`.
  </Card>

  <Card title="Simpler pagination" icon="list">
    Sử dụng `paginationToken` thay cho các chữ ký `before`/`until` khó hiểu.
  </Card>
</CardGroup>

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Indexing guide" icon="layer-group" href="/docs/vi/rpc/how-to-index-solana-data">
    Sử dụng getTransactionsForAddress để nạp dữ liệu quá khứ và đồng bộ chỉ mục Solana.
  </Card>

  <Card title="getTransfersByAddress" icon="arrow-right-arrow-left" href="/docs/vi/rpc/gettransfersbyaddress">
    Lịch sử đã phân tích cú pháp chỉ gồm giao dịch chuyển, dùng cho thanh toán và đối soát.
  </Card>

  <Card title="API reference" icon="code" href="/docs/vi/api-reference/rpc/http/gettransactionsforaddress">
    Lược đồ yêu cầu và phản hồi đầy đủ cho getTransactionsForAddress.
  </Card>

  <Card title="Historical data overview" icon="clock-rotate-left" href="/docs/vi/rpc/historical-data">
    So sánh tất cả phương thức dữ liệu lịch sử của Solana.
  </Card>
</CardGroup>