Перейти к основному содержанию
POST
Тело запроса, схема ответа и примеры на этой странице создаются на основе определения OpenAPI. Scan обходит историю одного адреса, сохраняет транзакции, соответствующие критериям match, и разбирает только их. Используйте его вместо постраничного обхода разобранной истории транзакций и фильтрации на стороне клиента. По умолчанию каждый элемент в data имеет ту же структуру TransactionResult, которую возвращает разбор транзакций. Задайте returnShape, чтобы получить только подписи совпадений или только их количество. Ответ также содержит сводку scan, в которой указано, насколько далеко продвинулось сканирование и почему оно остановилось.

Как работает Scan

  1. Scan получает историю адреса страницами до 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 нет балансов токенов, поэтому Scan сопоставляет его по лампортам. Используйте минт нативного SOL So11111111111111111111111111111111111111111 (обернутый SOL — So11111111111111111111111111111111111111112):
  • При области address транзакция считается совпадением, если изменилось количество лампортов сканируемого адреса.
  • При области transaction она считается совпадением, если изменилось количество лампортов любого счета.
Комиссия, взимаемая с плательщика комиссии, не учитывается. Каждый счет сравнивается отдельно, поэтому лампорты, которые покидают счет и возвращаются на него в той же транзакции, не учитываются. Сопоставление с нативным SOL обнаруживает SOL, выплаченный программой без инструкции перевода, например при продаже на Pump.fun. Оно также обнаруживает сопутствующие перемещения средств, например чаевые Jito и арендную плату, уплаченную за счета или возвращенную с них.

Область совпадения

Для каждой программы и каждого минта задается scope: Используйте область transaction, когда сканируемый адрес присутствует в транзакции, но отсутствует в сопоставляемой инструкции или балансе. Например, адрес только оплачивает комиссию, выполняет транзакцию с мультиподписью или отсутствует в CPI события Anchor. Для сканирования минта токена в поиске транзакций, которые также содержат USDC, требуется область transaction для записи USDC. Владелец счета токена определяется по owner, записанному для каждого баланса токена. Более старые транзакции, в которых он не записан, соответствуют области address только непосредственно для address.

Форматы возвращаемых данных

returnShape определяет, какие данные о совпадениях содержит ответ: signatures и count игнорируют limit и rawTransaction. Они возвращают все совпадения в просканированном запросом диапазоне, поэтому останавливаются только при windowEnd, budget или deadline. Чтобы подсчитать совпадения во всей истории, продолжайте вызывать метод с paginationToken и суммируйте scan.matchedTransactions. Каждый элемент в data с returnShape: "signatures" выглядит так:
Все три формата имеют одинаковую стоимость, поскольку количество кредитов зависит от числа просканированных страниц истории, а не от возвращаемых данных.

Примеры запросов

Покупки и продажи 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 кошелька за период времени

Просканируйте историю кошелька в поиске транзакций, затрагивавших USDC в течение 2025 года. tokenAccounts: "balanceChanged" включает переводы, которые затрагивали только счет токена USDC кошелька:
Чтобы получить только количество совпавших транзакций, добавьте "returnShape": "count".

Перемещения SOL в кошельке

Просканируйте кошелек в поиске транзакций, которые изменили его баланс SOL в течение 2025 года, не считая уплаченной им комиссии. Сюда входит SOL, выплаченный программой без инструкции перевода:

Пагинация и причины остановки

scan.stoppedOn указывает, почему запрос завершился: scan.scannedThrough содержит слот и время блока последней просканированной транзакции, что позволяет сообщать о ходе обработки длинных историй. При поиске редкой инструкции Scan может израсходовать весь бюджет, не найдя совпадений. В этом случае ответ содержит пустой массив data, но все равно возвращает paginationToken, поэтому продолжайте сканирование:
Этот цикл продолжает сканирование до исчерпания истории:
scan-pumpfun-trades.js
Сканируйте наиболее узкий из возможных адресов. Каждая транзакция в истории адреса учитывается в бюджете, поэтому чем меньше у адреса несвязанных транзакций, тем больше совпадений находит каждый запрос.

Кредиты

Каждое сканирование стоит 10 кредитов плюс 1 кредит за каждую просканированную страницу истории. Страница содержит до 1 000 транзакций, поэтому сканирование с бюджетом по умолчанию в 10 000 транзакций стоит не более 20 кредитов. Страница, обработка которой прервана по истечении срока, не считается просканированной и не тарифицируется. В каждом ответе стоимость указывается в scan.creditsCharged. Стоимость тарифных планов приведена в разделе Кредиты.

Ошибки

При ошибках на уровне запроса возвращается тело JSON с сообщением error, например {"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 сопоставляется по изменениям количества лампортов вместо балансов токенов, без учета комиссии.
string
по умолчанию:"address"
Какие балансы токенов минта учитывать. address учитывает только балансы, для которых счет токена равен address или принадлежит ему либо минт равен address. Для нативного SOL учитываются только изменения количества лампортов address. transaction учитывает любой баланс минта в транзакции. Для нативного SOL учитывается изменение количества лампортов любого счета.
  • address
  • transaction
string
по умолчанию:"transactions"
Данные, которые ответ содержит для совпадений: transactions (разобранные совпадения в data, не более limit), signatures (signature, slot, transactionIndex и blockTime для каждого совпадения в data) или 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
Минимальный слот, в котором может быть обработан запрос.
string
по умолчанию:"none"
Кодировка исходной транзакции Solana, возвращаемой как rawTransaction для каждого успешного результата в структуре 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 (signature, slot, transactionIndex и blockTime для каждого совпадения в data) или 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

Насколько далеко продвинулось сканирование и почему оно остановилось.