Skip to main content
POST
The request body, response schema, and examples on this page are generated from the OpenAPI definition. Scan walks one address’s history, keeps the transactions that match your match criteria, and parses only those. Use it instead of paging through Parsed Transaction History and filtering client-side. By default, each item in data uses the same TransactionResult shape returned by Parse Transactions. Set returnShape to get only the matching signatures or only a count. The response also includes a scan summary that tells you how far the scan got and why it stopped.

​
How Scan Works

  1. Scan fetches the address’s history in pages of up to 1,000 transactions, in sortOrder, within the slot, time, and signature bounds you set.
  2. It keeps the transactions that match every criterion set in match.
  3. It stops at the first of these: limit matches found (default transactions shape only), budget.maxScannedTransactions scanned, the end of the history or window, or the request time limit.
A scan that stops early is still a 200. Call again with the returned paginationToken while one is present, even when data is empty.

​
Match Criteria

match is required. Set programs, mints, or both. When you set both, a transaction must match both.

​
Match by Program

programs lists up to 20 programs, each at most once. A transaction matches when it has an instruction of any of them, top-level or inner (CPI), within the program’s scope. For each program, you can narrow the match:
  • instructions: instruction names from any IDL version of the program, as the IDL spells them or in snake_case. A name not found in the program’s IDLs returns 400.
  • discriminators: instruction data prefixes, each 1 to 8 hex-encoded bytes with an optional 0x prefix. Use these for programs without an IDL.
  • Set either list or both. With both, an instruction matches when it is one of the named instructions or its data starts with one of the discriminators. Omit both to match any instruction of the program.
  • Each list accepts at most 50 entries per program.
To confirm a program’s decoded instruction names, use the Parsed Streams describeProgram method.

​
Match by Mint

mints lists up to 20 objects of the form { "mint": "...", "scope": "address" }, each mint at most once. A transaction matches when one of its pre or post token balances is of one of the mints, within that mint’s scope. When you scan a wallet for a mint, set tokenAccounts to balanceChanged. By default, history leaves out transactions that touch only the wallet’s token accounts and not the wallet itself, which includes many incoming token transfers.

​
Match Native SOL

Native SOL has no token balances, so scan matches it on lamports. Use the native SOL mint So11111111111111111111111111111111111111111 (wrapped SOL is So11111111111111111111111111111111111111112):
  • With address scope, a transaction matches when the scanned address’s lamports changed.
  • With transaction scope, it matches when any account’s lamports changed.
The fee charged to the fee payer does not count. Each account is compared on its own, so lamports that leave an account and come back in the same transaction do not count. Native SOL matching catches SOL a program pays out without a transfer instruction, such as a Pump.fun sell. It also catches incidental movements, such as Jito tips and rent paid for or refunded from accounts.

​
Match Scope

Each program and each mint takes a scope: Use transaction scope when the scanned address is in the transaction but not in the instruction or balance you match. For example, the address only pays the fee, executes a multisig transaction, or is missing from an Anchor event CPI. Scanning a token’s mint for transactions that also hold USDC needs transaction scope on the USDC entry. Token account ownership comes from the owner recorded on each token balance. Older transactions that do not record it match address scope only on address itself.

​
Return Shapes

returnShape sets what the response carries for the matches: signatures and count ignore limit and rawTransaction. They return every match in the range a request scans, so they stop only on windowEnd, budget, or deadline. To count a whole history, keep calling with paginationToken and add up scan.matchedTransactions. Each item in data with returnShape: "signatures" looks like this:
All three shapes cost the same, since credits depend on the history pages scanned, not on what is returned.

​
Example Requests

​
Pump.fun Buys and Sells

Scan the Pump.fun program’s history for buy and sell instructions:
Pump.fun also has variants such as buy_exact_sol_in, buy_v2, and sell_v2. List every instruction name you want to match.

​
Buys and Sells of One Token

