> ## 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ừ Enhanced Transactions sang Parsed Events
> Chuyển từ API Enhanced Transactions sang Parsed Events — ánh xạ endpoint và tham số, ánh xạ trường phản hồi, mã trước/sau khi chuyển đổi và prompt cho tác nhân AI.
## Tại sao nên di chuyển?
[API Enhanced Transactions](/docs/vi/enhanced-transactions/overview) 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](/docs/vi/parsed-events), giải mã các chỉ thị thông qua danh mục IDL cũng được dùng cho [Parsed Streams](/docs/vi/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 đó:
| | Enhanced Transactions | Parsed Events |
| --------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- |
| Mô hình giải mã | Các loại sự kiện cố định, trình phân tích cú pháp được tuyển chọn | Danh mục IDL, hơn 3.600 chương trình |
| Chi tiết chỉ thị | Chỉ có bản tóm tắt sự kiện | Mọi chỉ thị, đối số và tài khoản đã giải mã, bao gồm cả CPI |
| Chương trình không có trình phân tích cú pháp | Đầu ra `UNKNOWN` chung | Luôn trả về dữ liệu thô và tài khoản cho từng chỉ thị |
| Tín dụng cho mỗi yêu cầu | 100 | 10 |
| Phân trang | Con trỏ chữ ký, cần xử lý lỗi tìm kiếm trong thời gian chạy | `paginationToken` (vẫn hỗ trợ con trỏ chữ ký) |
| Lỗi chương trình đã giải mã | Không | Có (`decodedError`) |
| Payload giao dịch thô | Không | Tùy chọn (`includeRawTransaction`) |
| Trạng thái | Sản phẩm cũ, chế độ bảo trì | Khả dụng rộng rãi, đang được phát triển tích cực |
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:
| Enhanced Transactions | Parsed Events |
| ------------------------------------------ | -------------------------------------------- |
| `POST /v0/transactions` | `POST /v1/parsed-events/transactions` |
| `GET /v0/addresses/{address}/transactions` | `POST /v1/parsed-events/transaction-history` |
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:
```javascript Before (Enhanced Transactions) theme={"system"}
const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;
const response = await fetch(url);
const transactions = await response.json(); // flat array of enriched transactions
for (const tx of transactions) {
console.log(tx.signature, tx.type, tx.description);
}
```
```javascript After (Parsed Events) theme={"system"}
const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
limit: 100,
sortOrder: "desc",
}),
});
const page = await response.json(); // { data: [...], paginationToken }
for (const item of page.data) {
if (item.parserStatus !== "OK") continue;
console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
}
```
## Ánh xạ tham số
### Phân tích giao dịch
`POST /v0/transactions` → `POST /v1/parsed-events/transactions`
| Cũ | Mới |
| -------------------------- | -------------------------------------------------------------------------------- |
| `transactions` (phần thân) | `transactions` — không thay đổi |
| `commitment` | `commitment` — `confirmed` (mặc định) hoặc `finalized`; không hỗ trợ `processed` |
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:
| Tham số truy vấn cũ | Trường phần thân mới |
| ----------------------- | -------------------- |
| `{address}` (đường dẫn) | `address` |
| `limit` | `limit` |
| `before-signature` | `beforeSignature` |
| `after-signature` | `afterSignature` |
| `sort-order` | `sortOrder` |
| `commitment` | `commitment` |
| `gt-time` | `time.gt` |
| `gte-time` | `time.gte` |
| `lt-time` | `time.lt` |
| `lte-time` | `time.lte` |
| `gt-slot` | `slot.gt` |
| `gte-slot` | `slot.gte` |
| `lt-slot` | `slot.lt` |
| `lte-slot` | `slot.lte` |
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](#các-bước-di-chuyển) 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](/docs/vi/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:
| Trường cũ | Trường mới |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | `parsed.summary.description` — `summary` là `null` khi không có bản tóm tắt cấp giao dịch phù hợp |
| `type` (`TRANSFER`, `SWAP`, ...) | `parsed.summary.type` (`transfer`, `swap`, ...) — tập hợp nhỏ hơn; chi tiết theo từng chỉ thị đã chuyển sang `parsed.instructions[]` |
| `source` (`SYSTEM_PROGRAM`, `JUPITER`, ...) | `parsed.summary.parsedData.protocol`, hoặc `instructions[].programName` theo từng chỉ thị |
| `events` (`events.swap`, `events.nft`, ...) | `parsed.summary.parsedData` — payload có cấu trúc, được đặt khóa theo loại tóm tắt |
| `fee` / `feePayer` | `parsed.fee` / `parsed.feePayer` — không thay đổi |
| `signature` | `signature` (ở cấp lớp vỏ) |
| `slot` | `parsed.slot` |
| `timestamp` | `parsed.blockTime` |
| `transactionError` | `parsed.error`, cùng với `parsed.decodedError` chứa tên lỗi riêng của chương trình khi có siêu dữ liệu |
| `nativeTransfers` | `parsed.nativeTransfers` — cùng cấu trúc (`fromUserAccount`, `toUserAccount`, `amount` tính bằng lamport) |
| `tokenTransfers` | `parsed.tokenTransfers` — cùng các trường tài khoản, nhưng `tokenAmount` (số thập phân đã được điều chỉnh tỷ lệ) trở thành `rawTokenAmount` (số nguyên thô) cùng với `decimals` |
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](/docs/vi/parsed-events/parsed-response) để biết tất cả các trường.
## Các bước di chuyển
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](#ánh-xạ-tham-số).
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`.
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](/docs/vi/parsed-streams), dịch vụ lọc phía máy chủ ở cấp chỉ thị.
Thay vòng lặp con trỏ `before-signature` bằng `paginationToken`:
```javascript theme={"system"}
let paginationToken = null;
const results = [];
do {
const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
address: "YOUR_ADDRESS_HERE",
limit: 100,
...(paginationToken && { paginationToken }),
}),
});
const page = await response.json();
results.push(...page.data);
paginationToken = page.paginationToken;
} while (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ã đó.
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.
```markdown theme={"system"}
Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.
## Background
Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md
## Step 1: Find the old call sites
Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses//transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
handlers for the "Failed to find events within the search period" error
## Step 2: Rewrite each call site
Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
("confirmed" default or "finalized") and includeRawTransaction.
Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
limit -> limit (default is now 100, not 10);
before-signature -> beforeSignature (prefer paginationToken, see below);
after-signature -> afterSignature; sort-order -> sortOrder;
commitment -> commitment (default is now "confirmed", not "finalized";
"processed" unsupported);
gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no server-side equivalent: filter returned items client-side
on parsed.summary?.type (lowercase: "swap", "transfer", ...) or on
parsed.instructions[] (programId / instructionName).
Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
parsed.summary?.description; type -> parsed.summary?.type;
source -> parsed.summary?.parsedData?.protocol or
parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
rawTokenAmount (raw integer string/number) plus decimals — divide by
10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
paginationToken is present, passing it back in the next request body.
Delete continuation-signature error handling for the old runtime type
search — it no longer exists.
## Step 3: Constraints and cleanup
- Keep the same Helius API key and host; only paths, methods, bodies, and
response handling change.
- Never hardcode an API key; keep reading it from the existing config or
environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
migration covers only the /v0/transactions and /v0/addresses REST calls.
## Step 4: Verify
- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
(e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
history for an address from both APIs — the old
GET /v0/addresses/{address}/transactions and the new
POST /v1/parsed-events/transaction-history — and prints whether the
signature sets, fees, and native transfer amounts match, listing any
differences. Read the API key from an environment variable and the address
from a CLI argument.
- Tell the user how to run it, for example:
HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs
- Summarize every call site changed and flag any you were unsure about.
```
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](/docs/vi/agents/overview).
## Các bước tiếp theo
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ả.
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.
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ủ.
Lịch sử giao dịch thô có hỗ trợ tài khoản token và bộ lọc phía máy chủ.