Giới thiệu Parsed Events Scan API

Quét theo chỉ thị của chương trình Solana

Yêu cầu sau quét lịch sử chương trình Pump.fun và trả về các giao dịch đã phân tích có chứa chỉ thị buy hoặc sell:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["buy", "sell"]
        }
      ]
    },
    "limit": 100
  }'

Với yêu cầu này, công cụ demo Parsed Events Scan đã quét 261 bản ghi và tìm thấy 100 kết quả khớp. Công cụ trả về 100 sự kiện gần nhất trong 182 ms với tổng chi phí chỉ 11 credit:

Tên chỉ thị có thể sử dụng cách viết từ bất kỳ phiên bản IDL nào của chương trình hoặc dạng snake_case. Parsed Events Scan API kiểm tra cả chỉ thị cấp cao nhất lẫn chỉ thị nội bộ được gọi qua Cross-program Invocations (CPI).

Các chương trình thường có nhiều phiên bản cho cùng một hành động. Ví dụ, IDL của Pump.fun có các chỉ thị buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell và sell_v2. Scan API cho phép bạn liệt kê mọi tên chỉ thị cần so khớp.

Hoạt động mua và bán chiếm phần lớn hoạt động của Pump.fun, nên quá trình so khớp diễn ra khá nhanh. Scan tiết kiệm nhiều hơn khi hoạt động bạn cần rất hiếm. Chẳng hạn, phí nhà sáng tạo chỉ chiếm một phần nhỏ trong các giao dịch của chương trình:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["collect_creator_fee"]
        }
      ]
    },
    "limit": 10
  }'

Khi dùng công cụ demo Parsed Events Scan để tìm mười lần nhận phí gần nhất, có thể thấy công cụ đã quét 3.402 giao dịch trong 182 ms và yêu cầu này tốn 14 credit:

Lệnh gọi getTransactionsForAddress tương đương sẽ tốn 350 credit, cao gấp 25 lần so với endpoint quét.

Nếu một chương trình Solana không có IDL với các chỉ thị được đặt tên thì sao?

Để sử dụng Parsed Events Scan API với các chương trình Solana không có IDL, bạn có thể so khớp bằng tiền tố dữ liệu chỉ thị.

Mỗi discriminator có thể chứa từ một đến tám byte được mã hóa hex. Bạn có thể kết hợp tên và discriminator cho một chương trình; chỉ thị chỉ cần khớp một trong hai. Ví dụ:

{
  "match": {
    "programs": [
      {
        "programId": "<PROGRAM_ADDRESS>",
        "discriminators": ["0x66063d1201daebea"]
      }
    ]
  }
}

Quét nhiều chương trình Solana cùng lúc

Bạn có thể liệt kê tối đa 20 chương trình trong một yêu cầu Parsed Events Scan API và giao dịch sẽ khớp khi gọi bất kỳ chương trình nào trong số đó.

Ví dụ, yêu cầu này quét các giao dịch của một ví để tìm kết quả khớp trên Jupiter, DFlow và Pump.fun chỉ trong một lần quét:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"]
      },
      { "programId": "DF1ow4tspfHX9JwWJsAb9epbkA8hmpSEAtxXy1V27QBH" },
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Quét theo mint token

Scan API cũng có thể tìm các giao dịch đã tương tác với một mint token nhất định bằng cách kiểm tra số dư token trước và sau giao dịch theo địa chỉ mint. Theo mặc định, API chỉ tính các số dư thuộc về địa chỉ được quét.

Khi quét một ví theo token, hãy đặt tokenAccounts thành balanceChanged. Trong nhiều trường hợp, một giao dịch chuyển token đến chỉ tương tác với tài khoản token của ví chứ không phải chính ví đó; vì vậy, lịch sử của ví mặc định sẽ không bao gồm các giao dịch này.

Ví dụ, yêu cầu này tìm hoạt động wSOL của Ansem trong tháng 9 năm 2026:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "<ANSEM_WALLET_ADDRESS>",
    "match": {
      "mints": [{ "mint": "So11111111111111111111111111111111111111112" }]
    },
    "tokenAccounts": "balanceChanged",
    "time": {
      "gte": 1788220800,
      "lte": 1790812800
    }
  }'

