メインコンテンツへスキップ
POST
このページのリクエストボディ、レスポンススキーマ、例は、OpenAPI 定義から生成されています。 Scan は、1 つのアドレスの履歴を走査し、match 条件に一致するトランザクションを保持して、そのトランザクションのみを解析します。解析済みトランザクション履歴をページ送りしてクライアント側でフィルタリングする代わりに使用してください。 デフォルトでは、data の各項目には、トランザクションを解析が返すものと同じ TransactionResult 形式が使用されます。一致する署名のみ、または件数のみを取得するには、returnShape を設定します。レスポンスには、スキャンの到達範囲と停止理由を示す scan の概要も含まれます。

Scan の仕組み

  1. Scan は、設定した slot、time、および署名の境界内で、sortOrder の順序に従い、最大 1,000 件のトランザクションからなるページ単位でアドレスの履歴を取得します。
  2. match に設定されたすべての条件に一致するトランザクションを保持します。
  3. 次のいずれかに最初に達した時点で停止します:limit 件の一致を検出した場合(デフォルトの transactions 形式のみ)、budget.maxScannedTransactions 件をスキャンした場合、履歴または範囲の末尾に到達した場合、あるいはリクエストの制限時間に達した場合。
早期に停止したスキャンも 200 です。paginationToken が返されている間は、data が空の場合でも、それを指定して再度呼び出してください。

一致条件

match は必須です。programs、mints、またはその両方を設定します。両方を設定した場合、トランザクションは両方に一致する必要があります。

プログラムによる照合

programs には最大 20 個のプログラムを指定でき、同じプログラムを複数回指定することはできません。プログラムの scope 内で、トップレベルまたは内部(CPI)に対象プログラムのいずれかの命令がある場合、トランザクションは一致します。 各プログラムでは、一致条件をさらに絞り込めます:
  • instructions:プログラムの任意の IDL バージョンにある命令名を、IDL の表記または snake_case で指定します。プログラムの IDL に存在しない名前を指定すると、400 が返されます。
  • discriminators:命令データのプレフィックスです。それぞれ 1~8 バイトの 16 進数エンコード値で、オプションの 0x プレフィックスを使用できます。IDL のないプログラムに使用します。
  • どちらか一方または両方のリストを設定します。両方を設定した場合、指定した名前の命令であるか、データがいずれかのディスクリミネーターで始まると、命令は一致します。プログラムのすべての命令に一致させるには、両方を省略します。
  • 各リストには、プログラムごとに最大 50 件を指定できます。
プログラムのデコード済み命令名を確認するには、Parsed Streams の describeProgram メソッドを使用してください。

ミントによる照合

mints には、{ "mint": "...", "scope": "address" } 形式のオブジェクトを最大 20 個指定でき、同じミントを複数回指定することはできません。ミントの scope 内で、トランザクション前後のトークン残高のいずれかが指定したミントのものである場合、トランザクションは一致します。 ウォレットでミントをスキャンする場合は、tokenAccounts を balanceChanged に設定します。デフォルトでは、ウォレット自体ではなく、そのウォレットのトークンアカウントのみに関与するトランザクションは履歴から除外されます。これには、多くの受信トークン転送が含まれます。

ネイティブ SOL の照合

ネイティブ SOL にはトークン残高がないため、Scan は lamport に基づいて照合します。ネイティブ SOL ミント So11111111111111111111111111111111111111111 を使用してください(ラップ済み SOL は So11111111111111111111111111111111111111112 です):
  • address スコープでは、スキャン対象アドレスの lamport が変化するとトランザクションは一致します。
  • transaction スコープでは、いずれかのアカウントの lamport が変化すると一致します。
手数料支払者に課される手数料はカウントされません。各アカウントは個別に比較されるため、同じトランザクション内でアカウントから出て戻ってきた lamport はカウントされません。ネイティブ SOL の照合では、Pump.fun の売却など、転送命令なしでプログラムが支払う SOL も検出できます。また、Jito のチップや、アカウントに対して支払われた、またはアカウントから返金された rent など、付随的な移動も検出します。

一致スコープ

各プログラムと各ミントには scope を指定します: スキャン対象アドレスがトランザクション内にはあるものの、照合する命令または残高には含まれない場合は、transaction スコープを使用します。たとえば、アドレスが手数料の支払いのみを行う場合、マルチシグトランザクションを実行する場合、または Anchor イベント CPI から欠落している場合です。あるトークンのミントをスキャンし、USDC も保有するトランザクションを検索する場合は、USDC エントリに transaction スコープが必要です。 トークンアカウントの所有権は、各トークン残高に記録された owner に基づきます。これが記録されていない古いトランザクションでは、address スコープは address 自体に対してのみ一致します。

戻り値の形式

returnShape は、一致結果としてレスポンスに含める内容を設定します: signatures と count は、limit と rawTransaction を無視します。1 回のリクエストでスキャンした範囲内のすべての一致を返すため、windowEnd、budget、または deadline の場合にのみ停止します。履歴全体をカウントするには、paginationToken を指定して呼び出しを続け、scan.matchedTransactions を合計します。 returnShape: "signatures" を指定した data の各項目は、次のようになります:
クレジットは返される内容ではなく、スキャンした履歴ページ数に基づくため、3 つの形式のコストはすべて同じです。

リクエスト例

Pump.fun の購入と売却

