跳转到主要内容
POST
此页面上的请求正文、响应模式和示例均根据 OpenAPI 定义生成。 扫描功能会遍历一个地址的历史记录，保留符合 match 条件的交易，并且只解析这些交易。你可以使用它来代替逐页获取 Parsed Transaction History 并在客户端进行筛选。 默认情况下，data 中的每一项都采用 Parse Transactions 返回的相同 TransactionResult 结构。设置 returnShape 可仅获取匹配的签名或匹配数量。响应还包含 scan 摘要，说明扫描进度以及停止原因。

​
扫描的工作方式

  1. 扫描功能会按每页最多 1,000 笔交易获取该地址的历史记录，并采用 sortOrder 顺序，同时遵循你设置的 slot、time 和签名边界。
  2. 它会保留符合 match 中所有条件的交易。
  3. 遇到以下任一情况时停止：找到 limit 个匹配项（仅适用于默认的 transactions 结构）、已扫描 budget.maxScannedTransactions 笔交易、到达历史记录或窗口末尾，或者达到请求时限。
提前停止的扫描仍然是 200。只要返回了 paginationToken，就使用它再次调用，即使 data 为空也是如此。

​
匹配条件

必须提供 match。设置 programs、mints 或两者。若同时设置，交易必须同时匹配两者。

​
按程序匹配

programs 最多可列出 20 个程序，每个程序最多出现一次。如果交易中包含其中任一程序的顶层或内部（CPI）指令，并且符合该程序的 scope，则交易匹配。 对于每个程序，你可以进一步缩小匹配范围：
  • instructions：程序任意 IDL 版本中的指令名称，可采用 IDL 中的原始拼写或 snake_case。若程序的 IDL 中不存在指定名称，将返回 400。
  • discriminators：指令数据前缀，每个前缀为 1 到 8 个十六进制编码的字节，可带可选的 0x 前缀。对于没有 IDL 的程序，请使用此项。
  • 可以设置其中一个列表或同时设置两个列表。如果同时设置，则当指令是指定名称之一，或其数据以任一鉴别符开头时，该指令即匹配。省略两者可匹配该程序的任意指令。
  • 每个程序的每个列表最多接受 50 个条目。
要确认程序解码后的指令名称，请使用 Parsed Streams 的 describeProgram 方法。

​
按铸币地址匹配

mints 最多可列出 20 个采用 { "mint": "...", "scope": "address" } 形式的对象，每个铸币地址最多出现一次。如果交易的任一交易前或交易后代币余额属于这些铸币地址之一，并且符合该铸币地址的 scope，则交易匹配。 按铸币地址扫描钱包时，请将 tokenAccounts 设置为 balanceChanged。默认情况下，历史记录会排除仅涉及钱包代币账户而不涉及钱包本身的交易，其中包括许多传入的代币转账。

​
匹配原生 SOL

原生 SOL 没有代币余额，因此扫描功能通过 lamport 匹配它。请使用原生 SOL 铸币地址 So11111111111111111111111111111111111111111（封装 SOL 为 So11111111111111111111111111111111111111112）：
  • 使用 address 范围时，如果被扫描地址的 lamport 发生变化，则交易匹配。
  • 使用 transaction 范围时，如果任意账户的 lamport 发生变化，则交易匹配。
向费用支付者收取的费用不计入其中。每个账户会单独比较，因此从某个账户转出后又在同一笔交易中转回的 lamport 不计入其中。原生 SOL 匹配可以捕获程序在没有转账指令的情况下支付 SOL 的情况，例如 Pump.fun 卖出交易。它也会捕获附带的资金变动，例如 Jito 小费，以及为账户支付或从账户退还的租金。

​
匹配范围

每个程序和每个铸币地址都接受一个 scope： 当被扫描地址存在于交易中，但不在你要匹配的指令或余额中时，请使用 transaction 范围。例如，该地址仅支付费用、执行多重签名交易，或者未出现在 Anchor 事件 CPI 中。扫描某个代币的铸币地址以查找同时持有 USDC 的交易时，需要在 USDC 条目上使用 transaction 范围。 代币账户所有权取自每个代币余额中记录的 owner。对于未记录此信息的旧交易，address 范围只会匹配 address 本身。

​
返回结构

returnShape 设置响应为匹配项携带的内容： signatures 和 count 会忽略 limit 和 rawTransaction。它们会返回一次请求所扫描范围内的所有匹配项，因此只会因 windowEnd、budget 或 deadline 而停止。要统计整个历史记录，请持续使用 paginationToken 调用，并累加 scan.matchedTransactions。 使用 returnShape: "signatures" 时，data 中的每一项如下所示：
由于积分取决于扫描的历史记录页数，而不是返回的内容，因此三种结构的费用相同。

​
请求示例

​
Pump.fun 买入和卖出

扫描 Pump.fun 程序的历史记录，查找 buy 和 sell 指令：
Pump.fun 还有 buy_exact_sol_in、buy_v2 和 sell_v2 等变体。请列出你要匹配的所有指令名称。