Scan API tìm thấy 53 giao dịch khớp sau khi quét tổng cộng 7.555 giao dịch:

Kết hợp chương trình và mint

Nhà phát triển có thể đặt cả programs và mints để thu hẹp kết quả. Khi kết hợp, giao dịch phải đáp ứng cả hai tiêu chí mới được coi là khớp. Tuy nhiên, để thu hẹp hoạt động của một chương trình về một token duy nhất, địa chỉ được quét quan trọng hơn các bộ lọc.

Ví dụ, hãy quét địa chỉ mint của token thay vì chương trình Pump.fun để tìm mọi giao dịch Pump.fun của một token nhất định. Mỗi giao dịch mua hoặc bán đều liệt kê mint dưới dạng một tài khoản nên sẽ khớp theo mặc định:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Lịch sử của mint chỉ chứa hoạt động của token đó, trong khi lịch sử của chương trình chứa giao dịch của mọi token. Vì vậy, quét lịch sử chương trình sẽ lãng phí ngân sách cho các giao dịch không liên quan.

Chọn phạm vi so khớp

Theo mặc định, chỉ thị của chương trình và số dư token của mint chỉ được tính khi có liên quan đến địa chỉ được quét. Một số dư token liên quan đến địa chỉ khi địa chỉ sở hữu tài khoản token hoặc khi địa chỉ là mint của số dư đó. Một chỉ thị liên quan đến địa chỉ khi:

• Một trong các tài khoản của chỉ thị là địa chỉ đó
• Một trong các tài khoản của chỉ thị là tài khoản token do địa chỉ đó sở hữu
• Địa chỉ là một mint và một trong các tài khoản của chỉ thị là tài khoản token của mint đó
• Địa chỉ là chương trình đang được gọi

Đặt "scope": "transaction" trên chương trình hoặc mint để tính nó ở bất kỳ đâu trong giao dịch. Hãy dùng tùy chọn này khi địa chỉ chỉ trả phí, thực thi một giao dịch multisig hoặc không phải là tài khoản của chỉ thị cần so khớp.

Ví dụ, yêu cầu này tìm các giao dịch của một token cũng có dịch chuyển USDC. Trong phạm vi mặc định, số dư USDC phải thuộc về địa chỉ mint nên sẽ không có kết quả nào khớp:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "mints": [
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "scope": "transaction" }
    ]
  },
  "returnShape": "signatures"
}

Các chương trình cũng hỗ trợ cùng phạm vi so khớp. Yêu cầu này tìm các giao dịch hoán đổi Jupiter mà một relayer đã trả phí.

Relayer chỉ ký giao dịch với vai trò bên trả phí, nên không phải là một trong các tài khoản của chỉ thị định tuyến. Vì vậy, không giao dịch nào trong số này khớp theo phạm vi mặc định:

{
  "address": "<RELAYER_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"],
        "scope": "transaction"
      }
    ]
  },
  "returnShape": "signatures"
}

Logic tương tự áp dụng cho một thành viên multisig thực thi đề xuất. Chỉ thị do multisig chạy tác động lên các tài khoản của vault chứ không phải tài khoản của thành viên. Vì vậy, để quét lịch sử của thành viên nhằm tìm các giao dịch này, cần dùng phạm vi transaction.

Theo dõi SOL gốc

SOL gốc không có số dư token, vì vậy quá trình quét so khớp dựa trên lamport.

Truyền mint SOL gốc (So11111111111111111111111111111111111111111), khác với wrapped SOL. Một giao dịch khớp khi số dư SOL của địa chỉ được quét thay đổi, không tính khoản phí địa chỉ đó đã trả:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "mints": [{ "mint": "So11111111111111111111111111111111111111111" }]
  },
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Cách này phát hiện SOL mà chương trình chi trả không qua chỉ thị chuyển, chẳng hạn như một giao dịch bán trên Pump.fun. Nó cũng phát hiện các dịch chuyển phát sinh khác, như tiền tip Jito và tiền thuê được thanh toán cho hoặc hoàn lại từ các tài khoản.

Nhận giao dịch đã phân tích, chữ ký hoặc số lượng

returnShape xác định dữ liệu mà phản hồi trả về cho các kết quả khớp:

