Skip to main content

Зачем выполнять миграцию?

API Enhanced Transactions — это устаревший продукт в режиме обслуживания: он по-прежнему работает, но больше не получает новые типы парсеров и функциональные обновления. Его преемник — Parsed Events, который декодирует инструкции с помощью каталога IDL, также используемого в Parsed Streams. Разница заключается в способе декодирования транзакций. Enhanced Transactions классифицирует транзакцию по одному из типов событий из фиксированного списка (TRANSFER, SWAP, NFT_SALE, …) и возвращает заранее сформированную сводку для известных ему типов. Parsed Events декодирует каждую инструкцию на основе собственного IDL программы — поддерживается более 3 600 программ — в именованные аргументы и именованные аккаунты, а затем формирует на их основе сводку: Parsed Events общедоступен на всех тарифах, включая Free, и расходует 10 кредитов на запрос. Enhanced Transactions продолжает работать в режиме обслуживания, поэтому вы можете выполнять миграцию в удобном темпе.

Сопоставление конечных точек

Оба метода Parsed Events используют запросы POST к https://mainnet.helius-rpc.com и проходят аутентификацию с помощью того же параметра запроса api-key, который вы уже используете: В конечной точке истории все входные данные переносятся из параметров строки запроса в тело JSON. Тела запросов отклоняют неизвестные поля, поэтому опечатки приводят к явной ошибке, а не молча игнорируются.

До и после

Одна и та же задача — получение разобранной истории кошелька — в обоих API:

Сопоставление параметров

Разбор транзакций

POST /v0/transactions → POST /v1/parsed-events/transactions Новая возможность без аналога в старом API: includeRawTransaction возвращает исходные данные транзакции Solana вместе с результатом разбора.

История транзакций

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Каждый параметр запроса становится полем тела JSON: При этом меняются три значения по умолчанию:
  • Значение limit по умолчанию теперь равно 100 вместо 10.
  • Значение commitment по умолчанию теперь равно confirmed вместо finalized; processed не поддерживается.
  • sortOrder сохраняет те же значения asc/desc, при этом значением по умолчанию остается desc.
Для постраничного просмотра используйте paginationToken из предыдущего ответа вместо beforeSignature — см. раздел Упростите пагинацию ниже. У старого параметра type нет аналога в Parsed Events: фильтрация по типу транзакции на стороне сервера отсутствует. Фильтруйте на стороне клиента по parsed.summary.type (swap, transfer, add_liquidity, …) или непосредственно по декодированным инструкциям, что точнее старых фиксированных типов. Для потоков реального времени с фильтрацией по типу Parsed Streams выполняет фильтрацию на стороне сервера на уровне инструкций.

Сопоставление полей ответа

Enhanced Transactions возвращает плоский массив дополненных транзакций. Parsed Events помещает каждый результат в оболочку — { signature, parserStatus, parsed }, — а в ответах с историей массив дополнительно помещается в объект страницы с paginationToken. Разобранные поля сопоставляются следующим образом: Главное изменение — новое поле без аналога в старом API: parsed.instructions[] содержит все инструкции верхнего уровня и внутренние инструкции в порядке выполнения, а имена decoded.args и decoded.accounts берутся из IDL программы. Enhanced Transactions предоставлял одну сводку событий на транзакцию, а Parsed Events предоставляет и сводку, и полный список декодированных инструкций. Описание всех полей см. в разделе Разобранный ответ.

Этапы миграции

1

Swap the endpoints

Направьте вызовы Parse Transactions на POST /v1/parsed-events/transactions, а вызовы истории — на POST /v1/parsed-events/transaction-history. Используются тот же хост и тот же параметр запроса api-key. Запросы истории меняются с GET с параметрами запроса на POST с телом JSON — перенесите каждый параметр согласно сопоставлению выше.
2

Update the response handling

Извлеките данные из новой оболочки: проверьте parserStatus === "OK", затем считывайте поля из parsed, а не с верхнего уровня. Переименуйте timestamp в blockTime, считывайте description и type из summary (предусмотрев проверку на null) и делите rawTokenAmount на 10^decimals там, где старый код считывал tokenAmount.
3

Replace type filtering

Там, где старый код передавал type=..., фильтруйте возвращенные элементы на стороне клиента по parsed.summary.type или parsed.instructions[]. Например, условие «инструкции, в которых programId — Jupiter, а instructionName — route» заменяет type=SWAP условием, которое можно фактически проверить. Если фильтр по типу использовался для формирования потока реального времени, переведите этот потребитель на Parsed Streams, который выполняет фильтрацию на стороне сервера на уровне инструкций.
4

Simplify pagination

Замените цикл с курсором before-signature на paginationToken:
Цикл завершается, когда paginationToken отсутствует. Старые ошибки поиска во время выполнения (“Failed to find events within the search period”) и обработка подписей продолжения полностью исчезают — удалите этот код.
5

Verify against the old output

Для тестового адреса получите одну и ту же страницу из обоих API и сравните наборы подписей, комиссии и суммы переводов. Затем разверните изменения и удалите старую ветвь кода. Enhanced Transactions продолжает работать во время миграции — обязательной даты отключения нет.

Различия в поведении, которые следует проверить

  • Уровни подтверждения по умолчанию. Для истории по умолчанию используется confirmed, тогда как старая конечная точка по умолчанию использовала finalized. Явно передайте commitment: "finalized", если ваш конвейер зависит от окончательности. processed не поддерживается.
  • Ошибки отдельных элементов. Подпись, которую невозможно разобрать, больше не приводит к ошибке всего запроса — она возвращается как элемент с parserStatus: "ERROR" и parserError. Обрабатывайте ошибку для каждого элемента, а не для всего запроса.
  • Охват сводки. summary имеет значение null для транзакций без распознанного действия на уровне транзакции. В таком случае старый API возвращал type: "UNKNOWN"; новый API по-прежнему предоставляет все декодированные инструкции для дальнейшей обработки.
  • Доступ и стоимость. Parsed Events доступен на всех тарифах и расходует 10 кредитов на запрос вместо 100 для Enhanced Transactions.

Поручите миграцию ИИ-агенту

Если вы используете Claude Code, Cursor или другого агента для написания кода, вставьте приведенный ниже промпт в сеанс агента для вашего репозитория. Агент найдет места вызова Enhanced Transactions и перепишет их.
Промпт самодостаточен — агенту не нужен доступ к этой странице. Документацию для агентов, поиск MCP и навыки см. в разделе Helius для ИИ-агентов.

Дальнейшие действия

Parsed Events Quickstart

Разберите первую транзакцию, получите историю адреса и настройте постраничный просмотр результатов.

Parsed Response

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

Parsed Streams

Такое же декодирование в реальном времени через WebSocket с фильтрацией на стороне сервера.

getTransactionsForAddress

История необработанных транзакций с поддержкой аккаунтов токенов и фильтрами на стороне сервера.