Skip to main content

Tại sao nên di chuyển?

API Enhanced Transactions là một sản phẩm cũ đang ở chế độ bảo trì: sản phẩm vẫn hoạt động nhưng không còn nhận các loại trình phân tích cú pháp mới hoặc được phát triển thêm tính năng. Sản phẩm kế nhiệm là Parsed Events, giải mã các chỉ thị thông qua danh mục IDL cũng được dùng cho Parsed Streams. Điểm khác biệt nằm ở cách giải mã giao dịch. Enhanced Transactions phân loại giao dịch thành một trong danh sách cố định các loại sự kiện (TRANSFER, SWAP, NFT_SALE, …) và trả về bản tóm tắt dựng sẵn cho các loại mà hệ thống nhận biết. Parsed Events giải mã mọi chỉ thị dựa trên IDL riêng của chương trình — hơn 3.600 chương trình — thành các đối số và tài khoản có tên, sau đó xây dựng bản tóm tắt dựa trên dữ liệu đó: Parsed Events được cung cấp rộng rãi trên mọi gói, bao gồm gói Free, với mức 10 tín dụng cho mỗi yêu cầu. Enhanced Transactions vẫn hoạt động ở chế độ bảo trì, vì vậy bạn có thể di chuyển theo tiến độ phù hợp.

Ánh xạ endpoint

Cả hai phương thức Parsed Events đều là yêu cầu POST đến https://mainnet.helius-rpc.com, được xác thực bằng cùng tham số truy vấn api-key mà bạn đang sử dụng: Endpoint lịch sử chuyển tất cả đầu vào từ tham số chuỗi truy vấn sang phần thân JSON. Phần thân yêu cầu sẽ từ chối các trường không xác định, vì vậy lỗi chính tả sẽ tạo lỗi rõ ràng thay vì bị âm thầm bỏ qua.

Trước và sau khi chuyển đổi

Cùng một tác vụ — truy xuất lịch sử đã phân tích cú pháp của một ví — trong cả hai API:

Ánh xạ tham số

Phân tích giao dịch

POST /v0/transactions → POST /v1/parsed-events/transactions Tùy chọn mới không có giá trị tương đương cũ: includeRawTransaction trả về payload giao dịch Solana gốc cùng với kết quả đã phân tích cú pháp.

Lịch sử giao dịch

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Mỗi tham số truy vấn trở thành một trường trong phần thân JSON: Ba giá trị mặc định cũng thay đổi:
  • limit mặc định là 100 thay vì 10.
  • commitment mặc định là confirmed thay vì finalized; không hỗ trợ processed.
  • sortOrder giữ nguyên các giá trị asc/desc, trong đó desc là giá trị mặc định.
Để phân trang, nên dùng paginationToken từ phản hồi trước thay vì beforeSignature — xem phần Đơn giản hóa phân trang bên dưới. Tham số type cũ không có giá trị tương đương trong Parsed Events — không có bộ lọc loại giao dịch phía máy chủ. Hãy lọc phía máy khách theo parsed.summary.type (swap, transfer, add_liquidity, …), hoặc theo chính các chỉ thị đã giải mã, cách này chính xác hơn các loại cố định cũ. Đối với luồng dữ liệu theo thời gian thực dành riêng cho từng loại, Parsed Streams hỗ trợ lọc phía máy chủ ở cấp chỉ thị.

Ánh xạ trường phản hồi

Enhanced Transactions trả về một mảng phẳng gồm các giao dịch đã được bổ sung dữ liệu. Parsed Events bao bọc mỗi kết quả trong một lớp vỏ — { signature, parserStatus, parsed } — còn phản hồi lịch sử bao bọc mảng trong một đối tượng trang có paginationToken. Các trường đã phân tích cú pháp được ánh xạ như sau: Thay đổi lớn nhất là một trường mới không có giá trị tương đương cũ: parsed.instructions[] chứa mọi chỉ thị cấp cao nhất và chỉ thị bên trong theo thứ tự thực thi, trong đó decoded.args và decoded.accounts được đặt tên theo IDL của chương trình. Trong khi Enhanced Transactions cung cấp một bản tóm tắt sự kiện cho mỗi giao dịch, Parsed Events cung cấp cả bản tóm tắt lẫn danh sách đầy đủ các chỉ thị đã giải mã. Xem Phản hồi đã phân tích cú pháp để biết tất cả các trường.

Các bước di chuyển

1

Swap the endpoints

