Bắt đầu nhanh với Parsed Streams

Bạn mới làm quen với Parsed Streams? Hãy đọc mô hình tư duy trước — phần này giải thích lý do các bộ lọc có cấu trúc như vậy.

Bắt đầu nhanh

Get Access

Parsed Streams có sẵn trong tất cả các gói với mức phí 1 credit cho mỗi sự kiện được phân phối. Lấy khóa API từ Helius Dashboard và kết nối với điểm cuối Gatekeeper tại wss://beta.helius-rpc.com, cùng máy chủ với lưu lượng RPC và WebSocket của Helius.Xác thực bằng khóa API của dự án, được truyền dưới dạng tham số truy vấn api-key (hoặc tiêu đề x-api-key).

Connect

wscat

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

Khóa bị thiếu hoặc không hợp lệ sẽ bị từ chối với HTTP 401. Dự án đã đạt giới hạn kết nối sẽ nhận HTTP 429.

Subscribe with a Filter

Gửi parsedTransactionSubscribe cùng một bộ lọc và các tùy chọn không bắt buộc:

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

result trong phản hồi là một ID đăng ký dạng số nguyên:

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

Read a Notification

Mỗi giao dịch khớp sẽ đến dưới dạng parsedTransactionNotification, đã được giải mã, với matchedIndexes trỏ đến các lệnh mà bộ lọc của bạn khớp. Xem Thông báo để biết cấu trúc đầy đủ.

Unsubscribe

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

Hoặc chỉ cần đóng kết nối — thao tác này sẽ xóa tất cả đăng ký của kết nối đó.

Hướng dẫn

Track Jupiter Swaps

Sử dụng describeProgram để tạo một bộ lọc đáng tin cậy trước khi đăng ký.

Track Pump.fun Mints

Một trình lắng nghe an toàn khi kết nối lại, ghi nhật ký mọi lần triển khai token Pump.fun mới.

Handling Reconnects

Duy trì hoạt động qua các lần hết thời gian chờ khi không hoạt động và triển khai, sau đó bổ sung chính xác những gì đã bỏ lỡ.

Tài liệu tham khảo giao thức

Parsed Streams sử dụng JSON-RPC 2.0 qua một kết nối WebSocket duy nhất. Mỗi yêu cầu nhận được một phản hồi có cùng id. Sau đó, một đăng ký sẽ đẩy các thông báo parsedTransactionNotification cho đến khi bạn hủy đăng ký hoặc ngắt kết nối.

Phương thức	Mục đích
`parsedTransactionSubscribe`	Bắt đầu đăng ký bằng một bộ lọc
`parsedTransactionUnsubscribe`	Dừng đăng ký
`describeProgram`	Liệt kê các lệnh, sự kiện và vai trò tài khoản của một chương trình

Đăng ký

Gửi parsedTransactionSubscribe cùng một bộ lọc và các tùy chọn không bắt buộc. result trong phản hồi là một ID đăng ký dạng số nguyên.

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 }

Các trường của bộ lọc

Bắt buộc phải có ít nhất một trong hai trường programs hoặc accounts.include. Các trường bạn đặt được kết hợp bằng phép AND: một lệnh phải đáp ứng tất cả các trường đó mới khớp.

string[]

Các ID chương trình cần khớp (địa chỉ base58, không phải tên). Một lệnh khớp nếu chương trình của lệnh nằm trong danh sách này. Các mục trong danh sách được kết hợp bằng OR.

string[]

Tên lệnh đã giải mã, chẳng hạn như route. Trước tiên hệ thống so khớp chính xác, sau đó dùng phương án dự phòng không phân biệt chữ hoa chữ thường và dấu phân cách, vì vậy sharedAccountsRoute cũng khớp với tên trên dây shared_accounts_route. Các mục trong danh sách được kết hợp bằng OR. Chỉ các lệnh có tên mà danh mục nhận diện được mới có thể khớp, vì vậy hãy lấy tên từ describeProgram.

string[]

Địa chỉ tài khoản. Một lệnh khớp nếu bất kỳ địa chỉ nào trong số này xuất hiện trong danh sách tài khoản của lệnh. Các mục trong danh sách được kết hợp bằng OR. Hoạt động với mọi lệnh, dù đã giải mã hay chưa. Bản thân ID chương trình không được tính là tài khoản ở đây.

object

Ánh xạ từ tên vai trò tài khoản đã giải mã đến địa chỉ, chẳng hạn như { "user_transfer_authority": "<pubkey>" }. Mọi mục đều phải thỏa mãn (AND giữa các mục) và lệnh phải được giải mã thì điều kiện này mới áp dụng. Tên vai trò được so khớp chính xác, không chuyển đổi chữ hoa chữ thường, vì vậy hãy sao chép chúng từ describeProgram thay vì phỏng đoán.

boolean

mặc định:"false"

Bao gồm các lệnh từ giao dịch thất bại.

boolean

