Краткое руководство по Parsed Streams

Впервые используете Parsed Streams? Сначала прочитайте описание ментальной модели — оно объясняет, почему фильтры устроены именно так.

Краткое руководство

Get Access

Parsed Streams доступен на всех тарифных планах по цене 1 кредит за каждое доставленное событие. Получите ключ API в панели управления Helius и подключитесь к конечной точке Gatekeeper по адресу wss://beta.helius-rpc.com — на том же хосте, который используется для трафика Helius RPC и WebSocket.Пройдите аутентификацию с помощью ключа API вашего проекта, передав его как параметр запроса api-key (или заголовок x-api-key).

Connect

wscat

wscat -c "wss://beta.helius-rpc.com/?api-key=YOUR_API_KEY"

Если ключ отсутствует или недействителен, запрос отклоняется с HTTP 401. Если проект достиг лимита подключений, возвращается HTTP 429.

Subscribe with a Filter

Отправьте parsedTransactionSubscribe с фильтром и необязательными параметрами:

{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

Поле result в ответе — это целочисленный идентификатор подписки:

{ "jsonrpc": "2.0", "id": 1, "result": 23 }

Read a Notification

Каждая соответствующая транзакция поступает как parsedTransactionNotification уже в декодированном виде, а matchedIndexes указывает на инструкции, соответствующие вашему фильтру. Полную структуру см. в разделе «Уведомления».

Unsubscribe

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

Или просто закройте подключение — при этом все его подписки будут удалены.

Руководства

Track Jupiter Swaps

Используйте describeProgram, чтобы создать надежный фильтр перед оформлением подписки.

Track Pump.fun Mints

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

Handling Reconnects

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

Справочник по протоколу

Parsed Streams использует JSON-RPC 2.0 через одно подключение WebSocket. На каждый запрос поступает ответ с тем же id. Затем подписка отправляет сообщения parsedTransactionNotification, пока вы не отмените подписку или не отключитесь.

Метод	Назначение
`parsedTransactionSubscribe`	Создать подписку с фильтром
`parsedTransactionUnsubscribe`	Остановить подписку
`describeProgram`	Получить список инструкций, событий и ролей аккаунтов программы

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "parsedTransactionSubscribe",
  "params": [
    {
      "programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
      "instructionNames": ["route", "shared_accounts_route"],
      "accounts": {
        "include": ["So11111111111111111111111111111111111111112"],
        "roles": { "user_transfer_authority": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" }
      },
      "includeFailed": false,
      "includeCpi": true
    },
    { "commitment": "confirmed", "details": "full" }
  ]
}

Response

{ "jsonrpc": "2.0", "id": 1, "result": 23 }

Поля фильтра

Необходимо указать хотя бы одно из полей programs или accounts.include. Заданные поля объединяются оператором AND: для совпадения инструкция должна соответствовать каждому из них.

string[]

Идентификаторы программ для сопоставления (адреса base58, а не имена). Инструкция соответствует фильтру, если ее программа входит в этот список. Внутри списка применяется OR.

string[]

Имена декодированных инструкций, например route. Сначала выполняется точное сопоставление, а затем — резервное сопоставление без учета регистра и разделителей, поэтому sharedAccountsRoute также соответствует имени shared_accounts_route в передаваемых данных. Внутри списка применяется OR. Соответствовать фильтру могут только инструкции, имя которых удалось определить по каталогу, поэтому берите имена из describeProgram.

string[]

Адреса аккаунтов. Инструкция соответствует фильтру, если любой из этих адресов присутствует в ее списке аккаунтов. Внутри списка применяется OR. Работает для каждой инструкции независимо от того, декодирована она или нет. Сам идентификатор программы здесь не считается аккаунтом.

object

Сопоставление имени роли декодированного аккаунта с адресом, например { "user_transfer_authority": "<pubkey>" }. Каждая запись должна выполняться (между записями применяется AND), а для применения этого условия инструкция должна быть декодирована. Имена ролей сопоставляются точно, без изменения регистра, поэтому копируйте их из describeProgram, а не подбирайте самостоятельно.

boolean

по умолчанию:"false"

Включать инструкции из неуспешных транзакций.

boolean

по умолчанию:"true"

Внутренние инструкции (CPI) могут соответствовать фильтру. Укажите false, чтобы сопоставлять только инструкции верхнего уровня.

Неизвестные поля в любой части фильтра или параметров не игнорируются, а отклоняются с ошибкой -32602. Поэтому опечатки приводят к явной ошибке, а не к отсутствию совпадений.

Параметры

Второй параметр необязателен.

string

по умолчанию:"confirmed"

Поддерживается только confirmed.

string

по умолчанию:"full"

Содержимое каждого уведомления. full: вся транзакция, каждая инструкция и matchedIndexes, указывающий на совпадения с фильтром. matched: только совпавшие инструкции без списка индексов. raw: только совпавшие инструкции, каждая из которых сокращена до своей позиции, programId и блока data в формате base58, без декодированных полей и массива accountKeys. Используйте matched, если пропускная способность важнее контекста (полный объем данных в среднем примерно втрое больше), и raw, если вы самостоятельно декодируете данные инструкций и вам нужны только байты.

Количество одновременных подключений на проект зависит от тарифного плана: 5 для Free, 10 для Developer и 50 для Business и Professional. Лимит общий для всех ключей API проекта. См. «Ограничения частоты запросов».

Уведомления

Для каждой соответствующей транзакции отправляется одно уведомление на подписку. При значении details: "full" по умолчанию:

{
  "jsonrpc": "2.0",
  "method": "parsedTransactionNotification",
  "params": {
    "subscription": 23,
    "result": {
      "context": { "slot": 430172053 },
      "value": {
        "transaction": {
          "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
          "slot": 430172053,
          "blockTime": null,
          "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
          "fee": 5000,
          "accountKeys": ["6jduWNCT...", "..."],
          "status": "ok",
          "error": null,
          "summary": {
            "type": "swap",
            "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
            "parsedData": {
              "type": "swap",
              "protocol": "jupiter",
              "kind": "swap",
              "in_amount": "1000000",
              "actual_out_amount": "183985",
              "input_mint": "So11111111111111111111111111111111111111112",
              "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          },
          "nativeTransfers": [
            { "fromUserAccount": "6jduWNCT...", "toUserAccount": "DfXygSm4...", "amount": 1000000 }
          ],
          "tokenTransfers": [
            {
              "fromUserAccount": "6jduWNCT...",
              "toUserAccount": "AeUfFU6L...",
              "fromTokenAccount": "HLaEoW1s...",
              "toTokenAccount": "G13P9kSY...",
              "rawTokenAmount": 183985,
              "decimals": 6,
              "tokenStandard": "Fungible",
              "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          ]
        },
        "instructions": [
          {
            "instructionIndex": 4,
            "innerInstructionIndex": null,
            "stackHeight": 1,
            "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
            "programName": "jupiter",
            "instructionName": "route",
            "summary": {
              "type": "swap",
              "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
              "parsedData": {
                "type": "swap",
                "protocol": "jupiter",
                "kind": "swap",
                "in_amount": "1000000",
                "actual_out_amount": "183985",
                "input_mint": "So11111111111111111111111111111111111111112",
                "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
              }
            },
            "decoded": {
              "args": { "in_amount": "1000000", "slippage_bps": 50 },
              "accounts": [
                { "name": "user_transfer_authority", "pubkey": "9xQe...", "isSigner": true, "isWritable": false }
              ]
            }
          }
        ],
        "matchedIndexes": [8, 13]
      }
    }
  }
}

Как это читать:

transaction содержит полный контекст. Значение fee указано в лампортах. accountKeys — полный список ключей, включая ключи, загруженные из таблиц поиска адресов, в том же порядке, в котором их возвращает блокчейн. Значение feePayer всегда равно accountKeys[0]. Поле error содержит ошибку транзакции в виде структурированного JSON, например {"InstructionError": [2, {"Custom": 6001}]}, когда status равно "error".
summary имеет одинаковую структуру везде, где встречается: type (например, swap или transfer), понятное человеку поле description и структурированные данные parsedData, когда синтаксический анализатор распознает действие. Для обмена это протокол, суммы и минты. transaction.summary обозначает основное действие транзакции; каждая распознанная инструкция содержит собственное поле summary с той же структурой. Чтобы получить все обмены в транзакции, переберите instructions и прочитайте summary.parsedData там, где summary.type равно "swap".
Суммы обмена сообщаются площадкой. Значения in_amount, actual_out_amount и суммы внутренних обменов в parsedData — это значения, указанные площадкой, а не суммы, фактически отправленные или полученные кошельком пользователя. Они не учитывают комиссии за перевод Token-2022 и другие удержания, примененные вне обмена. Чтобы узнать точную полученную сумму, сравните балансы токен-аккаунта пользователя до и после транзакции.
nativeTransfers и tokenTransfers содержат движения SOL и токенов, извлеченные синтаксическим анализатором из всей транзакции, в той же структуре, которую возвращает Parsed Events API. Благодаря этому потребители потока и API могут использовать общий код обработки. Оба поля присутствуют всегда, но могут быть пустыми.
instructions содержит все инструкции транзакции в порядке выполнения: за каждой инструкцией верхнего уровня следуют ее внутренние инструкции. Каждая запись содержит собственную позицию: instructionIndex указывает, к какой инструкции верхнего уровня она относится (нумерация начинается с 0), innerInstructionIndex — ее позицию среди внутренних вызовов этой инструкции (null означает, что это сама инструкция верхнего уровня), а stackHeight — глубину вызова (1 для верхнего уровня). Используйте эти значения, а не позицию в массиве.
matchedIndexes содержит индексы элементов instructions, которые фактически соответствуют вашему фильтру. Остальные элементы предоставляются для контекста. При details: "matched" массив содержит только совпадения, а matchedIndexes отсутствует.
Имена decoded записываются в snake_case (in_amount, user_transfer_authority), как они опубликованы в IDL программы. Целочисленные аргументы часто представлены строками ("1000000"), поскольку значения u64 не помещаются в числовой тип JavaScript.
blockTime в настоящее время всегда равно null. Не полагайтесь на это поле.
В одной транзакции может встречаться сочетание декодированных и недекодированных инструкций: полностью декодированный обмен может находиться рядом с нераспознанной заметкой. Выбирайте ветвь по decoded: когда его значение равно null, инструкция вместо этого содержит rawData (байты base58) и rawAccounts (обычный список публичных ключей), поэтому у вас всегда будут данные для обработки.

При details: "raw" поле value сокращается до метаданных транзакции и блоков данных. accountKeys, nativeTransfers, tokenTransfers, matchedIndexes и все декодированные поля отсутствуют (поле транзакции summary по-прежнему включено). Каждая совпавшая инструкция представлена своей позицией, программой и байтами data в формате base58 точно в том виде, в котором они находятся в блокчейне (они присутствуют даже для инструкций, которые можно было декодировать по каталогу):

"value": {
  "transaction": {
    "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
    "slot": 430172053,
    "blockTime": null,
    "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
    "fee": 5000,
    "status": "ok",
    "error": null,
    "summary": {
      "type": "swap",
      "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
      "parsedData": {
        "type": "swap",
        "protocol": "jupiter",
        "kind": "swap",
        "in_amount": "1000000",
        "actual_out_amount": "183985",
        "input_mint": "So11111111111111111111111111111111111111112",
        "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    }
  },
  "instructions": [
    { "instructionIndex": 4, "innerInstructionIndex": null, "stackHeight": 1, "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", "data": "3Bxs4h24hBtQy9rw" }
  ]
}

Отмена подписки

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

Возвращает true, если подписка существовала и принадлежала вам. Уведомления прекращаются немедленно. При закрытии подключения удаляются все его подписки.

Обнаружение

Самая распространенная ошибка при работе с API такого типа — допустимый фильтр, который ничего не находит, обычно из-за неверно подобранного имени инструкции или роли. describeProgram предотвращает это, возвращая точные имена, с которыми выполняется сопоставление. Сейчас этот метод доступен только в wss://fs-beta.helius-rpc.com/?api-key=<API_KEY>, поэтому отправляйте его через отдельное от подписок подключение:

Request

{ "jsonrpc": "2.0", "id": 1, "method": "describeProgram", "params": [{ "program": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" }] }

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
    "name": "jupiter",
    "instructions": ["route", "shared_accounts_route", "exact_out_route"],
    "events": ["SwapEvent"],
    "roles": ["user_transfer_authority", "destination_token_account"]
  }
}

Можно передать адрес программы или ее имя в каталоге, но предпочтительно использовать адрес: имена могут быть неоднозначными в разных версиях программы (несколько записей каталога имеют имя jupiter, и поиск по имени может вернуть более старую запись). Если вы выполняете поиск по имени, убедитесь, что result.id — это программа, на которую вы хотите подписаться. Рекомендуемый порядок действий: вызовите describeProgram, чтобы получить точные имена инструкций и ролей, создайте фильтр с этими именами, а затем оформите подписку. Полный процесс пошагово описан в руководстве «Отслеживание обменов Jupiter».

Ограничения

Ограничение	Значение
Одновременные подключения на проект	5 (Free), 10 (Developer), 50 (Business и Professional)
Подписки на одно подключение	25
Сообщения клиента	10 в секунду, пакет до 20
Размер сообщения клиента	64 КиБ
`programs` на фильтр	10
`instructionNames` на фильтр	50, до 64 символов каждый
`accounts.include` на фильтр	100
`accounts.roles` на фильтр	20, каждое имя — до 64 символов
Буфер исходящих данных на подключение	2048 уведомлений, после чего подключение закрывается

Ошибки

Ошибки соответствуют JSON-RPC 2.0: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }. В сообщениях точно указано, что и где пошло не так.

Код	Значение
`-32700`	Ошибка синтаксического анализа (недопустимый JSON)
`-32600`	Недопустимый запрос
`-32601`	Метод не найден
`-32602`	Недопустимые параметры: неверный публичный ключ, неизвестное поле, неподдерживаемое значение commitment или details
`-32000`	Превышен лимит фильтра
`-32001`	Сервер не готов; повторите попытку с увеличивающейся задержкой
`-32002`	Превышено ограничение частоты запросов (10 сообщений в секунду)
`-32006`	Слишком много подписок (25 на подключение)

Подключения также могут закрываться с кодом закрытия WebSocket. Значение каждого кода и способы восстановления см. в руководстве «Обработка переподключений».

Примеры клиентов

wscat -c "wss://beta.helius-rpc.com/?api-key=<API_KEY>"
# then send:
{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

import WebSocket from "ws";

const ws = new WebSocket("wss://beta.helius-rpc.com/?api-key=<API_KEY>");

ws.on("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "parsedTransactionSubscribe",
    params: [{ programs: ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"] }],
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.method === "parsedTransactionNotification") {
    const { transaction, instructions, matchedIndexes } = msg.params.result.value;
    for (const i of matchedIndexes ?? instructions.keys()) {
      const ix = instructions[i];
      console.log(transaction.signature, ix.programName, ix.instructionName, ix.decoded?.args);
    }
  }
});

import asyncio, json, websockets

URL = "wss://beta.helius-rpc.com/?api-key=<API_KEY>"

async def main():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1, "method": "parsedTransactionSubscribe",
            "params": [{"programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}],
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("method") == "parsedTransactionNotification":
                value = msg["params"]["result"]["value"]
                for i in value.get("matchedIndexes") or range(len(value["instructions"])):
                    ix = value["instructions"][i]
                    print(ix.get("programName"), ix.get("instructionName"), (ix.get("decoded") or {}).get("args"))

asyncio.run(main())

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

Потоковая передача данных и отслеживание событий

API данных и RPC

Торговля

Отправка транзакций

Кошелек как услуга

Конфиденциальность

Ресурсы

Краткое руководство по Parsed Streams