Parsed Streams 빠른 시작

Parsed Streams가 처음이신가요? 정신 모델을 먼저 읽어보세요. 필터가 왜 그런 모양인지 설명합니다.

빠른 시작

Get Access

Parsed Streams는 모든 플랜에서 사용할 수 있으며, 전달된 이벤트당 1크레딧이 부과됩니다. Helius Dashboard에서 API 키를 발급받고, Helius RPC 및 WebSocket 트래픽과 동일한 호스트인 wss://beta.helius-rpc.com의 Gatekeeper 엔드포인트에 연결하세요.api-key 쿼리 매개변수(또는 x-api-key 헤더)로 전달되는 프로젝트의 API 키로 인증합니다.

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은(는) 정수 구독 ID입니다:

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

Read a Notification

일치하는 각 거래는 이미 디코딩된 parsedTransactionNotification으로 도착하며, 필터의 명령어를 가리키는 matchedIndexes가 있습니다. 전체 형식을 보려면 Notifications을 참조하세요.

Unsubscribe

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

또는 연결을 닫기만 하면 모든 구독이 제거됩니다.

가이드

Jupiter 스왑 추적

구독 전에 신뢰할 수 있는 필터를 만들기 위해 describeProgram을 사용하세요.

Pump.fun 민트 추적

새로운 Pump.fun 토큰 배포를 모두 기록하는 재연결 안전 리스너.

재연결 처리

유휴 시간 초과 및 배포를 극복하고, 놓친 부분을 정확하게 백필합니다.

프로토콜 참조

Parsed Streams는 단일 WebSocket 연결을 통해 JSON-RPC 2.0을 사용합니다. 각 요청은 동일한 id로 응답합니다. 그런 다음 구독은 당신이 구독 취소하거나 연결을 끊을 때까지 parsedTransactionNotification 메시지를 푸시합니다.

메서드	용도
`parsedTransactionSubscribe`	필터를 사용하여 구독 시작
`parsedTransactionUnsubscribe`	구독 중지
`describeProgram`	프로그램의 명령어, 이벤트 및 계정 역할 나열

필터와 선택적 옵션으로 parsedTransactionSubscribe을(를) 전송합니다. 응답 result은(는) 정수 구독 id입니다.

Request

