Chuyển đến nội dung chính
POST
Nội dung yêu cầu, lược đồ phản hồi và các ví dụ trên trang này được tạo từ định nghĩa OpenAPI. Scan duyệt lịch sử của một địa chỉ, giữ lại các giao dịch khớp với tiêu chí match của bạn và chỉ phân tích các giao dịch đó. Hãy dùng tính năng này thay vì phân trang qua Lịch sử giao dịch đã phân tích rồi lọc ở phía máy khách. Theo mặc định, mỗi mục trong data sử dụng cùng cấu trúc TransactionResult do Phân tích giao dịch trả về. Đặt returnShape để chỉ nhận các chữ ký khớp hoặc chỉ nhận số lượng. Phản hồi cũng bao gồm phần tóm tắt scan cho biết quá trình quét đã tiến đến đâu và lý do dừng.

Cách Scan hoạt động

  1. Scan tìm nạp lịch sử của địa chỉ theo các trang có tối đa 1.000 giao dịch, theo sortOrder, trong các giới hạn slot, time và chữ ký mà bạn đặt.
  2. Scan giữ lại các giao dịch khớp với mọi tiêu chí được đặt trong match.
  3. Scan dừng khi điều kiện đầu tiên trong số này xảy ra: tìm thấy limit kết quả khớp (chỉ với cấu trúc transactions mặc định), đã quét budget.maxScannedTransactions, đến cuối lịch sử hoặc khoảng thời gian, hoặc đạt giới hạn thời gian của yêu cầu.
Một lần quét dừng sớm vẫn là 200. Hãy gọi lại với paginationToken được trả về miễn là trường này còn hiện diện, ngay cả khi data trống.

Tiêu chí khớp

match là bắt buộc. Đặt programs, mints hoặc cả hai. Khi đặt cả hai, giao dịch phải khớp với cả hai.

Khớp theo chương trình

programs liệt kê tối đa 20 chương trình, mỗi chương trình chỉ xuất hiện một lần. Một giao dịch khớp khi có lệnh của bất kỳ chương trình nào trong số đó, ở cấp cao nhất hoặc bên trong (CPI), trong scope của chương trình. Với mỗi chương trình, bạn có thể thu hẹp điều kiện khớp:
  • instructions: tên lệnh từ bất kỳ phiên bản IDL nào của chương trình, theo cách viết trong IDL hoặc ở dạng snake_case. Tên không có trong các IDL của chương trình sẽ trả về 400.
  • discriminators: tiền tố dữ liệu lệnh, mỗi tiền tố dài từ 1 đến 8 byte được mã hóa hex, có thể kèm tiền tố 0x. Dùng các tiền tố này cho chương trình không có IDL.
  • Đặt một trong hai danh sách hoặc cả hai. Khi có cả hai, một lệnh khớp nếu đó là một trong các lệnh được đặt tên hoặc dữ liệu của lệnh bắt đầu bằng một trong các discriminator. Bỏ qua cả hai để khớp với mọi lệnh của chương trình.
  • Mỗi danh sách chấp nhận tối đa 50 mục cho mỗi chương trình.
Để xác nhận tên lệnh đã giải mã của một chương trình, hãy dùng phương thức Parsed Streams describeProgram.

Khớp theo mint

mints liệt kê tối đa 20 đối tượng có dạng { "mint": "...", "scope": "address" }, mỗi mint chỉ xuất hiện một lần. Một giao dịch khớp khi một trong các số dư token trước hoặc sau giao dịch thuộc một trong các mint, trong scope của mint đó. Khi quét ví theo mint, hãy đặt tokenAccounts thành balanceChanged. Theo mặc định, lịch sử bỏ qua các giao dịch chỉ tương tác với tài khoản token của ví mà không tương tác với chính ví, bao gồm nhiều giao dịch chuyển token đến.

Khớp với SOL gốc

SOL gốc không có số dư token, vì vậy Scan khớp dựa trên lamport. Dùng mint SOL gốc So11111111111111111111111111111111111111111 (SOL được bọc là So11111111111111111111111111111111111111112):
  • Với phạm vi address, giao dịch khớp khi số lamport của địa chỉ được quét thay đổi.
  • Với phạm vi transaction, giao dịch khớp khi số lamport của bất kỳ tài khoản nào thay đổi.
Phí được tính cho bên trả phí không được tính. Mỗi tài khoản được so sánh riêng, vì vậy số lamport rời khỏi một tài khoản rồi quay lại trong cùng giao dịch không được tính. Việc khớp SOL gốc phát hiện SOL do chương trình chi trả mà không có lệnh 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 chuyển động phát sinh, chẳng hạn 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.

Phạm vi khớp

