> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Переход с Enhanced Transactions на Parsed Events

> Перейдите с API Enhanced Transactions на Parsed Events: сопоставление конечных точек, параметров и полей ответа, код до и после миграции, а также промпт для ИИ-агента.

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

[API Enhanced Transactions](/docs/ru/enhanced-transactions/overview) — это устаревший продукт в режиме обслуживания: он по-прежнему работает, но больше не получает новые типы парсеров и функциональные обновления. Его преемник — [Parsed Events](/docs/ru/parsed-events), который декодирует инструкции с помощью каталога IDL, также используемого в [Parsed Streams](/docs/ru/parsed-streams).

Разница заключается в способе декодирования транзакций. Enhanced Transactions классифицирует транзакцию по одному из типов событий из фиксированного списка (`TRANSFER`, `SWAP`, `NFT_SALE`, ...) и возвращает заранее сформированную сводку для известных ему типов. Parsed Events декодирует **каждую инструкцию** на основе собственного IDL программы — поддерживается более 3 600 программ — в именованные аргументы и именованные аккаунты, а затем формирует на их основе сводку:

| | Enhanced Transactions | Parsed Events |
| - | - | - |
| Модель декодирования | Фиксированные типы событий, отобранные парсеры | Каталог IDL, более 3 600 программ |
| Детализация инструкций | Только сводка событий | Каждая инструкция, декодированные аргументы и аккаунты, включая CPI |
| Программы без парсера | Универсальный вывод `UNKNOWN` | Для каждой инструкции всегда возвращаются необработанные данные и аккаунты |
| Кредитов на запрос | 100 | 10 |
| Пагинация | Курсоры подписей, необходимость обработки ошибок поиска во время выполнения | `paginationToken` (курсоры подписей также доступны) |
| Декодированные ошибки программ | Нет | Да (`decodedError`) |
| Необработанные данные транзакции | Нет | Необязательно (`includeRawTransaction`) |
| Статус | Устаревший продукт, режим обслуживания | Общедоступный продукт, активная разработка |

Parsed Events общедоступен на всех тарифах, включая Free, и расходует 10 кредитов на запрос. Enhanced Transactions продолжает работать в режиме обслуживания, поэтому вы можете выполнять миграцию в удобном темпе.

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

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

| Enhanced Transactions | Parsed Events |
| - | - |
| `POST /v0/transactions` | `POST /v1/parsed-events/transactions` |
| `GET /v0/addresses/{address}/transactions` | `POST /v1/parsed-events/transaction-history` |

В конечной точке истории все входные данные переносятся из параметров строки запроса в тело JSON. Тела запросов отклоняют неизвестные поля, поэтому опечатки приводят к явной ошибке, а не молча игнорируются.

## До и после

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

<CodeGroup>
  ```javascript Before (Enhanced Transactions) theme={"system"}
  const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
  const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;

  const response = await fetch(url);
  const transactions = await response.json(); // flat array of enriched transactions

  for (const tx of transactions) {
    console.log(tx.signature, tx.type, tx.description);
  }
  ```

  ```javascript After (Parsed Events) theme={"system"}
  const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
      limit: 100,
      sortOrder: "desc",
    }),
  });
  const page = await response.json(); // { data: [...], paginationToken }

  for (const item of page.data) {
    if (item.parserStatus !== "OK") continue;
    console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
  }
  ```
</CodeGroup>

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

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

`POST /v0/transactions` → `POST /v1/parsed-events/transactions`

| Старый | Новый |
| - | - |
| `transactions` (тело) | `transactions` — без изменений |
| `commitment` | `commitment` — `confirmed` (по умолчанию) или `finalized`; `processed` не поддерживается |

Новая возможность без аналога в старом API: `includeRawTransaction` возвращает исходные данные транзакции Solana вместе с результатом разбора.

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

`GET /v0/addresses/{address}/transactions` → `POST /v1/parsed-events/transaction-history`. Каждый параметр запроса становится полем тела JSON:

| Старый параметр запроса | Новое поле тела |
| - | - |
| `{address}` (путь) | `address` |
| `limit` | `limit` |
| `before-signature` | `beforeSignature` |
| `after-signature` | `afterSignature` |
| `sort-order` | `sortOrder` |
| `commitment` | `commitment` |
| `gt-time` | `time.gt` |
| `gte-time` | `time.gte` |
| `lt-time` | `time.lt` |
| `lte-time` | `time.lte` |
| `gt-slot` | `slot.gt` |
| `gte-slot` | `slot.gte` |
| `lt-slot` | `slot.lt` |
| `lte-slot` | `slot.lte` |

При этом меняются три значения по умолчанию:

* Значение `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](/docs/ru/parsed-streams) выполняет фильтрацию на стороне сервера на уровне инструкций.

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

Enhanced Transactions возвращает плоский массив дополненных транзакций. Parsed Events помещает каждый результат в оболочку — `{ signature, parserStatus, parsed }`, — а в ответах с историей массив дополнительно помещается в объект страницы с `paginationToken`. Разобранные поля сопоставляются следующим образом:

| Старое поле | Новое поле |
| - | - |
| `description` | `parsed.summary.description` — `summary` имеет значение `null`, если сводка уровня транзакции неприменима |
| `type` (`TRANSFER`, `SWAP`, ...) | `parsed.summary.type` (`transfer`, `swap`, ...) — меньший набор; сведения по каждой инструкции перенесены в `parsed.instructions[]` |
| `source` (`SYSTEM_PROGRAM`, `JUPITER`, ...) | `parsed.summary.parsedData.protocol` или `instructions[].programName` для каждой инструкции |
| `events` (`events.swap`, `events.nft`, ...) | `parsed.summary.parsedData` — структурированные данные с ключом по типу сводки |
| `fee` / `feePayer` | `parsed.fee` / `parsed.feePayer` — без изменений |
| `signature` | `signature` (на уровне оболочки) |
| `slot` | `parsed.slot` |
| `timestamp` | `parsed.blockTime` |
| `transactionError` | `parsed.error` и `parsed.decodedError` с собственным именем ошибки программы, если доступны метаданные |
| `nativeTransfers` | `parsed.nativeTransfers` — та же структура (`fromUserAccount`, `toUserAccount`, `amount` в лампортах) |
| `tokenTransfers` | `parsed.tokenTransfers` — те же поля аккаунта, но `tokenAmount` (предварительно масштабированное десятичное значение) заменяется на `rawTokenAmount` (необработанное целое число) и `decimals` |

Главное изменение — новое поле без аналога в старом API: `parsed.instructions[]` содержит все инструкции верхнего уровня и внутренние инструкции в порядке выполнения, а имена `decoded.args` и `decoded.accounts` берутся из IDL программы. Enhanced Transactions предоставлял одну сводку событий на транзакцию, а Parsed Events предоставляет и сводку, *и* полный список декодированных инструкций. Описание всех полей см. в разделе [Разобранный ответ](/docs/ru/parsed-events/parsed-response).

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

<Steps>
  <Step title="Swap the endpoints">
    Направьте вызовы Parse Transactions на `POST /v1/parsed-events/transactions`, а вызовы истории — на `POST /v1/parsed-events/transaction-history`. Используются тот же хост и тот же параметр запроса `api-key`. Запросы истории меняются с `GET` с параметрами запроса на `POST` с телом JSON — перенесите каждый параметр согласно [сопоставлению выше](#сопоставление-параметров).
  </Step>

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

  <Step title="Replace type filtering">
    Там, где старый код передавал `type=...`, фильтруйте возвращенные элементы на стороне клиента по `parsed.summary.type` или `parsed.instructions[]`. Например, условие «инструкции, в которых `programId` — Jupiter, а `instructionName` — `route`» заменяет `type=SWAP` условием, которое можно фактически проверить. Если фильтр по типу использовался для формирования потока реального времени, переведите этот потребитель на [Parsed Streams](/docs/ru/parsed-streams), который выполняет фильтрацию на стороне сервера на уровне инструкций.
  </Step>

  <Step title="Simplify pagination">
    Замените цикл с курсором `before-signature` на `paginationToken`:

    ```javascript theme={"system"}
    let paginationToken = null;
    const results = [];

    do {
      const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          address: "YOUR_ADDRESS_HERE",
          limit: 100,
          ...(paginationToken && { paginationToken }),
        }),
      });
      const page = await response.json();
      results.push(...page.data);
      paginationToken = page.paginationToken;
    } while (paginationToken);
    ```

    Цикл завершается, когда `paginationToken` отсутствует. Старые ошибки поиска во время выполнения ("Failed to find events within the search period") и обработка подписей продолжения полностью исчезают — удалите этот код.
  </Step>

  <Step title="Verify against the old output">
    Для тестового адреса получите одну и ту же страницу из обоих API и сравните наборы подписей, комиссии и суммы переводов. Затем разверните изменения и удалите старую ветвь кода. Enhanced Transactions продолжает работать во время миграции — обязательной даты отключения нет.
  </Step>
</Steps>

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

* **Уровни подтверждения по умолчанию.** Для истории по умолчанию используется `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 и перепишет их.