Chuyển các lệnh gọi Parse Transactions sang POST /v1/parsed-events/transactions và các lệnh gọi lịch sử sang POST /v1/parsed-events/transaction-history. Giữ nguyên máy chủ và tham số truy vấn api-key. Yêu cầu lịch sử chuyển từ GET có tham số truy vấn sang POST có phần thân JSON — di chuyển từng tham số theo bảng ánh xạ ở trên.
2

Update the response handling

Mở lớp vỏ mới: kiểm tra parserStatus === "OK", sau đó đọc các trường từ parsed thay vì cấp cao nhất. Đổi tên timestamp thành blockTime, đọc description và type từ summary (có kiểm tra trường hợp null), đồng thời chia rawTokenAmount cho 10^decimals tại nơi mã cũ đọc tokenAmount.
3

Replace type filtering

Tại nơi mã cũ truyền type=..., hãy lọc các mục được trả về ở phía máy khách theo parsed.summary.type hoặc parsed.instructions[] — ví dụ: “các chỉ thị trong đó programId là Jupiter và instructionName là route” thay thế type=SWAP bằng điều kiện mà bạn thực sự có thể xác minh. Nếu bộ lọc loại được dùng để điều khiển luồng dữ liệu theo thời gian thực, hãy chuyển trình tiêu thụ đó sang Parsed Streams, dịch vụ lọc phía máy chủ ở cấp chỉ thị.
4

Simplify pagination

Thay vòng lặp con trỏ before-signature bằng paginationToken:
Vòng lặp kết thúc khi không có paginationToken. Các lỗi tìm kiếm trong thời gian chạy cũ (“Không tìm thấy sự kiện trong khoảng thời gian tìm kiếm”) và logic xử lý chữ ký tiếp tục tương ứng sẽ biến mất hoàn toàn — hãy xóa đoạn mã đó.
5

Verify against the old output

Với một địa chỉ mẫu, hãy truy xuất cùng một trang từ cả hai API rồi so sánh các tập hợp chữ ký, phí và số tiền chuyển. Sau đó triển khai và xóa luồng mã cũ. Enhanced Transactions vẫn hoạt động trong khi bạn di chuyển — không có thời hạn ngừng bắt buộc.

Các khác biệt về hành vi cần xem xét

  • Giá trị commitment mặc định. Lịch sử mặc định là confirmed, trong khi endpoint cũ mặc định là finalized. Truyền commitment: "finalized" một cách rõ ràng nếu pipeline của bạn phụ thuộc vào tính hoàn tất. Không hỗ trợ processed.
  • Lỗi theo từng mục. Một chữ ký không thể phân tích cú pháp sẽ không còn khiến yêu cầu thất bại — chữ ký đó được trả về dưới dạng một mục có parserStatus: "ERROR" và parserError. Hãy xử lý lỗi theo từng mục thay vì theo từng yêu cầu.
  • Phạm vi bản tóm tắt. summary là null đối với các giao dịch không có hành động cấp giao dịch được nhận dạng. API cũ trả về type: "UNKNOWN" trong trường hợp đó; API mới vẫn cung cấp mọi chỉ thị đã giải mã để bạn xử lý.
  • Quyền truy cập và chi phí. Parsed Events có trên mọi gói và có chi phí 10 tín dụng cho mỗi yêu cầu, giảm từ 100 tín dụng của Enhanced Transactions. Việc tính tín dụng bắt đầu vào ngày 24 tháng 9 năm 2026; các dự án đã sử dụng Parsed Events trước ngày đó sẽ không bị tính phí cho đến ngày 1 tháng 10 năm 2026.

Để tác nhân AI thực hiện việc di chuyển

Nếu sử dụng Claude Code, Cursor hoặc tác nhân lập trình khác, hãy dán prompt bên dưới vào phiên làm việc của tác nhân trong kho lưu trữ. Prompt này tìm các vị trí gọi Enhanced Transactions và viết lại chúng.
Prompt 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 sẵn 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

Parsed Events Quickstart

Phân tích giao dịch đầu tiên, truy xuất lịch sử địa chỉ và phân trang qua các kết quả.

Parsed Response

Tài liệu tham khảo về các trường cho giao dịch, giao dịch chuyển và chỉ thị đã phân tích cú pháp.

Parsed Streams

Cùng cơ chế giải mã theo thời gian thực qua WebSocket, với bộ lọc phía máy chủ.

getTransactionsForAddress

Lịch sử giao dịch thô có hỗ trợ tài khoản token và bộ lọc phía máy chủ.