Зачем выполнять миграцию?
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 и перепишет их.Дальнейшие действия
Parsed Events Quickstart
Разберите первую транзакцию, получите историю адреса и настройте постраничный просмотр результатов.
Parsed Response
Справочник по полям разобранных транзакций, переводов и инструкций.
Parsed Streams
Такое же декодирование в реальном времени через WebSocket с фильтрацией на стороне сервера.
getTransactionsForAddress
История необработанных транзакций с поддержкой аккаунтов токенов и фильтрами на стороне сервера.