mặc định:"true"

Các lệnh bên trong (CPI) đủ điều kiện để khớp. Đặt false để chỉ khớp các lệnh cấp cao nhất.

Các trường không xác định ở bất kỳ đâu trong bộ lọc hoặc tùy chọn đều bị từ chối với -32602 thay vì bị âm thầm bỏ qua, do đó lỗi chính tả sẽ gây lỗi rõ ràng thay vì không khớp với bất kỳ thứ gì.

Tùy chọn

Tham số thứ hai là không bắt buộc.

string

mặc định:"confirmed"

Chỉ hỗ trợ confirmed.

string

mặc định:"full"

Nội dung của mỗi thông báo. full: toàn bộ giao dịch, mọi lệnh, cùng với matchedIndexes trỏ đến các kết quả khớp bộ lọc. matched: chỉ các lệnh đã khớp, không có danh sách chỉ mục. raw: chỉ các lệnh đã khớp, mỗi lệnh được rút gọn thành vị trí, programId và blob data dạng base58, không có trường đã giải mã và không có mảng accountKeys. Sử dụng matched khi băng thông quan trọng hơn ngữ cảnh (payload đầy đủ có kích thước trung bình lớn gấp khoảng ba lần) và raw khi bạn tự giải mã dữ liệu lệnh và chỉ cần các byte.

Số kết nối đồng thời cho mỗi dự án phụ thuộc vào gói của bạn: 5 với Free, 10 với Developer và 50 với Business và Professional, dùng chung cho tất cả khóa API của dự án. Xem Giới hạn tốc độ.

Thông báo

Mỗi giao dịch khớp sẽ tạo một thông báo cho mỗi đăng ký. Với details: "full" mặc định:

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

Cách đọc:

transaction là ngữ cảnh đầy đủ. fee được tính bằng lamport. accountKeys là danh sách khóa hoàn chỉnh, bao gồm các khóa được tải từ bảng tra cứu địa chỉ, theo đúng thứ tự mà chuỗi báo cáo. feePayer luôn là accountKeys[0]. error chứa lỗi giao dịch dưới dạng JSON có cấu trúc, ví dụ {"InstructionError": [2, {"Custom": 6001}]}, khi status là "error".
summary có cùng một cấu trúc ở mọi nơi xuất hiện: một type (chẳng hạn như swap hoặc transfer), một description dễ đọc và một tải trọng parsedData có cấu trúc khi trình phân tích nhận dạng được hành động — đối với một giao dịch hoán đổi: giao thức, số lượng và mint. transaction.summary gắn nhãn cho hành động chính của giao dịch; mỗi chỉ thị được nhận dạng có summary riêng với cùng cấu trúc. Để thu thập mọi giao dịch hoán đổi trong một giao dịch, hãy duyệt qua instructions và đọc summary.parsedData tại nơi summary.type là "swap".
Số lượng hoán đổi do nền tảng giao dịch báo cáo. in_amount, actual_out_amount và số lượng hoán đổi nội bộ trong parsedData là các giá trị do nền tảng giao dịch báo cáo, không phải số lượng mà ví của người dùng thực sự gửi hoặc nhận. Các giá trị này không tính đến phí chuyển Token-2022 hoặc các khoản khấu trừ khác được áp dụng bên ngoài giao dịch hoán đổi. Để biết chính xác số lượng đã nhận, hãy so sánh số dư tài khoản token của người dùng trước và sau giao dịch.
nativeTransfers và tokenTransfers liệt kê các chuyển động SOL và token mà trình phân tích đã trích xuất từ toàn bộ giao dịch, với cùng cấu trúc mà Parsed Events API trả về, nhờ đó bên sử dụng luồng và API có thể dùng chung mã xử lý. Cả hai luôn hiện diện nhưng có thể rỗng.
instructions chứa mọi chỉ thị của giao dịch theo thứ tự thực thi: mỗi chỉ thị cấp cao nhất, tiếp theo là các chỉ thị nội bộ của chỉ thị đó. Mỗi mục chứa vị trí riêng: instructionIndex cho biết mục đó thuộc chỉ thị cấp cao nhất nào (bắt đầu từ 0), innerInstructionIndex là vị trí của mục đó trong số các lệnh gọi nội bộ của chỉ thị ấy (null nghĩa là đây chính là chỉ thị cấp cao nhất), còn stackHeight là độ sâu lệnh gọi (1 đối với cấp cao nhất). Hãy dùng các giá trị này, không dùng vị trí trong mảng.
matchedIndexes là các chỉ mục trong instructions, cho biết những chỉ thị nào thực sự khớp với bộ lọc của bạn. Các chỉ thị còn lại được cung cấp để làm ngữ cảnh. Với details: "matched", mảng chỉ chứa các kết quả khớp và không có matchedIndexes.
Tên decoded dùng kiểu snake_case (in_amount, user_transfer_authority), như được công bố trong IDL của chương trình. Các đối số số nguyên thường là chuỗi ("1000000") vì các giá trị u64 không thể biểu diễn vừa trong kiểu số của JavaScript.
blockTime hiện luôn là null. Không xây dựng logic dựa trên trường này.
Có thể có cả chỉ thị đã giải mã và chưa giải mã trong cùng một giao dịch: một giao dịch hoán đổi đã được giải mã đầy đủ có thể nằm cạnh một memo không được nhận dạng. Hãy rẽ nhánh dựa trên decoded: khi trường này là null, chỉ thị sẽ chứa rawData (các byte base58) và rawAccounts (danh sách pubkey thuần túy) thay thế, vì vậy bạn luôn có dữ liệu để xử lý.