Mỗi chương trình và mỗi mint nhận một scope: Dùng phạm vi transaction khi địa chỉ được quét có trong giao dịch nhưng không có trong lệnh hoặc số dư mà bạn muốn khớp. Ví dụ: địa chỉ chỉ trả phí, thực thi giao dịch đa chữ ký hoặc bị thiếu trong CPI sự kiện Anchor. Khi quét mint của một token để tìm các giao dịch cũng chứa USDC, mục USDC cần dùng phạm vi transaction. Quyền sở hữu tài khoản token được lấy từ owner được ghi trên mỗi số dư token. Các giao dịch cũ không ghi thông tin này chỉ khớp với phạm vi address trên chính address.

Cấu trúc trả về

returnShape xác định nội dung phản hồi chứa cho các kết quả khớp: signatures và count bỏ qua limit và rawTransaction. Chúng trả về mọi kết quả khớp trong phạm vi mà một yêu cầu quét, vì vậy chúng chỉ dừng ở windowEnd, budget hoặc deadline. Để đếm toàn bộ lịch sử, hãy tiếp tục gọi với paginationToken và cộng các giá trị scan.matchedTransactions. Mỗi mục trong data có returnShape: "signatures" trông như sau:
Cả ba cấu trúc đều có cùng chi phí vì số credit phụ thuộc vào các trang lịch sử được quét, không phụ thuộc vào nội dung được trả về.

Yêu cầu mẫu

Các giao dịch mua và bán trên Pump.fun

Quét lịch sử của chương trình Pump.fun để tìm các lệnh buy và sell:
Pump.fun cũng có các biến thể như buy_exact_sol_in, buy_v2 và sell_v2. Hãy liệt kê mọi tên lệnh bạn muốn khớp.

Giao dịch mua và bán một token

Để lấy các giao dịch Pump.fun của một token, hãy quét địa chỉ mint của token thay vì chương trình. Lịch sử của mint chỉ chứa hoạt động của token đó và mỗi lệnh mua hoặc bán đều liệt kê mint làm tài khoản, vì vậy lệnh sẽ khớp với phạm vi address mặc định:
Để chỉ giữ lại các giao dịch của token cũng liên quan đến tài khoản token USDC, hãy thêm USDC với phạm vi transaction. Với phạm vi address mặc định, số dư USDC sẽ phải thuộc về địa chỉ mint nên sẽ không có kết quả nào khớp:

Giao dịch của một ví trên hai chương trình

Liệt kê nhiều chương trình để khớp với lời gọi đến bất kỳ chương trình nào trong số đó. Yêu cầu này chỉ trả về chữ ký của các giao dịch Pump.fun và PumpSwap của một ví:

Hoạt động USDC của một ví trong một khoảng thời gian

Quét lịch sử của một ví để tìm các giao dịch đã tương tác với USDC trong năm 2025. tokenAccounts: "balanceChanged" bao gồm các giao dịch chuyển chỉ tương tác với tài khoản token USDC của ví:
Để chỉ lấy số lượng giao dịch khớp, hãy thêm "returnShape": "count".

Chuyển động SOL của một ví

Quét một ví để tìm các giao dịch đã thay đổi số dư SOL của ví ngoài khoản phí đã trả trong năm 2025. Điều này bao gồm SOL do chương trình chi trả mà không có lệnh chuyển:

Phân trang và lý do dừng

scan.stoppedOn cho biết lý do yêu cầu kết thúc: scan.scannedThrough cung cấp slot và thời gian khối của giao dịch cuối cùng được quét để bạn có thể báo cáo tiến trình qua các lịch sử dài. Một lần quét tìm lệnh hiếm có thể dùng hết ngân sách mà không tìm thấy kết quả khớp. Khi đó, phản hồi có mảng data trống nhưng vẫn trả về paginationToken, vì vậy hãy tiếp tục quét:
Vòng lặp này tiếp tục quét cho đến khi duyệt hết lịch sử:
scan-pumpfun-trades.js
Hãy quét địa chỉ có phạm vi hẹp nhất có thể. Mọi giao dịch trong lịch sử của địa chỉ đều được tính vào ngân sách, vì vậy địa chỉ càng có ít giao dịch không liên quan thì mỗi yêu cầu càng tìm thấy nhiều kết quả khớp.

Credit

Mỗi lần quét tốn 10 credit cộng thêm 1 credit cho mỗi trang lịch sử được quét. Một trang chứa tối đa 1.000 giao dịch, vì vậy một lần quét với ngân sách mặc định là 10.000 giao dịch tốn tối đa 20 credit. Trang bị ngắt do hết thời hạn sẽ không được quét và không bị tính phí. Mỗi phản hồi báo cáo khoản phí trong scan.creditsCharged. Xem Credit để biết giá của các gói.

Lỗi