​
单个代币的买入和卖出

要获取某个代币的 Pump.fun 交易，请扫描该代币的铸币地址，而不是程序。铸币地址的历史记录只包含该代币的活动，并且每条买入或卖出指令都会将铸币地址列为账户，因此可使用默认的 address 范围进行匹配：
要仅保留还涉及 USDC 代币账户的代币交易，请添加 USDC 并使用 transaction 范围。如果使用默认的 address 范围，USDC 余额必须属于该铸币地址，因此不会有任何匹配项：

​
一个钱包在两个程序中的交易

列出多个程序可匹配对其中任一程序的调用。此请求仅以签名形式返回某个钱包的 Pump.fun 和 PumpSwap 交易：

​
某个时间范围内钱包的 USDC 活动

扫描钱包历史记录，查找 2025 年期间涉及 USDC 的交易。tokenAccounts: "balanceChanged" 会包括仅涉及钱包 USDC 代币账户的转账：
要仅获取匹配交易的数量，请添加 "returnShape": "count"。

​
钱包的 SOL 变动

扫描钱包，查找 2025 年期间除其支付费用以外导致 SOL 余额变化的交易。这包括程序在没有转账指令的情况下支付的 SOL：

​
分页和停止原因

scan.stoppedOn 会说明请求结束的原因： scan.scannedThrough 提供最后一笔已扫描交易的 slot 和区块时间，因此你可以报告处理较长历史记录时的进度。 扫描罕见指令时，可能在找到匹配项之前就耗尽预算。此时响应中的 data 数组为空，但仍会返回 paginationToken，因此请继续扫描：
此循环会持续扫描，直到历史记录全部处理完毕：
scan-pumpfun-trades.js
尽可能扫描范围最窄的地址。该地址历史记录中的每笔交易都会计入预算，因此地址中的无关交易越少，每个请求能找到的匹配项就越多。

​
积分

每次扫描的费用为 10 积分，外加每扫描一页历史记录 1 积分。每页最多包含 1,000 笔交易，因此使用默认 10,000 笔交易预算的扫描最多花费 20 积分。因截止时间而中断的页面不会被扫描，也不会收费。 每个响应都会在 scan.creditsCharged 中报告其费用。有关套餐定价，请参阅积分。

​
错误

请求级错误会返回包含 error 消息的 JSON 正文，例如 {"error": "limit must be between 1 and 100"}。若正文包含未知字段，例如 includeRawTransaction（应使用 rawTransaction），或者将 mints 设置为纯字符串而不是 { "mint": "..." } 对象，则返回 {"error": "invalid request payload"}。

​
请求参数

​
string
必填
要扫描其历史记录的地址。
​
object
必填
交易必须匹配的内容。设置 programs、mints 或两者。若同时设置，交易必须同时匹配两者。
​
array
要匹配的程序，最多 20 个，每个程序最多出现一次。如果交易中包含其中任一程序的顶层或内部（CPI）指令，并且符合该程序的 scope，则交易匹配。
​
string
必填
程序地址。
​
array
程序任意 IDL 版本中的指令名称，可采用 IDL 中的原始拼写或 snake_case。最多 50 个。可与 discriminators 组合使用。
​
array
指令数据前缀，每个前缀为 1 到 8 个十六进制编码的字节，可带可选的 0x 前缀。最多 50 个。可与 instructions 组合使用。
​
string
默认值:"address"
哪些程序指令计入匹配。address 仅计入以下指令：其某个账户是 address、由 address 拥有的代币账户、铸币地址为 address 的代币账户；或者当 address 本身就是该程序时，计入所有指令。transaction 会计入交易中该程序的任意指令。
  • address
  • transaction
​
array
要匹配的铸币地址，最多 20 个，每个最多出现一次。如果交易的任一交易前或交易后代币余额属于其中某个铸币地址，并且符合该铸币地址的 scope，则交易匹配。
​
string
必填
代币铸币地址。原生 SOL 铸币地址 So11111111111111111111111111111111111111111 根据 lamport 变化而不是代币余额进行匹配，且不计入费用。
​
string
默认值:"address"
铸币地址的哪些代币余额计入匹配。address 仅计入以下余额：其代币账户是 address 或由它拥有，或者其铸币地址是 address。对于原生 SOL，仅 address 的 lamport 变化计入匹配。transaction 会计入交易中该铸币地址的任意余额。对于原生 SOL，任意账户的 lamport 变化都计入匹配。
  • address
  • transaction
​
string
默认值:"transactions"
响应为匹配项携带的内容：transactions（data 中解析后的匹配项，最多 limit 个）、signatures（data 中的每个匹配项包含 signature、slot、transactionIndex 和 blockTime），或 count（没有 data；scan.matchedTransactions 为匹配项数量）。signatures 和 count 会忽略 limit 和 rawTransaction。
  • transactions
  • signatures
  • count
