Представляем Parsed Events Scan API

Сканирование по инструкциям программ Solana

Следующий запрос сканирует историю программы Pump.fun и возвращает разобранные транзакции с инструкцией buy или sell:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["buy", "sell"]
        }
      ]
    },
    "limit": 100
  }'

С помощью этого запроса демоинструмент Parsed Events Scan просканировал 261 запись и нашел 100 совпадений. Он вернул 100 последних событий за 182 мс, потратив всего 11 кредитов:

Названия инструкций могут использовать написание из любой известной версии IDL программы или формат snake_case. Parsed Events Scan API проверяет как инструкции верхнего уровня, так и внутренние инструкции, вызванные через межпрограммные вызовы (CPI).

У программ часто бывает несколько версий одного действия. Например, IDL Pump.fun содержит инструкции buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell и sell_v2. Scan API позволяет перечислить все названия инструкций, по которым нужно искать совпадения.

Покупки и продажи составляют значительную часть активности Pump.fun, поэтому совпадения находятся довольно быстро. Scan позволяет сэкономить больше, если нужная активность встречается редко. Например, комиссии создателей составляют лишь небольшую долю транзакций программы:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["collect_creator_fee"]
        }
      ]
    },
    "limit": 10
  }'

При поиске десяти последних запросов через демоинструмент Parsed Events Scan видно, что он просканировал 3 402 транзакции за 182 мс, а запрос обошелся в 14 кредитов:

Аналогичный вызов getTransactionsForAddress обошелся бы в 350 кредитов — в 25 раз дороже эндпоинта сканирования.

Что делать, если у программы Solana нет IDL с именованными инструкциями?

Чтобы использовать Parsed Events Scan API с программами Solana без IDL, можно искать совпадения по префиксам данных инструкций.

Каждый дискриминатор может содержать от одного до восьми байтов в шестнадцатеричной кодировке. Для одной программы можно сочетать названия и дискриминаторы: инструкция считается совпадением по любому из них. Например:

{
  "match": {
    "programs": [
      {
        "programId": "<PROGRAM_ADDRESS>",
        "discriminators": ["0x66063d1201daebea"]
      }
    ]
  }
}

Одновременное сканирование нескольких программ Solana

В одном запросе Parsed Events Scan API можно указать до 20 программ. Транзакция считается совпадением, если вызывает любую из них.

Например, этот запрос за одно сканирование ищет сделки кошелька в Jupiter, DFlow и Pump.fun:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"]
      },
      { "programId": "DF1ow4tspfHX9JwWJsAb9epbkA8hmpSEAtxXy1V27QBH" },
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Сканирование по выпуску токена

Scan API также может находить транзакции, затрагивающие заданный выпуск токена. Для этого он проверяет балансы токенов до и после каждой транзакции по адресу выпуска. По умолчанию учитываются только балансы, принадлежащие сканируемому адресу.

При сканировании кошелька по токену задайте для tokenAccounts значение balanceChanged. Во многих случаях входящий перевод токена затрагивает только токен-аккаунт кошелька, но не сам кошелек. Поэтому по умолчанию такие транзакции отсутствуют в истории кошелька.

Например, этот запрос находит активность Ansem с wSOL за сентябрь 2026 года:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "<ANSEM_WALLET_ADDRESS>",
    "match": {
      "mints": [{ "mint": "So11111111111111111111111111111111111111112" }]
    },
    "tokenAccounts": "balanceChanged",
    "time": {
      "gte": 1788220800,
      "lte": 1790812800
    }
  }'

Scan API нашел 53 совпадения, просканировав в общей сложности 7 555 транзакций:

Сочетание программ и выпусков

Разработчики могут задать одновременно programs и mints, чтобы сузить результаты. При их сочетании транзакция должна соответствовать обоим критериям. Однако для ограничения активности программы одним токеном сканируемый адрес важнее фильтров.

Например, чтобы найти все сделки Pump.fun с заданным токеном, сканируйте адрес выпуска токена, а не программу Pump.fun. В каждой покупке или продаже выпуск указан как аккаунт, поэтому совпадение находится по умолчанию:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

История выпуска содержит активность только этого токена, а история программы — сделки со всеми токенами. Поэтому сканирование программы израсходовало бы бюджет на посторонние транзакции.

Выбор области сопоставления

По умолчанию инструкции программы и балансы выпуска токена учитываются только в том случае, если они связаны со сканируемым адресом. Баланс токена связан с адресом, если адрес владеет токен-аккаунтом или является выпуском этого баланса. Инструкция связана с адресом в следующих случаях:

