Skip to main content

Tổng quan

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.

Flexible sorting

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

Advanced filtering

Lọc theo khoảng thời gian, slot, chữ ký, trạng thái và giao dịch chuyển token.

Full transaction data

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.

Token accounts

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

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.

Hỗ trợ mạng

Bắt đầu nhanh

1

Get your API key

Lấy khóa API từ Bảng điều khiển Helius.
2

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:
3

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

Tham số yêu cầu

string
bắt buộc
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
string
mặc định:"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)
string
mặc định:"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ử)
number
mặc định:"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"
string
Token phân trang từ phản hồi trước (định dạng: "slot:position")
string
mặc định:"finalized"
Mức cam kết: finalized hoặc confirmed. Mức cam kết processed không được hỗ trợ.
object
Các tùy chọn lọc nâng cao để thu hẹp kết quả.
object
Lọc theo số slot bằng các toán tử so sánh: gte, gt, lte, ltVí dụ: { "slot": { "gte": 1000, "lte": 2000 } }
object
Lọc theo dấu thời gian Unix bằng các toán tử so sánh: gte, gt, lte, lt, eqVí dụ: { "blockTime": { "gte": 1640995200, "lte": 1641081600 } }
object
Lọc theo chữ ký giao dịch bằng các toán tử so sánh: gte, gt, lte, ltVí dụ: { "signature": { "lt": "SIGNATURE_STRING" } }
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" }
string
mặc định:"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" }
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" } }
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.
string
mặc định:"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
string
Mint token dùng để lọc.
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.
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
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.
number
Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá

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ề:

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.

Trường phản hồi

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.

Bộ lọc enum

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

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

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:
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. Toán tử phạm vi số lượ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:
Xử lý để phân tích:

Tạo mint token

Tìm giao dịch tạo mint cho một token cụ thể:
Để tìm thao tác tạo pool thanh khoản, hãy truy vấn địa chỉ pool:
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ể:
Sau đó phân tích dữ liệu giao dịch để tìm các giao dịch chuyển SOL:
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ỉ:
Các giao dịch chuyển đi lớn tới một đối tác cụ thể:
Kết hợp với phạm vi slot và trạng thái:

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:

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:
Đố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.
Đượ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.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.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.
Đố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.

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.

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

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

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:
Với getTransactionsForAddress, bạn chỉ cần đặt filters.tokenAccounts:

Khả năng bổ sung

Chronological sorting

Sắp xếp giao dịch từ cũ nhất đến mới nhất bằng sortOrder: 'asc'.

Time-based filtering

Lọc theo khoảng thời gian bằng các bộ lọc blockTime.

Status filtering

Chỉ lấy giao dịch thành công hoặc thất bại bằng bộ lọc status.

Simpler pagination

Sử dụng paginationToken thay cho các chữ ký before/until khó hiểu.

Bước tiếp theo

Indexing guide

Sử dụng getTransactionsForAddress để nạp dữ liệu quá khứ và đồng bộ chỉ mục Solana.

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.

API reference

Lược đồ yêu cầu và phản hồi đầy đủ cho getTransactionsForAddress.

Historical data overview

So sánh tất cả phương thức dữ liệu lịch sử của Solana.