{
  "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[]

매칭할 프로그램 ID(이름이 아닌 base58 주소). 명령어의 프로그램이 이 목록에 있을 경우 일치합니다. 목록 내에서는 OR입니다.

string[]

route과 같은 디코딩된 명령어 이름입니다. 목록 내에서는 OR입니다. 카탈로그에서 식별할 수 있는 이름만 매치될 수 있으므로 describeProgram에서 이름을 가져가세요.

string[]

계정 주소. 명령어의 계정 목록에 이들 중 하나가 나타나면 일치합니다. 목록 내에서는 OR입니다. 디코딩 여부와 관계없이 모든 명령어에서 작동합니다. 프로그램 ID 자체는 여기서 계정으로 간주되지 않습니다.

object

디코딩된 계정 역할 이름과 주소의 맵입니다. 각 항목은 성립해야 하며(항목 간 AND) 이 기능에는 명령어가 디코딩되어야 합니다. 역할 이름은 대소문자 변경 없이 정확히 맞아야 하므로 추측하지 말고 describeProgram에서 복사하세요.

boolean

기본값:"false"

실패한 거래의 명령어 포함.

boolean

기본값:"true"

내부(CPI) 명령어도 매칭에 적합합니다. 상위 수준 명령어만 매칭하려면 false를 설정하세요.

필터나 옵션의 어디에서든 알 수 없는 필드는 묵과되는 대신 -32602으로 거부되므로 오타는 아무것도 매칭되지 않는 대신 크게 실패합니다.

옵션

두 번째 매개변수는 선택사항입니다.

string

기본값:"confirmed"

지원되는 유일한 값은 confirmed입니다.

string

기본값:"full"

각 알림에 포함되는 내용입니다. full: 전체 거래, 모든 명령어, 그리고 필터 히트를 가리키는 matchedIndexes을 포함합니다. matched: 매칭된 명령어만, 인덱스 목록 없음. raw: 매칭된 명령어만, 각 위치까지 줄어든 상태, programId, base58의 data 블롭(디코딩 필드 및 accountKeys 배열 없음). 대역폭이 컨텍스트보다 중요하면 matched을 사용하고, 명령어 데이터를 직접 디코딩하고 바이트만 필요할 때는 raw을 사용하세요.

프로젝트당 동시 연결 수는 플랜에 따라 다릅니다. Free는 5개, Developer는 10개, Business 및 Professional은 50개이며, 프로젝트의 모든 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의 단위는 lamports입니다. accountKeys는 주소 조회 테이블에서 로드된 키를 포함한 전체 키 목록이며, 체인이 보고하는 순서와 동일합니다. feePayer는 항상 accountKeys[0]입니다. status가 "error"일 때 error에는 트랜잭션 오류가 구조화된 JSON으로 포함됩니다(예: {"InstructionError": [2, {"Custom": 6001}]}).
**summary**는 어디에 나타나든 동일한 구조를 가집니다. type(예: swap 또는 transfer), 사람이 읽을 수 있는 description, 그리고 파서가 작업을 인식할 때의 구조화된 parsedData 페이로드로 구성됩니다. 스왑의 경우 프로토콜, 수량, 민트가 포함됩니다. transaction.summary는 트랜잭션의 주요 작업을 나타냅니다. 인식된 각 명령어에는 동일한 구조의 자체 summary가 포함됩니다. 트랜잭션의 모든 스왑을 수집하려면 instructions를 순회하고, summary.type가 "swap"인 항목에서 summary.parsedData를 읽으세요.
스왑 수량은 거래소가 보고한 값입니다. 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에 게시된 형식과 동일합니다. u64 값은 JavaScript 숫자에 담을 수 없으므로 정수 인수는 일반적으로 문자열입니다("1000000").
**blockTime**는 현재 항상 null입니다. 이 값을 기반으로 구현하지 마세요.
하나의 트랜잭션 안에 디코딩된 명령어와 디코딩되지 않은 명령어가 섞여 있을 수 있습니다. 완전히 디코딩된 스왑 옆에 인식되지 않은 메모가 있을 수 있습니다. decoded를 기준으로 분기하세요. 값이 null이면 명령어에 대신 rawData(base58 바이트)와 rawAccounts(일반 pubkey 목록)가 포함되므로 항상 처리할 데이터가 있습니다.

details: "raw"에서는 value가 트랜잭션 메타와 블롭으로 축소됩니다. accountKeys, nativeTransfers, tokenTransfers, matchedIndexes 및 모든 디코딩 필드가 사라집니다. 매칭된 모든 명령어는 위치, 프로그램 및 체인에 표시되는 것과 정확히 같은 base58의 data 바이트입니다(카탈로그가 디코딩할 수 있던 명령어에도 표시).

"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을 사용하고, 해당 이름으로 필터를 작성한 다음 구독하세요. Track Jupiter Swaps 가이드는 이 전체 과정을 처음부터 끝까지 안내합니다.

제한 사항

한도	값
프로젝트당 동시 연결 수	5(Free), 10(Developer), 50(Business 및 Professional)
연결당 구독 수	25
클라이언트 메시지	초당 10개, 순간 최대 20개
클라이언트 메시지 크기	64 KiB
필터당 `programs`	10
필터당 `instructionNames`	50, 각각 최대 64자
필터당 `accounts.include`	100
필터당 `accounts.roles`	20, 각 이름은 최대 64자
연결당 발신 버퍼	알림 2,048개, 이후 연결 종료

오류

오류는 JSON-RPC 2.0을 따릅니다: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }. 메시지는 정확히 무엇이 잘못되었는지 어디에서 문제가 발생했는지 알려줍니다.

코드	의미
`-32700`	구문 분석 오류 (유효하지 않은 JSON)
`-32600`	잘못된 요청
`-32601`	메서드를 찾을 수 없음
`-32602`	잘못된 매개변수: 잘못된 공개키, 알 수 없는 필드, 지원되지 않는 커밋 또는 세부정보 값
`-32000`	필터 제한 초과
`-32001`	서버 준비가 되지 않음; 백오프로 재시도
`-32002`	속도 제한 (초당 10개 메시지)
`-32006`	너무 많은 구독 (연결당 25개)

연결은 WebSocket 종료 코드로도 닫을 수 있습니다 — 각 의미와 복구 방법은 Handling Reconnects를 참조하세요.

클라이언트 예제

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 빠른 시작

빠른 시작

가이드

Jupiter 스왑 추적

Pump.fun 민트 추적

재연결 처리

프로토콜 참조

구독

필터 필드

옵션

알림

구독 취소

디스커버리

제한 사항

오류

클라이언트 예제

​빠른 시작

​가이드

Jupiter 스왑 추적

Pump.fun 민트 추적

재연결 처리

​프로토콜 참조

​구독

​필터 필드

​옵션

​알림

​구독 취소

​디스커버리

​제한 사항

​오류

​클라이언트 예제

빠른 시작

가이드

프로토콜 참조

구독

필터 필드

옵션

알림

구독 취소

디스커버리

제한 사항

오류

클라이언트 예제