• Один из ее аккаунтов является этим адресом
• Один из ее аккаунтов — токен-аккаунт, принадлежащий этому адресу
• Адрес является выпуском, а один из аккаунтов инструкции — токен-аккаунт этого выпуска
• Адрес является вызываемой программой

Задайте "scope": "transaction" для программы или выпуска, чтобы учитывать их в любом месте транзакции. Используйте эту настройку, если адрес только оплачивает комиссию, выполняет мультисиг-транзакцию или не входит в аккаунты сопоставляемой инструкции.

Например, этот запрос находит транзакции токена, в которых также перемещался USDC. При области по умолчанию балансы USDC должны были бы принадлежать адресу выпуска, поэтому совпадений не было бы:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "mints": [
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "scope": "transaction" }
    ]
  },
  "returnShape": "signatures"
}

Для программ доступна та же область сопоставления. Этот запрос находит свопы Jupiter, комиссии за которые оплатил ретранслятор.

Ретранслятор только подписывает транзакции как плательщик комиссии, поэтому он не входит в аккаунты инструкции маршрута. В области по умолчанию ни одна из этих транзакций не совпала бы:

{
  "address": "<RELAYER_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"],
        "scope": "transaction"
      }
    ]
  },
  "returnShape": "signatures"
}

Та же логика применяется к участнику мультисига, который исполняет предложение. Выполняемая мультисигом инструкция работает с аккаунтами хранилища, а не участника. Поэтому для их поиска в истории участника нужна область transaction.

Отслеживание нативного SOL

У нативного SOL нет балансов токенов, поэтому при сканировании сопоставление выполняется по лампортам.

Передайте выпуск нативного SOL (So11111111111111111111111111111111111111111), который отличается от обернутого SOL. Транзакция считается совпадением, если баланс SOL сканируемого адреса изменился без учета уплаченной им комиссии:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "mints": [{ "mint": "So11111111111111111111111111111111111111111" }]
  },
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Так можно обнаружить SOL, выплаченный программой без инструкции перевода, например при продаже на Pump.fun. Также обнаруживаются сопутствующие перемещения, такие как чаевые Jito и арендная плата, уплаченная за аккаунты или возвращенная с них.

Получение разобранных транзакций, подписей или количества

returnShape определяет содержимое ответа для совпадений:

Например, этот запрос подсчитывает покупки трейдера на Pump.fun за сентябрь 2026 года, не возвращая транзакции:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2"]
      }
    ]
  },
  "returnShape": "count",
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

При подсчете signatures и count игнорируют limit и охватывают все совпадения в диапазоне, просканированном запросом. Чтобы подсчитать данные за длительный период, продолжайте постраничный просмотр и суммируйте scan.matchedTransactions.

Все три формата стоят одинаково.

Управление объемом истории, сканируемой каждым запросом

За один запрос можно просканировать до 10 000 транзакций и получить до 100 совпадений.

Поле budget.maxScannedTransactions управляет этим ограничением. По умолчанию оно равно 10 000. Поле limit определяет, сколько совпадений вернет эндпоинт. Оно принимает значения от 1 до 100, а значение по умолчанию — 100.

Эти параметры разделены, поскольку совпадения могут быть редкими. Иными словами, запрос может просканировать тысячи транзакций и вернуть лишь несколько совпадений.

По умолчанию запросы сканирования включают только успешные транзакции.

Задайте для status значение failed или any, чтобы включить неудачные транзакции. Они возвращаются с декодированными ошибками программы, если эти ошибки определены в IDL программы.

Сводки сканирования

Каждый ответ содержит сводку scan:

{
  "data": [],
  "paginationToken": "460903064:422",
  "scan": {
    "stoppedOn": "budget",
    "scannedTransactions": 2000,
    "matchedTransactions": 0,
    "scannedThrough": {
      "slot": 460903064,
      "blockTime": 1792856105
    },
    "creditsCharged": 12
  }
}

Сводка сообщает:

• Почему сканирование остановилось
• Сколько транзакций было просканировано
• Сколько транзакций совпало
• Последние просканированные слот и время блока
• Сколько кредитов израсходовал запрос

Как работает пагинация сканирования

Когда сканирование останавливается, поле scan.stoppedOn указывает причину:

• windowEnd: сканирование достигло конца истории или окна
• limit: ответ содержит запрошенное количество совпадений
• budget: запрос исчерпал бюджет на сканирование транзакций
• deadline: запрос достиг ограничения по времени

Если ответ содержит paginationToken, передайте этот токен в следующем запросе и продолжайте, даже если текущий массив data пуст. Пустой результат может означать, что запрос исчерпал бюджет до обнаружения совпадения, а не то, что совпадений дальше нет.

