> ## 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.
# Di chuyển từ getSignaturesForAddress + getTransaction sang getTransactionsForAddress
> Thay thế vòng lặp getSignaturesForAddress + getTransaction bằng một lệnh gọi getTransactionsForAddress duy nhất — ánh xạ tham số, mã trước/sau và phân trang.
## Tại sao nên di chuyển?
Cách tiêu chuẩn để truy xuất lịch sử giao dịch của một địa chỉ trên Solana gồm hai bước: gọi `getSignaturesForAddress` để liệt kê các chữ ký, sau đó gọi `getTransaction` một lần cho mỗi chữ ký để truy xuất thông tin chi tiết. Với 1.000 giao dịch, cách này cần 1.001 yêu cầu HTTP.
[`getTransactionsForAddress`](/docs/vi/rpc/gettransactionsforaddress) là một phương thức RPC độc quyền của Helius, gộp cả hai bước thành một lệnh gọi. Phương thức này trả về tối đa 1.000 giao dịch đầy đủ cho mỗi yêu cầu, đồng thời hỗ trợ lọc, sắp xếp hai chiều và tài khoản token mà các phương thức tiêu chuẩn không có.
| | `getSignaturesForAddress` + `getTransaction` | `getTransactionsForAddress` |
| --------------------------------------- | -------------------------------------------- | ------------------------------------- |
| Số yêu cầu cho 1.000 giao dịch | 1.001 | 1 |
| Số credit cho 1.000 giao dịch đầy đủ | \~1.001 (1 credit cho mỗi lệnh gọi) | 100 (10 credit cho mỗi 100 giao dịch) |
| Lịch sử tài khoản token liên kết (ATA) | Không bao gồm | Bao gồm qua `filters.tokenAccounts` |
| Bộ lọc phạm vi thời gian và slot | Không | Có |
| Bộ lọc trạng thái (thành công/thất bại) | Không | Có |
| Thứ tự sắp xếp | Chỉ mới nhất trước | Mới nhất hoặc cũ nhất trước |
| Phân trang | Chữ ký `before`/`until` | `paginationToken` |
Kết quả: số credit ít hơn khoảng 10 lần, số lượt trao đổi khứ hồi ít hơn 1.000 lần và không cần xử lý theo lô phía máy khách, xử lý giới hạn tốc độ hay logic thử lại cho việc phân tán lệnh gọi `getTransaction`.
## Trước và sau
Dưới đây là cùng một tác vụ — truy xuất 1.000 giao dịch gần nhất của một địa chỉ với đầy đủ chi tiết — theo cả hai cách:
```javascript Before (two methods) theme={"system"}
const rpcUrl = 'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY';
// Step 1: Get signatures (1 request)
const sigResponse = await fetch(rpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getSignaturesForAddress',
params: ['YOUR_ADDRESS_HERE', { limit: 1000 }]
})
});
const { result: signatures } = await sigResponse.json();
// Step 2: Get transaction details (1,000 additional requests)
const transactions = await Promise.all(
signatures.map(async (sig) => {
const txResponse = await fetch(rpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransaction',
params: [sig.signature, { maxSupportedTransactionVersion: 1 }]
})
});
const { result } = await txResponse.json();
return result;
})
);
```
```javascript After (one method) theme={"system"}
const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params: [
'YOUR_ADDRESS_HERE',
{
transactionDetails: 'full',
maxSupportedTransactionVersion: 1,
limit: 1000
}
]
})
});
const { result } = await response.json();
const transactions = result.data; // Full transactions, same shape as getTransaction
```
`getTransactionsForAddress` không thuộc RPC Solana tiêu chuẩn, vì vậy `@solana/web3.js` không có hàm trợ giúp `Connection` dành cho phương thức này. Hãy gọi bằng một yêu cầu JSON-RPC thô như minh họa ở trên — phương thức hoạt động trên cùng endpoint Helius với phần lưu lượng RPC còn lại của bạn.
## Ánh xạ tham số
Mọi tùy chọn trong quy trình hai bước cũ đều có giá trị tương đương trực tiếp. Hầu hết tên được giữ nguyên — chỉ có cơ chế phân trang hoạt động khác.
### Từ getSignaturesForAddress
| Tùy chọn cũ | Giá trị tương đương mới |
| ---------------- | ------------------------------------------------------------------------------ |
| `limit` | `limit` — cùng mức tối đa 1.000 |
| `before` | `paginationToken` từ phản hồi trước |
| `until` | `filters.signature.gt` |
| `commitment` | `commitment` — chỉ `confirmed` hoặc `finalized`; `processed` không được hỗ trợ |
| `minContextSlot` | `minContextSlot` — không thay đổi |
### Từ getTransaction
| Tùy chọn cũ | Giá trị tương đương mới |
| -------------------------------- | --------------------------------------------------------- |
| `encoding` | `encoding` — áp dụng khi `transactionDetails` là `"full"` |
| `maxSupportedTransactionVersion` | `maxSupportedTransactionVersion` — không thay đổi |
| `commitment` | `commitment` — cùng quy tắc như trên |
Hai khả năng hoàn toàn không có giá trị tương đương trong cách cũ:
* `filters` — thu hẹp kết quả theo `blockTime`, `slot`, `status`, `tokenTransfer` hoặc `tokenAccounts` ở phía máy chủ thay vì truy xuất mọi thứ rồi lọc trong mã của bạn.
* `sortOrder: "asc"` — kết quả theo trình tự thời gian (cũ nhất trước), điều mà các phương thức tiêu chuẩn không thể trả về nếu không truy xuất toàn bộ lịch sử rồi đảo ngược thứ tự.
## Các bước di chuyển
`getTransactionsForAddress` là phương thức độc quyền của Helius. Phương thức này hoạt động trên `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY` (và devnet) — cùng endpoint mà các lệnh gọi hiện tại của bạn đã sử dụng nếu bạn là khách hàng của Helius. Không cần thay đổi khóa API hoặc gói dịch vụ.
Xóa lệnh gọi `getSignaturesForAddress` và vòng lặp `getTransaction`. Tạo một yêu cầu `getTransactionsForAddress` duy nhất với `transactionDetails: "full"`, đồng thời chuyển các giá trị `encoding`, `maxSupportedTransactionVersion` và `commitment` sang như minh họa trong phần [ánh xạ tham số](#ánh-xạ-tham-số).
Nếu chỉ cần chữ ký (ví dụ: để cung cấp dữ liệu cho một pipeline hiện có), hãy dùng `transactionDetails: "signatures"` thay thế — chi phí cố định là 10 credit cho mỗi lệnh gọi.
Cấu trúc bao ngoài của phản hồi thay đổi theo ba cách:
* Kết quả nằm trong `result.data` (một mảng), không nằm trực tiếp trong `result`.
* Mỗi mục ở chế độ đầy đủ là `{ slot, transactionIndex, blockTime, transaction, meta }`. Các đối tượng `transaction` và `meta` có hình dạng giống hệt dữ liệu mà `getTransaction` trả về, vì vậy mã phân tích cú pháp của bạn được giữ nguyên.
* Các mục ở chế độ chữ ký khớp với đầu ra của `getSignaturesForAddress` (`signature`, `slot`, `err`, `memo`, `blockTime`, `confirmationStatus`), cộng thêm trường `transactionIndex` mới.
Có một khác biệt về hành vi cần lưu ý: với cách cũ, một lệnh gọi `getTransaction` có thể trả về `null` cho một chữ ký. Với `getTransactionsForAddress`, mọi mục trong `result.data` đều là một giao dịch hoàn chỉnh — hãy loại bỏ mọi xử lý null dành cho phần thông tin chi tiết bị thiếu.
Thay vòng lặp con trỏ `before` bằng `paginationToken`:
```javascript theme={"system"}
let paginationToken = null;
const allTransactions = [];
do {
const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params: [
'YOUR_ADDRESS_HERE',
{
transactionDetails: 'full',
maxSupportedTransactionVersion: 1,
limit: 1000,
...(paginationToken && { paginationToken })
}
]
})
});
const { result } = await response.json();
allTransactions.push(...result.data);
paginationToken = result.paginationToken;
} while (paginationToken);
```
Vòng lặp kết thúc khi `paginationToken` là `null` — không còn phải so sánh danh sách chữ ký hoặc tự theo dõi chữ ký cuối cùng.
Nếu từng dùng `until` để dừng tại một chữ ký đã biết, hãy thay bằng `filters.signature: { gt: "KNOWN_SIGNATURE" }`. Nếu từng dùng nó để dừng tại một thời điểm, `filters.blockTime` hoặc `filters.slot` thường phù hợp hơn.
Cách cũ hoàn toàn bỏ sót hoạt động của tài khoản token liên kết (ATA), trừ khi bạn cũng gọi `getTokenAccountsByOwner` và truy xuất chữ ký cho mọi tài khoản token. Để bao gồm hoạt động này, hãy thêm một bộ lọc:
```json theme={"system"}
{
"filters": {
"tokenAccounts": "balanceChanged"
}
}
```
`balanceChanged` trả về các giao dịch tham chiếu đến ví hoặc thay đổi số dư của bất kỳ tài khoản token nào thuộc sở hữu của ví, đồng thời lọc bỏ thư rác. Xem [tài khoản token liên kết](/docs/vi/rpc/gettransactionsforaddress#tài-khoản-token-liên-kết) để biết các tùy chọn `none`/`balanceChanged`/`all` và lưu ý dành cho dữ liệu trước năm 2022.
Với một địa chỉ mẫu, hãy truy xuất lịch sử bằng cả hai cách và so sánh các tập hợp chữ ký. Khi không đặt `filters.tokenAccounts` (mặc định là `none`), `getTransactionsForAddress` trả về cùng các giao dịch như `getSignaturesForAddress` trong cùng một phạm vi. Sau đó, hãy triển khai và xóa đường dẫn mã cũ.
## Những khác biệt về hành vi cần xem xét
Hầu hết quá trình di chuyển chỉ cần thay thế trực tiếp, nhưng hãy kiểm tra những điểm sau trước khi phát hành:
* **Mức cam kết.** `processed` không được hỗ trợ; hãy dùng `confirmed` hoặc `finalized`. Nếu mã cũ thăm dò lịch sử gần đây ở mức `processed`, hãy chuyển sang `confirmed`.
* **Tính phí sử dụng.** Phản hồi giao dịch đầy đủ tốn 10 credit cho mỗi 100 giao dịch được trả về (tối thiểu 10 credit); phản hồi chỉ có chữ ký tốn cố định 10 credit. Cách cũ tốn 1 credit cho mỗi lệnh gọi — rẻ hơn trên mỗi yêu cầu nhưng đắt hơn nhiều trên mỗi giao dịch được truy xuất. Phản hồi thất bại không mất phí. Xem [tính phí sử dụng](/docs/vi/rpc/gettransactionsforaddress#tính-mức-sử-dụng).
* **Hỗ trợ mạng.** Mainnet lưu giữ dữ liệu không giới hạn. Devnet được hỗ trợ với thời gian lưu giữ 2 tuần. Testnet không được hỗ trợ.
* **Địa chỉ dành riêng.** Một tập hợp nhỏ các địa chỉ hệ thống (Vote Program, System Program, sysvars) được định tuyến đến các đường dẫn lưu trữ dự phòng hoặc trả về kết quả trống. Nếu lập chỉ mục các địa chỉ này, hãy xem lại [giới hạn và trường hợp biên](/docs/vi/rpc/gettransactionsforaddress#hạn-chế-và-trường-hợp-biên).
* **Nhiều địa chỉ.** Giống như quy trình cũ, một yêu cầu xử lý một địa chỉ. Hãy truy vấn các địa chỉ song song rồi hợp nhất; xem [nhiều địa chỉ](/docs/vi/rpc/gettransactionsforaddress#nhiều-địa-chỉ).
## Câu hỏi thường gặp
### getTransactionsForAddress có phải là phương thức RPC Solana tiêu chuẩn không?
Không. Đây là phương thức độc quyền của Helius, có trên các endpoint RPC của Helius. RPC Solana tiêu chuẩn và các nhà cung cấp khác chỉ cung cấp `getSignaturesForAddress` và `getTransaction`. Các lệnh gọi RPC khác của bạn không bị ảnh hưởng — phương thức này nằm trên cùng endpoint bên cạnh toàn bộ giao diện RPC tiêu chuẩn.
### Tôi có còn cần getTransaction sau khi di chuyển không?
Chỉ cần cho các lần tra cứu đơn lẻ khi bạn đã có chữ ký nhưng không có ngữ cảnh địa chỉ, chẳng hạn như xác minh một giao dịch cụ thể do người dùng dán vào. Với mọi loại lịch sử dựa trên địa chỉ — điền dữ liệu quá khứ, lập chỉ mục, nguồn cấp hoạt động ví — `getTransactionsForAddress` thay thế cả hai phương thức.
### Phương thức này có hoạt động với @solana/web3.js không?
Phương thức này không có trong lớp `Connection`, nhưng hoạt động với bất kỳ máy khách HTTP nào dùng URL RPC Helius của bạn. Hãy dùng `fetch` (hoặc phương thức tương đương trong ngôn ngữ của bạn) với phần nội dung JSON-RPC tiêu chuẩn, như minh họa trong các ví dụ ở trên. Bạn vẫn có thể tiếp tục dùng `Connection` cho mọi tác vụ khác.
### Phương thức này có trả về cùng các giao dịch như getSignaturesForAddress không?
Có. Với cài đặt mặc định (`filters.tokenAccounts: "none"`), phương thức trả về các giao dịch tham chiếu đến địa chỉ được truy vấn — cùng một tập hợp như `getSignaturesForAddress`. Đặt `tokenAccounts` thành `balanceChanged` hoặc `all` sẽ trả về nhiều hơn: phương thức bổ sung hoạt động từ các tài khoản token liên kết của ví mà phương thức tiêu chuẩn không thể thấy.
### Chi phí so với cách cũ là bao nhiêu?
Truy xuất 1.000 giao dịch đầy đủ tốn 100 credit với `getTransactionsForAddress`, so với khoảng 1.001 credit (và 1.001 yêu cầu) khi dùng `getSignaturesForAddress` + `getTransaction`. Phản hồi chỉ có chữ ký tốn cố định 10 credit cho mỗi lệnh gọi. Xem [credit Helius](/docs/vi/billing/credits) để biết toàn bộ mức giá.
## Để một tác nhân AI thực hiện việc di chuyển
Nếu dùng Claude Code, Cursor hoặc một tác nhân lập trình khác, hãy dán lời nhắc bên dưới vào phiên tác nhân của kho lưu trữ. Tác nhân sẽ tìm cách triển khai cũ trong cơ sở mã của bạn và viết lại.
````markdown theme={"system"}
Migrate this codebase from the two-step Solana transaction history pattern
(getSignaturesForAddress followed by getTransaction) to the single Helius RPC
method getTransactionsForAddress.
## Background
getTransactionsForAddress is a Helius-exclusive JSON-RPC method served on
standard Helius RPC endpoints (https://mainnet.helius-rpc.com/?api-key=...).
It returns up to 1,000 full transactions per call, replacing one
getSignaturesForAddress call plus one getTransaction call per signature.
Docs: https://www.helius.dev/docs/rpc/gettransactionsforaddress.md
## Step 1: Find the old pattern
Search for:
- getSignaturesForAddress calls (via @solana/web3.js Connection, raw JSON-RPC,
or another SDK) whose signatures are then passed to getTransaction /
getParsedTransaction / getTransactions
- Pagination loops using `before` or `until` signature cursors
- getTokenAccountsByOwner calls used only to fetch per-token-account signature
history
Leave standalone getTransaction calls (single-signature lookups with no
address context) unchanged.
## Step 2: Rewrite each call site
Replace the two-step flow with one raw JSON-RPC request (web3.js has no
Connection helper for this method):
```javascript
const response = await fetch(HELIUS_RPC_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTransactionsForAddress',
params: [
address, // base-58 string
{
transactionDetails: 'full', // or 'signatures' if only signatures were used
maxSupportedTransactionVersion: 1, // carry over from the old getTransaction options
encoding: 'json', // carry over ('json', 'jsonParsed', 'base64', 'base58')
limit: 1000, // up to 1,000
// paginationToken: '...', // from the previous response, for page 2+
// sortOrder: 'desc', // 'desc' (default, newest first) or 'asc'
// filters: { ... } // optional, see mapping below
}
]
})
});
const { result } = await response.json();
// result.data -> array of transactions
// result.paginationToken -> string cursor, or null when done
```
Parameter mapping:
- limit -> limit
- before: -> paginationToken (preferred) or filters: { signature: { lt: } }
- until: -> filters: { signature: { gt: } }
- commitment -> commitment ('confirmed' or 'finalized' only; if the old code
used 'processed', use 'confirmed')
- minContextSlot -> minContextSlot
- encoding / maxSupportedTransactionVersion (from getTransaction) -> same names,
top level of the config object
Response shape:
- Full mode: each entry is { slot, transactionIndex, blockTime, transaction, meta }.
transaction and meta are identical in shape to getTransaction results, so
existing parsing code carries over. Entries are never null - remove
null-handling that existed for missing getTransaction results.
- Signatures mode: entries match getSignaturesForAddress output
({ signature, slot, err, memo, blockTime, confirmationStatus }) plus
transactionIndex.
Pagination: loop while result.paginationToken is non-null, passing it back as
paginationToken. Remove manual last-signature tracking.
If the old code fetched signatures for the wallet's token accounts too
(getTokenAccountsByOwner + per-account getSignaturesForAddress), replace all
of it with one call using filters: { tokenAccounts: 'balanceChanged' } and
delete the merge/dedupe logic.
## Step 3: Constraints and cleanup
- The endpoint must be a Helius RPC URL; other providers do not serve this
method. Do not change endpoints for other RPC calls.
- Remove now-unused batching, throttling, and retry helpers that existed only
for the getTransaction fan-out.
- One request covers one address; keep parallel queries for multi-address code.
- Preserve the surrounding code style and error handling conventions.
## Step 4: Verify
- Run the project's type checks and tests.
- Do NOT make any RPC calls yourself. Instead, write a standalone script (e.g.
scripts/verify-gtfa-migration.mjs) that fetches history for one address both
ways - the old getSignaturesForAddress + getTransaction flow and the new
getTransactionsForAddress call with default filters - and prints whether the
signature sets match, listing any differences. Read the RPC URL from an
environment variable and the address from a CLI argument; never hardcode an
API key.
- Tell the user how to run it, for example:
HELIUS_RPC_URL="https://mainnet.helius-rpc.com/?api-key=..." \
node scripts/verify-gtfa-migration.mjs
- Summarize every call site changed and flag any you were unsure about.
````
Lời nhắc này có đầy đủ ngữ cảnh — tác nhân không cần truy cập trang này. Để xem tài liệu dành cho tác nhân, tính năng tìm kiếm MCP và các kỹ năng, hãy xem [Helius dành cho tác nhân AI](/docs/vi/agents/overview).
## Các bước tiếp theo
Hướng dẫn đầy đủ về bộ lọc, sắp xếp, phân trang và tài khoản token.
Lược đồ yêu cầu và phản hồi hoàn chỉnh.
Dùng getTransactionsForAddress để điền dữ liệu quá khứ và đồng bộ một chỉ mục Solana.
So sánh tất cả các phương thức dữ liệu lịch sử của Solana.