```markdown theme={"system"}
Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.

## Background

Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md

## Step 1: Find the old call sites

Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses/<address>/transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
  handlers for the "Failed to find events within the search period" error

## Step 2: Rewrite each call site

Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
  ("confirmed" default or "finalized") and includeRawTransaction.

Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
  POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
  limit -> limit (default is now 100, not 10);
  before-signature -> beforeSignature (prefer paginationToken, see below);
  after-signature -> afterSignature; sort-order -> sortOrder;
  commitment -> commitment (default is now "confirmed", not "finalized";
  "processed" unsupported);
  gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
  gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no server-side equivalent: filter returned items client-side
  on parsed.summary?.type (lowercase: "swap", "transfer", ...) or on
  parsed.instructions[] (programId / instructionName).

Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
  parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
  parsed.summary?.description; type -> parsed.summary?.type;
  source -> parsed.summary?.parsedData?.protocol or
  parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
  rawTokenAmount (raw integer string/number) plus decimals — divide by
  10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
  paginationToken is present, passing it back in the next request body.
  Delete continuation-signature error handling for the old runtime type
  search — it no longer exists.

## Step 3: Constraints and cleanup

- Keep the same Helius API key and host; only paths, methods, bodies, and
  response handling change.
- Never hardcode an API key; keep reading it from the existing config or
  environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
  migration covers only the /v0/transactions and /v0/addresses REST calls.

## Step 4: Verify

- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
  (e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
  history for an address from both APIs — the old
  GET /v0/addresses/{address}/transactions and the new
  POST /v1/parsed-events/transaction-history — and prints whether the
  signature sets, fees, and native transfer amounts match, listing any
  differences. Read the API key from an environment variable and the address
  from a CLI argument.
- Tell the user how to run it, for example:
  HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs <address>
- Summarize every call site changed and flag any you were unsure about.
```

Промпт самодостаточен — агенту не нужен доступ к этой странице. Документацию для агентов, поиск MCP и навыки см. в разделе [Helius для ИИ-агентов](/docs/ru/agents/overview).

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

<CardGroup cols={2}>
  <Card title="Parsed Events Quickstart" icon="bolt" href="/docs/ru/parsed-events/quickstart">
    Разберите первую транзакцию, получите историю адреса и настройте постраничный просмотр результатов.
  </Card>

  <Card title="Parsed Response" icon="brackets-curly" href="/docs/ru/parsed-events/parsed-response">
    Справочник по полям разобранных транзакций, переводов и инструкций.
  </Card>

  <Card title="Parsed Streams" icon="tower-broadcast" href="/docs/ru/parsed-streams">
    Такое же декодирование в реальном времени через WebSocket с фильтрацией на стороне сервера.
  </Card>

  <Card title="getTransactionsForAddress" icon="clock-rotate-left" href="/docs/ru/rpc/gettransactionsforaddress">
    История необработанных транзакций с поддержкой аккаунтов токенов и фильтрами на стороне сервера.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.