Например, этот цикл собирает сделки Pump.fun за последний час.

Обратите внимание: граница time и лимит запросов не позволяют циклу пройти всю историю:

const PUMP_PROGRAM = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const ONE_HOUR_AGO = Math.floor(Date.now() / 1000) - 3600;
const MAX_REQUESTS = 50;

let paginationToken;
let requests = 0;

async function scanHistory() {
  const response = await fetch(
    `https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=${process.env.HELIUS_API_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        address: PUMP_PROGRAM,
        match: {
          programs: [{ programId: PUMP_PROGRAM, instructions: ["buy", "sell"] }],
        },
        time: { gte: ONE_HOUR_AGO },
        limit: 100,
        ...(paginationToken && { paginationToken }),
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

do {
  const page = await scanHistory();
  requests++;

  for (const transaction of page.data) {
    console.log(transaction.signature);
  }

  paginationToken = page.paginationToken;
} while (paginationToken && requests < MAX_REQUESTS);

Разобранные результаты без клиентского конвейера

Каждый элемент в data использует тот же формат TransactionResult, что и эндпоинт разбора транзакций Parsed Events. Результаты могут включать декодированные инструкции, переводы, изменения аккаунтов, события, сводки транзакций и разобранные данные конкретных протоколов, если они доступны. Если приложению также нужны исходные данные транзакции Solana, задайте для rawTransaction значение "json", "jsonParsed" или "base64".

Основное различие заключается в том, где выполняется обработка истории.

Приложение один раз задает параметры поиска, а Parsed Events Scan API обрабатывает пагинацию истории, сопоставление и разбор, после чего возвращает нужные транзакции.

Используйте новейшие SDK Helius

Наши SDK для TypeScript и Rust поддерживают Parsed Events API и новый эндпоинт сканирования.

В SDK для TypeScript сканирование доступно как helius.parsedEvents.scan(). Тип ответа соответствует переданному returnShape:

const { scan } = await helius.parsedEvents.scan({
  address: "<WALLET_ADDRESS>",
  match: {
    programs: [{ programId: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", instructions: ["buy", "sell"] }],
  },
  returnShape: "count",
});

console.log(scan.matchedTransactions, scan.stoppedOn);

В SDK для Rust также доступны scan, scan_signatures и scan_count в helius.parsed_events(). Все они принимают один и тот же ScanRequest.

Стоимость Parsed Events Scan API

Каждый запрос Parsed Events Scan API стоит 10 кредитов плюс 1 кредит за каждую просканированную страницу истории. Страница истории содержит до 1 000 транзакций.

Например, запрос со стандартным бюджетом в 10 000 транзакций стоит не более 20 кредитов. Точная стоимость указывается в ответе в scan.creditsCharged.

Для сравнения: сканирование стоит в десять раз дешевле постраничного просмотра той же истории через getTransactionsForAddress, который обходится в 100 кредитов за страницу (до 1 000 транзакций).

Контроль использования

Чтобы контролировать использование, выбирайте максимально узкий подходящий адрес и по возможности добавляйте границы по слотам или времени. Чем меньше посторонних транзакций, тем больше полезных совпадений в каждом запросе.

Замена Enhanced Transactions API на Parsed Events API

Enhanced Transactions API остается доступным в режиме сопровождения, но больше не получает новые типы парсеров и функции. Его преемник Parsed Events использует каталог IDL Helius для декодирования инструкций тысяч программ Solana. Если вы еще этого не сделали, перейдите на Parsed Events API.

В чем разница?

Enhanced Transactions API распределяет активность по фиксированному набору типов транзакций, таких как свопы, переводы и продажи NFT. Parsed Events Scan API поддерживает более точный поиск по инструкции программы, необработанному дискриминатору, выпуску токена или сочетанию этих критериев. Helius применяет фильтры при сканировании истории адреса и разбирает только совпавшие транзакции.

Parsed Events API предоставляет разработчикам более широкий охват программ и больше контроля над запросами к истории без необходимости поддерживать клиентский сканер.

Начало работы

Используйте Parsed Events Scan API, если знаете, какая ончейн-активность вам нужна, но не хотите создавать и поддерживать клиентский сканер истории. Полная схема запроса, поля ответа, ограничения, ошибки и дополнительные примеры приведены в справочнике Scan Transaction History API.

Чтобы продолжить знакомство с возможностями Scan API, откройте новый инструмент Scan в панели управления Helius. Попробуйте сканировать адреса по программам и выпускам, а также применять фильтры.