To get one token’s Pump.fun trades, scan the token’s mint address instead of the program. The mint’s history holds only that token’s activity, and each buy or sell instruction lists the mint as an account, so it matches with the default address scope:
To keep only the token’s transactions that also involve a USDC token account, add USDC with transaction scope. With the default address scope, a USDC balance would have to belong to the mint address, so nothing would match:

​
A Wallet’s Trades Across Two Programs

List several programs to match a call to any of them. This request returns a wallet’s Pump.fun and PumpSwap trades as signatures only:

​
A Wallet’s USDC Activity in a Time Range

Scan a wallet’s history for transactions that touched USDC during 2025. tokenAccounts: "balanceChanged" includes transfers that touched only the wallet’s USDC token account:
To get only the number of matching transactions, add "returnShape": "count".

​
A Wallet’s SOL Movements

Scan a wallet for transactions that changed its SOL balance, beyond the fee it paid, during 2025. This includes SOL that a program paid out without a transfer instruction:

​
Pagination and Stop Reasons

scan.stoppedOn tells you why the request ended: scan.scannedThrough gives the slot and block time of the last transaction scanned, so you can report progress through long histories. A scan for a rare instruction can use up its budget without finding a match. The response then has an empty data array and still returns a paginationToken, so keep scanning:
This loop keeps scanning until the history is exhausted:
scan-pumpfun-trades.js
Scan the narrowest address you can. Every transaction in the address’s history counts toward the budget, so the fewer unrelated transactions an address has, the more matches each request finds.

​
Credits

Each scan costs 10 credits plus 1 credit per history page scanned. A page holds up to 1,000 transactions, so a scan with the default budget of 10,000 transactions costs at most 20 credits. A page cut off by the deadline is not scanned and not charged. Each response reports its charge in scan.creditsCharged. See Credits for plan pricing.

​
Errors

Request-level errors return a JSON body with an error message, such as {"error": "limit must be between 1 and 100"}. A body with an unknown field, such as includeRawTransaction (use rawTransaction), or with mints as plain strings instead of { "mint": "..." } objects, returns {"error": "invalid request payload"}.

​
Request Parameters

​
string
required
Address whose history is scanned.
​
object
required
What a transaction must match. Set programs, mints, or both. When both are set, a transaction must match both.
​
array
Programs to match, at most 20, each at most once. A transaction matches when it has an instruction of any of them, top-level or inner (CPI), within the program’s scope.
​
string
required
Program address.
​
array
Instruction names from any IDL version of the program, as the IDL spells them or in snake_case. At most 50. Can be combined with discriminators.
​
array
Instruction data prefixes, each 1 to 8 hex-encoded bytes with an optional 0x prefix. At most 50. Can be combined with instructions.
​
string
default:"address"
Which of the program’s instructions count. address counts only instructions with an account that is address, a token account address owns, or a token account whose mint is address, or every instruction when address is the program. transaction counts any instruction of the program in the transaction.
  • address
  • transaction
​
array
Mints to match, at most 20, each at most once. A transaction matches when one of its pre or post token balances is of one of these mints, within the mint’s scope.
​
string
required
Token mint address. The native SOL mint So11111111111111111111111111111111111111111 matches on lamport changes instead of token balances, not counting the fee.
​
string
default:"address"
Which of the mint’s token balances count. address counts only balances whose token account is address or is owned by it, or whose mint is address. For native SOL, only changes to address’s lamports count. transaction counts any balance of the mint in the transaction. For native SOL, a change to any account’s lamports counts.
  • address
  • transaction
​
string
default:"transactions"
What the response carries for the matches: transactions (parsed matches in data, up to limit), signatures (signature, slot, transactionIndex, and blockTime per match in data), or count (no data; scan.matchedTransactions is the number of matches). signatures and count ignore limit and rawTransaction.
  • transactions
  • signatures
  • count
​
number
default:"100"
Most matches to return with the transactions shape, from 1 to 100.
​
object
Limits on how much history one request scans.
​
number
default:"10000"
Most transactions to scan in this request, from 1 to 10,000.
​
string
Scan transactions before this signature.
​
string
Scan transactions after this signature.
​
string
Cursor returned by a previous scan. Shape is slot:transactionIndex.
​
string
default:"desc"
Order in which history is scanned and matches are returned.
  • asc
  • desc