Lỗi ở cấp yêu cầu trả về nội dung JSON có thông báo error, chẳng hạn như {"error": "limit must be between 1 and 100"}. Nội dung có trường không xác định, chẳng hạn như includeRawTransaction (hãy dùng rawTransaction), hoặc có mints ở dạng chuỗi thuần thay vì đối tượng { "mint": "..." }, sẽ trả về {"error": "invalid request payload"}.

Tham số yêu cầu

string
bắt buộc
Địa chỉ có lịch sử cần quét.
object
bắt buộc
Những gì một giao dịch phải khớp. Đặt programs, mints hoặc cả hai. Khi đặt cả hai, giao dịch phải khớp với cả hai.
array
Các chương trình cần khớp, tối đa 20 chương trình và mỗi chương trình chỉ xuất hiện một lần. Một giao dịch khớp khi có lệnh của bất kỳ chương trình nào trong số đó, ở cấp cao nhất hoặc bên trong (CPI), trong scope của chương trình.
string
bắt buộc
Địa chỉ chương trình.
array
Tên lệnh từ bất kỳ phiên bản IDL nào của chương trình, theo cách viết trong IDL hoặc ở dạng snake_case. Tối đa 50. Có thể kết hợp với discriminators.
array
Tiền tố dữ liệu lệnh, mỗi tiền tố dài từ 1 đến 8 byte được mã hóa hex, có thể kèm tiền tố 0x. Tối đa 50. Có thể kết hợp với instructions.
string
mặc định:"address"
Các lệnh nào của chương trình được tính. address chỉ tính các lệnh có một tài khoản là address, một tài khoản token do address sở hữu, hoặc một tài khoản token có mint là address; hoặc tính mọi lệnh khi address chính là chương trình. transaction tính mọi lệnh của chương trình trong giao dịch.
  • address
  • transaction
array
Các mint cần khớp, tối đa 20 mint và mỗi mint chỉ xuất hiện một lần. Một giao dịch khớp khi một trong các số dư token trước hoặc sau giao dịch thuộc một trong các mint này, trong scope của mint.
string
bắt buộc
Địa chỉ mint token. Mint SOL gốc So11111111111111111111111111111111111111111 khớp theo thay đổi lamport thay vì số dư token, không tính phí.
string
mặc định:"address"
Các số dư token nào của mint được tính. address chỉ tính các số dư có tài khoản token là address hoặc do địa chỉ đó sở hữu, hoặc có mint là address. Đối với SOL gốc, chỉ các thay đổi đối với số lamport của address được tính. transaction tính mọi số dư của mint trong giao dịch. Đối với SOL gốc, thay đổi số lamport của bất kỳ tài khoản nào cũng được tính.
  • address
  • transaction
string
mặc định:"transactions"
Nội dung phản hồi chứa cho các kết quả khớp: transactions (các kết quả khớp đã phân tích trong data, tối đa limit), signatures (signature, slot, transactionIndex và blockTime cho mỗi kết quả khớp trong data), hoặc count (không có data; scan.matchedTransactions là số lượng kết quả khớp). signatures và count bỏ qua limit và rawTransaction.
  • transactions
  • signatures
  • count
number
mặc định:"100"
Số kết quả khớp tối đa cần trả về với cấu trúc transactions, từ 1 đến 100.
object
Giới hạn lượng lịch sử mà một yêu cầu quét.
number
mặc định:"10000"
Số giao dịch tối đa cần quét trong yêu cầu này, từ 1 đến 10.000.
string
Quét các giao dịch trước chữ ký này.
string
Quét các giao dịch sau chữ ký này.
string
Con trỏ do lần quét trước trả về. Có cấu trúc slot:transactionIndex.
string
mặc định:"desc"
Thứ tự quét lịch sử và trả về các kết quả khớp.
  • asc
  • desc
string
mặc định:"confirmed"
Mức cam kết dùng để tìm nạp lịch sử. processed không được hỗ trợ.
  • confirmed
  • finalized
string
mặc định:"succeeded"
Kết quả thực thi cần bao gồm. Việc lọc diễn ra trước khi khớp, vì vậy các giao dịch bị loại trừ không được tính vào ngân sách.
  • succeeded
  • failed
  • any
string
mặc định:"none"
Có bao gồm các giao dịch chỉ tham chiếu đến tài khoản token do address sở hữu, chứ không phải chính address hay không: none loại trừ chúng, balanceChanged bao gồm các giao dịch làm thay đổi số dư của tài khoản token và all bao gồm tất cả. Dùng balanceChanged khi quét ví theo mint.
  • none
  • balanceChanged
  • all
number
Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá.
string
mặc định:"none"
Kiểu mã hóa của giao dịch Solana gốc được trả về dưới dạng rawTransaction trên mỗi kết quả thành công, trong cấu trúc getTransaction. Chỉ áp dụng cho cấu trúc transactions.
  • none
  • json
  • jsonParsed
  • base64