Ví dụ, yêu cầu này đếm số giao dịch mua Pump.fun của một nhà giao dịch trong tháng 9 năm 2026 mà không trả về giao dịch:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2"]
      }
    ]
  },
  "returnShape": "count",
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Khi đếm, signatures và count bỏ qua limit và bao quát mọi kết quả khớp trong phạm vi mà yêu cầu quét. Để đếm một lịch sử dài, hãy tiếp tục phân trang và cộng scan.matchedTransactions.

Cả ba dạng phản hồi đều có cùng chi phí.

Kiểm soát lượng lịch sử mà mỗi yêu cầu quét

Mỗi yêu cầu có thể quét tối đa 10.000 giao dịch và trả về tối đa 100 kết quả khớp.

Trường budget.maxScannedTransactions kiểm soát giới hạn đó và mặc định là 10.000. Trường limit kiểm soát số kết quả khớp mà endpoint trả về; trường này chấp nhận giá trị từ 1 đến 100 và mặc định là 100.

Hai tùy chọn kiểm soát này tách biệt vì kết quả khớp có thể thưa thớt. Nói cách khác, một yêu cầu có thể quét hàng nghìn giao dịch nhưng chỉ trả về vài kết quả khớp.

Theo mặc định, yêu cầu quét chỉ bao gồm các giao dịch thành công.

Đặt status thành failed hoặc any để bao gồm các giao dịch thất bại. Giao dịch thất bại đi kèm lỗi chương trình đã giải mã khi IDL của chương trình có định nghĩa các lỗi đó.

Tóm tắt quá trình quét

Mỗi phản hồi đều bao gồm bản tóm tắt scan:

{
  "data": [],
  "paginationToken": "460903064:422",
  "scan": {
    "stoppedOn": "budget",
    "scannedTransactions": 2000,
    "matchedTransactions": 0,
    "scannedThrough": {
      "slot": 460903064,
      "blockTime": 1792856105
    },
    "creditsCharged": 12
  }
}

Bản tóm tắt cho biết:

• Lý do quá trình quét dừng lại
• Số giao dịch đã quét
• Số giao dịch khớp
• Slot và thời gian block cuối cùng đã quét
• Số credit mà yêu cầu đã sử dụng

Cách phân trang khi quét hoạt động

Khi quá trình quét dừng, trường scan.stoppedOn cho biết lý do:

• windowEnd: quá trình quét đã đến cuối lịch sử hoặc khoảng thời gian
• limit: phản hồi chứa đủ số kết quả khớp được yêu cầu
• budget: yêu cầu đã đạt giới hạn số giao dịch được quét
• deadline: yêu cầu đã đạt giới hạn thời gian

Khi phản hồi có paginationToken, hãy gửi token đó trong yêu cầu tiếp theo và tiếp tục ngay cả khi mảng data hiện tại trống. Kết quả trống có thể có nghĩa là yêu cầu đã dùng hết ngân sách trước khi tìm thấy kết quả khớp, chứ không có nghĩa là không tồn tại kết quả khớp ở phần sau.

Ví dụ, vòng lặp này thu thập các giao dịch Pump.fun trong một giờ gần nhất.

Lưu ý rằng giới hạn time và giới hạn số yêu cầu ngăn vòng lặp duyệt toàn bộ lịch sử:

const PUMP_PROGRAM = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const ONE_HOUR_AGO = Math.floor(Date.now() / 1000) - 3600;
const MAX_REQUESTS = 50;

let paginationToken;
let requests = 0;