​
number
默认值:"100"
使用 transactions 结构时最多返回的匹配项数量，范围为 1 到 100。
​
object
单个请求可扫描的历史记录量限制。
​
number
默认值:"10000"
此请求最多扫描的交易数量，范围为 1 到 10,000。
​
string
扫描此签名之前的交易。
​
string
扫描此签名之后的交易。
​
string
上一次扫描返回的游标。结构为 slot:transactionIndex。
​
string
默认值:"desc"
扫描历史记录和返回匹配项的顺序。
  • asc
  • desc
​
string
默认值:"confirmed"
获取历史记录时使用的确认级别。不支持 processed。
  • confirmed
  • finalized
​
string
默认值:"succeeded"
要包含的执行结果。筛选发生在匹配之前，因此被排除的交易不会计入预算。
  • succeeded
  • failed
  • any
​
string
默认值:"none"
是否包含仅引用 address 所拥有的代币账户、而不引用 address 本身的交易：none 会排除这些交易；balanceChanged 会包含改变代币账户余额的交易；all 会包含所有这些交易。按铸币地址扫描钱包时，请使用 balanceChanged。
  • none
  • balanceChanged
  • all
​
number
可评估请求的最小 slot。
​
string
默认值:"none"
原始 Solana 交易的编码。该交易在每个成功结果中以 rawTransaction 返回，并采用 getTransaction 结构。仅适用于 transactions 结构。
  • none
  • json
  • jsonParsed
  • base64
​
object
slot 比较边界。每个边界均为可选。
​
number
匹配大于此值的值。
​
number
匹配大于或等于此值的值。
​
number
匹配小于此值的值。
​
number
匹配小于或等于此值的值。
​
object
以 Unix 秒表示的区块时间比较边界。每个边界均为可选。
​
number
匹配大于此值的值。
​
number
匹配大于或等于此值的值。
​
number
匹配小于此值的值。
​
number
匹配小于或等于此值的值。

授权

​
api-key
string
query
必填

请求体

application/json

扫描某个地址的历史记录以查找匹配交易的请求体。

​
address
string
必填

要扫描其历史记录的地址。

​
match
object
必填

交易必须满足的匹配条件。设置 programs、mints 或同时设置两者。同时设置时，交易必须同时满足这两个条件。

​
returnShape
enum<string>
默认值:transactions

响应为匹配项携带的内容：transactions（data 中已解析的匹配项，最多 limit 个）、signatures（data 中每个匹配项包含 signature、slot、transactionIndex 和 blockTime）或 count（无 data；scan.matchedTransactions 为匹配数量）。signatures 和 count 会忽略 limit 与 rawTransaction。

可用选项:
transactions,
signatures,
count
​
limit
integer
默认值:100

使用 transactions 结构时最多返回的匹配项数量，范围为 1 到 100。

必填范围: 1 <= x <= 100
​
budget
object

单个请求扫描历史记录量的限制。

​
beforeSignature
string

扫描此签名之前的交易。

​
afterSignature
string

扫描此签名之后的交易。

​
paginationToken
string

上一次扫描返回的游标。结构为 slot:transactionIndex。

​
sortOrder
enum<string>
默认值:desc

扫描历史记录及返回匹配项的顺序。

可用选项:
asc,
desc
​
commitment
enum<string>
默认值:confirmed

获取历史记录时使用的确认级别。不支持 processed。

可用选项:
confirmed,
finalized
​
status
enum<string>
默认值:succeeded

要包含的执行结果。筛选在匹配之前进行，因此被排除的交易不会计入预算。

可用选项:
succeeded,
failed,
any
​
tokenAccounts
enum<string>
默认值:none

是否包含仅引用 address 所拥有的代币账户、而不引用 address 本身的交易：none 排除这些交易，balanceChanged 包含会改变代币账户余额的交易，all 则包含全部此类交易。按铸币地址扫描钱包时，请使用 balanceChanged。

可用选项:
none,
balanceChanged,
all
​
minContextSlot
integer

可评估请求的最小槽位。

​
rawTransaction
enum<string>
默认值:none

原始 Solana 交易的编码。每个成功结果都会在 rawTransaction 中以 getTransaction 的结构返回该交易。仅适用于 transactions 结构。

可用选项:
none,
json,
jsonParsed,
base64
​
slot
object

槽位比较边界。每个边界均为可选。

​
time
object

以 Unix 秒表示的区块时间比较边界。每个边界均为可选。

响应

采用请求的 returnShape 返回匹配项及扫描摘要。部分结果仍返回 200；只要返回了 paginationToken，就使用它继续扫描。

采用请求的 returnShape 返回的匹配项及扫描摘要。

​
data
object

每个签名的解析器结果。

​
paginationToken
string

下一次扫描继续位置的游标。扫描到达历史记录或时间窗口末尾时缺失。

​
scan
object

扫描进度及停止原因。