Với details: "raw", value được thu gọn thành siêu dữ liệu giao dịch và các blob. accountKeys, nativeTransfers, tokenTransfers, matchedIndexes và tất cả các trường đã giải mã đều bị loại bỏ (summary của giao dịch vẫn được bao gồm); mỗi lệnh đã khớp chỉ gồm vị trí, chương trình và các byte data dạng base58, chính xác như cách chúng xuất hiện trên chuỗi (có mặt ngay cả với các lệnh mà danh mục có thể giải mã):

"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" }
  ]
}

Hủy đăng ký

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

Trả về true nếu đăng ký tồn tại và thuộc về bạn. Thông báo dừng ngay lập tức. Việc đóng kết nối sẽ xóa tất cả đăng ký của kết nối đó.

Khám phá

Lỗi phổ biến nhất với loại API này là bộ lọc hợp lệ nhưng không khớp với bất kỳ dữ liệu nào, thường do đoán sai tên lệnh hoặc vai trò. describeProgram ngăn chặn điều đó bằng cách trả về chính xác các tên mà trình so khớp sử dụng để so sánh. Hiện tại phương thức này chỉ có trên wss://fs-beta.helius-rpc.com/?api-key=<API_KEY>, vì vậy hãy gửi qua một kết nối riêng biệt với các đăng ký của bạn:

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"]
  }
}

Bạn có thể truyền địa chỉ chương trình hoặc tên danh mục, nhưng nên ưu tiên địa chỉ: tên có thể không rõ ràng giữa các phiên bản chương trình (nhiều mục danh mục có tên jupiter và thao tác tra cứu theo tên có thể phân giải thành mục cũ hơn). Nếu tra cứu theo tên, hãy kiểm tra rằng result.id là chương trình bạn định đăng ký. Quy trình đề xuất: dùng describeProgram để lấy chính xác tên lệnh và vai trò, tạo bộ lọc bằng các tên đó, rồi đăng ký. Hướng dẫn Theo dõi các giao dịch hoán đổi Jupiter trình bày toàn bộ quy trình từ đầu đến cuối.

Giới hạn

Giới hạn	Giá trị
Số kết nối đồng thời cho mỗi dự án	5 (Free), 10 (Developer), 50 (Business và Professional)
Số đăng ký trên mỗi kết nối	25
Thông báo từ máy khách	10 mỗi giây, tối đa 20 trong một đợt
Kích thước thông báo từ máy khách	64 KiB
`programs` trên mỗi bộ lọc	10
`instructionNames` trên mỗi bộ lọc	50, mỗi mục tối đa 64 ký tự
`accounts.include` trên mỗi bộ lọc	100
`accounts.roles` trên mỗi bộ lọc	20, mỗi tên tối đa 64 ký tự
Bộ đệm gửi đi trên mỗi kết nối	2048 thông báo, sau đó kết nối sẽ bị đóng

Lỗi

Các lỗi tuân theo JSON-RPC 2.0: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }. Thông báo cho biết chính xác lỗi là gì và nằm ở đâu.

Mã	Ý nghĩa
`-32700`	Lỗi phân tích cú pháp (JSON không hợp lệ)
`-32600`	Yêu cầu không hợp lệ
`-32601`	Không tìm thấy phương thức
`-32602`	Tham số không hợp lệ: pubkey sai, trường không xác định, giá trị commitment hoặc details không được hỗ trợ
`-32000`	Vượt quá giới hạn bộ lọc
`-32001`	Máy chủ chưa sẵn sàng; thử lại với thời gian chờ tăng dần
`-32002`	Bị giới hạn tốc độ (10 thông báo mỗi giây)
`-32006`	Quá nhiều đăng ký (25 trên mỗi kết nối)

Kết nối cũng có thể đóng với mã đóng WebSocket — xem Xử lý kết nối lại để biết ý nghĩa của từng mã và cách khôi phục.

Ví dụ máy khách

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())

Bắt đầu

Truyền dữ liệu & lắng nghe sự kiện

API dữ liệu & RPC

Giao dịch mua bán

Gửi giao dịch

Ví dưới dạng dịch vụ

Quyền riêng tư

Tài nguyên

Bắt đầu nhanh với Parsed Streams