​
string
default:"confirmed"
Commitment level used for the history fetch. processed is not supported.
  • confirmed
  • finalized
​
string
default:"succeeded"
Execution result to include. Filtering happens before matching, so excluded transactions do not count toward the budget.
  • succeeded
  • failed
  • any
​
string
default:"none"
Whether to include transactions that reference only a token account owned by address, not address itself: none leaves them out, balanceChanged includes those that change the token account’s balance, and all includes all of them. Use balanceChanged when you scan a wallet by mint.
  • none
  • balanceChanged
  • all
​
number
Minimum slot at which the request can be evaluated.
​
string
default:"none"
Encoding of the original Solana transaction returned as rawTransaction on each successful result, in the getTransaction shape. Applies to the transactions shape only.
  • none
  • json
  • jsonParsed
  • base64
​
object
Slot comparison bounds. Each bound is optional.
​
number
Match values greater than this value.
​
number
Match values greater than or equal to this value.
​
number
Match values less than this value.
​
number
Match values less than or equal to this value.
​
object
Block-time comparison bounds in Unix seconds. Each bound is optional.
​
number
Match values greater than this value.
​
number
Match values greater than or equal to this value.
​
number
Match values less than this value.
​
number
Match values less than or equal to this value.

Authorizations

​
api-key
string
query
required

Body

application/json

Request body for scanning an address's history for matching transactions.

​
address
string
required

Address whose history is scanned.

​
match
object
required

What a transaction must match. Set programs, mints, or both. When both are set, a transaction must match both.

​
returnShape
enum<string>
default:transactions

What the response carries for the matches: transactions (parsed matches in data, up to limit), signatures (signature, slot, transactionIndex, and blockTime per match in data), or count (no data; scan.matchedTransactions is the number of matches). signatures and count ignore limit and rawTransaction.

Available options:
transactions,
signatures,
count
​
limit
integer
default:100

Most matches to return with the transactions shape, from 1 to 100.

Required range: 1 <= x <= 100
​
budget
object

Limits on how much history one request scans.

​
beforeSignature
string

Scan transactions before this signature.

​
afterSignature
string

Scan transactions after this signature.

​
paginationToken
string

Cursor returned by a previous scan. Shape is slot:transactionIndex.

​
sortOrder
enum<string>
default:desc

Order in which history is scanned and matches are returned.

Available options:
asc,
desc
​
commitment
enum<string>
default:confirmed

Commitment level used for the history fetch. processed is not supported.

Available options:
confirmed,
finalized
​
status
enum<string>
default:succeeded

Execution result to include. Filtering happens before matching, so excluded transactions do not count toward the budget.

Available options:
succeeded,
failed,
any
​
tokenAccounts
enum<string>
default:none

Whether to include transactions that reference only a token account owned by address, not address itself: none leaves them out, balanceChanged includes those that change the token account's balance, and all includes all of them. Use balanceChanged when you scan a wallet by mint.

Available options:
none,
balanceChanged,
all
​
minContextSlot
integer

Minimum slot at which the request can be evaluated.

​
rawTransaction
enum<string>
default:none

Encoding of the original Solana transaction returned as rawTransaction on each successful result, in the getTransaction shape. Applies to the transactions shape only.

Available options:
none,
json,
jsonParsed,
base64
​
slot
object

Slot comparison bounds. Each bound is optional.

​
time
object

Block-time comparison bounds in Unix seconds. Each bound is optional.

Response

The matches in the requested returnShape and a summary of the scan. A partial result is still a 200; continue with paginationToken while one is returned.

The matches in the requested returnShape and a summary of the scan.

​
data
object

Per-signature parser result.

​
paginationToken
string

Cursor where the next scan continues. Missing when the scan reached the end of the history or window.

​
scan
object

How far the scan got and why it stopped.