object
Các giới hạn so sánh slot. Mỗi giới hạn đều không bắt buộc.
number
Khớp với các giá trị lớn hơn giá trị này.
number
Khớp với các giá trị lớn hơn hoặc bằng giá trị này.
number
Khớp với các giá trị nhỏ hơn giá trị này.
number
Khớp với các giá trị nhỏ hơn hoặc bằng giá trị này.
object
Các giới hạn so sánh thời gian khối theo giây Unix. Mỗi giới hạn đều không bắt buộc.
number
Khớp với các giá trị lớn hơn giá trị này.
number
Khớp với các giá trị lớn hơn hoặc bằng giá trị này.
number
Khớp với các giá trị nhỏ hơn giá trị này.
number
Khớp với các giá trị nhỏ hơn hoặc bằng giá trị này.

Ủy quyền

api-key
string
query
bắt buộc

Nội dung

application/json

Nội dung yêu cầu để quét lịch sử của một địa chỉ nhằm tìm các giao dịch khớp.

address
string
bắt buộc

Địa chỉ có lịch sử được quét.

match
object
bắt buộc

Các điều kiện mà một giao dịch phải khớp. Đặt programs, mints hoặc cả hai. Khi đặt cả hai, giao dịch phải khớp cả hai.

returnShape
enum<string>
mặc định:transactions

Nội dung phản hồi chứa cho các kết quả khớp: transactions (các kết quả khớp đã phân tích trong data, tối đa limit), signatures (signature, slot, transactionIndex và blockTime cho mỗi kết quả khớp trong data) hoặc count (không có data; scan.matchedTransactions là số lượng kết quả khớp). signatures và count bỏ qua limit và rawTransaction.

Tùy chọn có sẵn:
transactions,
signatures,
count
limit
integer
mặc định:100

Số kết quả khớp tối đa cần trả về với cấu trúc transactions, từ 1 đến 100.

Phạm vi bắt buộc: 1 <= x <= 100
budget
object

Giới hạn lượng lịch sử mà một yêu cầu quét.

beforeSignature
string

Quét các giao dịch trước chữ ký này.

afterSignature
string

Quét các giao dịch sau chữ ký này.

paginationToken
string

Con trỏ do lần quét trước trả về. Có cấu trúc slot:transactionIndex.

sortOrder
enum<string>
mặc định:desc

Thứ tự quét lịch sử và trả về các kết quả khớp.

Tùy chọn có sẵn:
asc,
desc
commitment
enum<string>
mặc định:confirmed

Mức commitment dùng để truy xuất lịch sử. processed không được hỗ trợ.

Tùy chọn có sẵn:
confirmed,
finalized
status
enum<string>
mặc định:succeeded

Kết quả thực thi cần bao gồm. Quá trình lọc diễn ra trước khi đối sánh, vì vậy các giao dịch bị loại trừ không được tính vào ngân sách.

Tùy chọn có sẵn:
succeeded,
failed,
any
tokenAccounts
enum<string>
mặc định:none

Có bao gồm các giao dịch chỉ tham chiếu đến tài khoản token thuộc sở hữu của address, chứ không tham chiếu trực tiếp đến address, hay không: none loại trừ chúng, balanceChanged bao gồm các giao dịch làm thay đổi số dư tài khoản token và all bao gồm tất cả. Dùng balanceChanged khi quét ví theo mint.

Tùy chọn có sẵn:
none,
balanceChanged,
all
minContextSlot
integer

Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá.

rawTransaction
enum<string>
mặc định:none

Kiểu mã hóa của giao dịch Solana gốc được trả về dưới dạng rawTransaction trong mỗi kết quả thành công, theo cấu trúc getTransaction. Chỉ áp dụng cho cấu trúc transactions.

Tùy chọn có sẵn:
none,
json,
jsonParsed,
base64
slot
object

Các giới hạn so sánh slot. Mỗi giới hạn đều không bắt buộc.

time
object

Các giới hạn so sánh thời gian khối theo giây Unix. Mỗi giới hạn đều không bắt buộc.

Phản hồi

Các kết quả khớp theo returnShape được yêu cầu và bản tóm tắt quá trình quét. Kết quả một phần vẫn trả về 200; tiếp tục bằng paginationToken chừng nào trường này còn được trả về.

Các kết quả khớp theo returnShape được yêu cầu và bản tóm tắt quá trình quét.

data
object

Kết quả phân tích cú pháp cho từng chữ ký.

paginationToken
string

Con trỏ nơi lần quét tiếp theo tiếp tục. Không có khi quá trình quét đã đến cuối lịch sử hoặc cửa sổ.

scan
object

Quá trình quét đã tiến đến đâu và lý do dừng.