Skip to main content

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 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ó. 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:
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ừ getTransaction

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

1

Confirm you're on a Helius endpoint

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ụ.
2

Replace the two-step fetch with one call

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ố.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.
3

Update the response handling

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

Replace signature-based pagination

Thay vòng lặp con trỏ before bằng 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.
5

Optional: enable complete token history

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:
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 để 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.
6

Verify against the old output

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

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 để 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.
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.

Các bước tiếp theo

getTransactionsForAddress guide

Hướng dẫn đầy đủ về bộ lọc, sắp xếp, phân trang và tài khoản token.

API reference

Lược đồ yêu cầu và phản hồi hoàn chỉnh.

Indexing guide

Dùng getTransactionsForAddress để điền dữ liệu quá khứ và đồng bộ một chỉ mục Solana.

Historical data overview

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