async function scanHistory() {
  const response = await fetch(
    `https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=${process.env.HELIUS_API_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        address: PUMP_PROGRAM,
        match: {
          programs: [{ programId: PUMP_PROGRAM, instructions: ["buy", "sell"] }],
        },
        time: { gte: ONE_HOUR_AGO },
        limit: 100,
        ...(paginationToken && { paginationToken }),
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

do {
  const page = await scanHistory();
  requests++;

  for (const transaction of page.data) {
    console.log(transaction.signature);
  }

  paginationToken = page.paginationToken;
} while (paginationToken && requests < MAX_REQUESTS);

Kết quả đã phân tích mà không cần pipeline phía máy khách

Mỗi mục trong data sử dụng cùng định dạng TransactionResult như endpoint Parse Transactions của Parsed Events. Khi có sẵn, kết quả có thể bao gồm chỉ thị đã giải mã, giao dịch chuyển, thay đổi tài khoản, sự kiện, bản tóm tắt giao dịch và dữ liệu đã phân tích dành riêng cho giao thức. Nếu ứng dụng cũng cần payload giao dịch Solana gốc, hãy đặt rawTransaction thành "json", "jsonParsed" hoặc "base64".

Khác biệt chính nằm ở nơi quy trình xử lý lịch sử được thực thi.

Ứng dụng của bạn chỉ cần xác định tiêu chí tìm kiếm một lần, còn Parsed Events Scan API sẽ xử lý việc phân trang lịch sử, so khớp và phân tích trước khi trả về các giao dịch liên quan.

Sử dụng các Helius SDK mới nhất

Cả SDK TypeScript và Rust của chúng tôi đều hỗ trợ Parsed Events API và endpoint quét mới.

TypeScript SDK cung cấp chức năng quét dưới dạng helius.parsedEvents.scan(). Kiểu phản hồi tuân theo returnShape được truyền vào:

const { scan } = await helius.parsedEvents.scan({
  address: "<WALLET_ADDRESS>",
  match: {
    programs: [{ programId: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", instructions: ["buy", "sell"] }],
  },
  returnShape: "count",
});

console.log(scan.matchedTransactions, scan.stoppedOn);

Rust SDK cũng cung cấp scan, scan_signatures và scan_count trên helius.parsed_events(); tất cả đều nhận cùng một ScanRequest.

Giá của Parsed Events Scan API

Mỗi yêu cầu Parsed Events Scan API có chi phí 10 credit, cộng thêm 1 credit cho mỗi trang lịch sử được quét. Một trang lịch sử chứa tối đa 1.000 giao dịch.

Ví dụ, một yêu cầu sử dụng ngân sách mặc định là 10.000 giao dịch có chi phí tối đa 20 credit. Phản hồi báo cáo chi phí chính xác trong scan.creditsCharged.

Để so sánh, chi phí quét bằng một phần mười chi phí phân trang cùng lượng lịch sử bằng getTransactionsForAddress, vốn tốn 100 credit mỗi trang (tối đa 1.000 giao dịch).

Kiểm soát mức sử dụng

Để kiểm soát mức sử dụng, hãy dùng địa chỉ có phạm vi hẹp nhất phù hợp và thêm giới hạn theo slot hoặc thời gian khi có thể. Càng ít giao dịch không liên quan, mỗi yêu cầu càng tìm được nhiều kết quả hữu ích.

Thay thế Enhanced Transactions API bằng Parsed Events API

Enhanced Transactions API vẫn hoạt động ở chế độ bảo trì nhưng không được bổ sung loại trình phân tích hoặc tính năng mới. Parsed Events là phiên bản kế nhiệm và sử dụng danh mục IDL của Helius để giải mã chỉ thị trên hàng nghìn chương trình Solana. Nếu chưa thực hiện, hãy di chuyển sang Parsed Events API.

Có gì khác biệt?

Enhanced Transactions API sắp xếp hoạt động vào một tập hợp loại giao dịch cố định, chẳng hạn như hoán đổi, chuyển tài sản và bán NFT. Trong khi đó, Parsed Events Scan API hỗ trợ tìm kiếm chính xác hơn theo chỉ thị chương trình, discriminator thô, mint token hoặc tổ hợp các tiêu chí này. Helius áp dụng các bộ lọc đó khi quét lịch sử địa chỉ và chỉ phân tích các giao dịch khớp.

Parsed Events API mang đến cho nhà phát triển phạm vi hỗ trợ chương trình rộng hơn và khả năng kiểm soát truy vấn lịch sử tốt hơn mà không cần duy trì trình quét phía máy khách.

Bắt đầu

Hãy dùng Parsed Events Scan API khi bạn biết mình cần hoạt động onchain nào nhưng không muốn xây dựng và duy trì trình quét lịch sử phía máy khách. Đọc tài liệu tham khảo Scan Transaction History API để xem toàn bộ schema yêu cầu, trường phản hồi, giới hạn, lỗi và các ví dụ khác.

Để tiếp tục khám phá khả năng của Scan API, hãy dùng thử công cụ Scan mới trong bảng điều khiển Helius. Thử quét địa chỉ theo chương trình, mint và các bộ lọc.