Pump.fun プログラムの履歴をスキャンし、buy および sell 命令を検索します:
Pump.fun には、buy_exact_sol_in、buy_v2、sell_v2 などのバリエーションもあります。一致させるすべての命令名を指定してください。

1 つのトークンの購入と売却

あるトークンの Pump.fun 取引を取得するには、プログラムではなくトークンのミントアドレスをスキャンします。ミントの履歴にはそのトークンのアクティビティのみが含まれ、各購入または売却命令はミントをアカウントとして列挙するため、デフォルトの address スコープで一致します:
USDC トークンアカウントも関与するトークンのトランザクションだけを保持するには、transaction スコープで USDC を追加します。デフォルトの address スコープでは、USDC 残高がミントアドレスに属している必要があるため、何も一致しません:

2 つのプログラムにまたがるウォレットの取引

複数のプログラムを指定すると、そのいずれかの呼び出しに一致させることができます。このリクエストは、ウォレットの Pump.fun と PumpSwap の取引を署名のみで返します:

時間範囲内のウォレットの USDC アクティビティ

2025 年中に USDC に関与したトランザクションを、ウォレットの履歴からスキャンします。tokenAccounts: "balanceChanged" には、ウォレットの USDC トークンアカウントのみに関与した転送も含まれます:
一致するトランザクションの件数だけを取得するには、"returnShape": "count" を追加します。

ウォレットの SOL の移動

2025 年中に、ウォレットが支払った手数料以外で SOL 残高を変化させたトランザクションをスキャンします。これには、転送命令なしでプログラムが支払った SOL も含まれます:

ページネーションと停止理由

scan.stoppedOn は、リクエストが終了した理由を示します: scan.scannedThrough は、最後にスキャンしたトランザクションのスロットとブロック時刻を示すため、長い履歴の進捗状況を報告できます。 まれな命令を検索するスキャンでは、一致が見つからないまま予算を使い切ることがあります。その場合、レスポンスの data 配列は空ですが、paginationToken は返されます。そのため、スキャンを続けてください:
このループは、履歴をすべて処理するまでスキャンを続けます:
scan-pumpfun-trades.js
可能な限り対象を絞ったアドレスをスキャンしてください。アドレス履歴内のすべてのトランザクションが予算に加算されるため、無関係なトランザクションが少ないアドレスほど、各リクエストで多くの一致を検出できます。

クレジット

各スキャンのコストは、10 クレジットに、スキャンした履歴ページごとに 1 クレジットを加えた値です。1 ページには最大 1,000 件のトランザクションが含まれるため、デフォルト予算の 10,000 件のトランザクションをスキャンする場合、コストは最大 20 クレジットです。期限によって中断されたページはスキャンされず、課金もされません。 各レスポンスの scan.creditsCharged に課金額が記載されます。プランの料金については、クレジットを参照してください。

エラー

リクエストレベルのエラーでは、{"error": "limit must be between 1 and 100"} などの error メッセージを含む JSON ボディが返されます。includeRawTransaction(rawTransaction を使用してください)のような不明なフィールドを含むボディ、または mints に { "mint": "..." } オブジェクトではなく単なる文字列を指定したボディでは、{"error": "invalid request payload"} が返されます。

リクエストパラメーター

string
必須
履歴をスキャンするアドレスです。
object
必須
トランザクションが満たす必要のある一致条件です。programs、mints、またはその両方を設定します。両方を設定した場合、トランザクションは両方に一致する必要があります。
array
照合するプログラムです。最大 20 個で、同じプログラムを複数回指定することはできません。プログラムの scope 内で、トップレベルまたは内部(CPI)に対象プログラムのいずれかの命令がある場合、トランザクションは一致します。
string
必須
プログラムアドレスです。
array
プログラムの任意の IDL バージョンにある命令名を、IDL の表記または snake_case で指定します。最大 50 件です。discriminators と組み合わせることができます。
array
命令データのプレフィックスです。それぞれ 1~8 バイトの 16 進数エンコード値で、オプションの 0x プレフィックスを使用できます。最大 50 件です。instructions と組み合わせることができます。
string
デフォルト:"address"
カウントするプログラム命令を指定します。address は、アカウントの 1 つが 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
1 回のリクエストでスキャンする履歴量の上限です。
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
リクエストを評価できる最小スロットです。
string
デフォルト:"none"
各成功結果で rawTransaction として返される元の Solana トランザクションのエンコーディングです。getTransaction 形式で返されます。transactions 形式にのみ適用されます。
  • none
  • json
  • jsonParsed
  • base64
object
スロット比較の境界です。各境界はオプションです。
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

1 回のリクエストでスキャンする履歴量の上限です。

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

成功した各結果で rawTransaction として返される、元の Solana トランザクションのエンコーディングです。形式は getTransaction と同じです。transactions 形式にのみ適用されます。

利用可能なオプション:
none,
json,
jsonParsed,
base64
slot
object

スロットの比較境界です。各境界は省略可能です。

time
object

Unix 秒単位のブロック時間の比較境界です。各境界は省略可能です。

レスポンス

要求された returnShape 形式の一致結果とスキャンの概要です。部分的な結果でもステータスは 200 です。paginationToken が返される間は、それを使用して処理を続行してください。

要求された returnShape 形式の一致結果とスキャンの概要です。

data
object

署名ごとのパーサー結果。

paginationToken
string

次のスキャンを続行する位置を示すカーソルです。スキャンが履歴または範囲の末尾に到達した場合は存在しません。

scan
object

スキャンがどこまで進み、なぜ停止したかを示します。