Learn how to listen for and retrieve Solana compressed NFT events using Helius APIs. WebSockets, webhooks, gRPC streaming, and real-time cNFT monitoring.
Traditional NFTs each have their own mint address and token account.
Compressed NFTs store data within a Merkle tree managed by the related cNFT program. This single on-chain account holds the Merkle tree root, and each NFT is represented as a leaf in that tree.
A cNFT transfer updates the ownership data in the existing leaf.
A cNFT burn removes or invalidates the leaf from the tree.
Because cNFTs lack typical token accounts, standard Solana NFT tracking methods (e.g., “watch the mint address” or “subscribe to a token account”) won’t work. Instead, you focus on program instructions or the Merkle tree account.
Imagine building a marketplace, wallet, or analytics dashboard around cNFTs. You need to know:
When new cNFTs are minted.
Which cNFTs are transferred to or from a user.
Whether a cNFT was burned.
Receiving these updates in real time helps you keep your interface or data layer in perfect sync with on-chain state. Combined with historical lookups, you gain a complete timeline of cNFT activity, from the moment it was created to its current status.
Helius offers three major ways to listen for cNFT events:
Standard WebSockets: Simple persistent connection for basic program monitoring
Enhanced WebSockets: Advanced filtering with better transaction targeting
gRPC (Yellowstone): Maximum performance and flexibility via LaserStream or Dedicated Nodes
Choose based on your needs: Standard WebSockets for simplicity, Enhanced WebSockets for better filtering, or gRPC for enterprise-scale applications with the highest performance.
Real-time event feeds are great for capturing future events. But what if you need the past—the entire lifetime of a cNFT or all transactions that impacted a Merkle tree or wallet?
In this section, we’ll explore two primary methods for historical lookups:
Helius’ Parsed Transaction API
Normal Solana RPC Calls: getSignaturesForAddress + getParsedTransaction or getTransaction
Helius offers an Enhanced Transaction API. It automatically decodes NFT, SPL, and Swap transactions into a human-readable format. This saves you from manually parsing raw data.
4.2 Normal Methods: getSignaturesForAddress + getParsedTransaction / getTransaction
If you prefer the traditional Solana approach or want maximum control, you can call Solana’s native RPC methods:
getSignaturesForAddress: Returns an array of transaction signatures involving the given address (e.g., the Merkle tree or user’s wallet).
getParsedTransaction: Returns a Solana-parsed JSON for a given signature.
getTransaction: Returns the raw binary-encoded transaction, which you can parse using an external library (e.g., Blockbuster) if you need specialized cNFT decoding.
4.2.1 getSignaturesForAddress
This is a pagination-friendly method. You can pass before or until parameters.
Example:
Copy
Ask AI
async function fetchSignatures(address, limit = 10) { const rpcUrl = "https://mainnet.helius-rpc.com/?api-key=<YOUR_API_KEY>"; const body = { jsonrpc: "2.0", id: 1, method: "getSignaturesForAddress", params: [ address, { limit: limit, commitment: "confirmed" } ] }; const response = await fetch(rpcUrl, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); if (data.error) { throw new Error(`RPC error: ${data.error.message}`); } console.log("Signatures for address:", data.result); return data.result;}// Usage with error handlingfetchSignatures("MERKLE_TREE_ADDRESS").catch(console.error);
4.2.2 getParsedTransaction or getTransaction
Once you have the signatures, retrieve each transaction’s details:
Look for instructions referencing the cNFT program or the Merkle tree. If you use getTransaction instead, you’ll get raw data (e.g., base64), which you’d decode with a specialized parser.
Filter for the cNFT program or a Merkle tree address.
Parse instructions in real time to track mints, transfers, and burns.
Retrieve Historical Data
Helius Enhanced Transaction API: The easiest way to get a human-readable breakdown of cNFT actions.
Normal RPC: getSignaturesForAddress + getParsedTransaction (or getTransaction + manual parsing) for maximum flexibility or if you already rely on standard Solana RPC calls.
Build a Complete Timeline
Merge future (real-time) events with past (historical) data.
If your event listening solution ever goes down, fill gaps by pulling recent transaction signatures for your Merkle tree or user address.
Leverage Helius: The Enhanced Transaction API is particularly handy if you want cNFT events (mints, transfers, burns) in a straightforward JSON format.
Pagination: For addresses with a lot of activity, you may need to iterate with before or until to get older data.
Verification: For extra security, you can verify Merkle proofs to confirm a cNFT leaf is valid under the on-chain root.
Indexing: If you’re building a large-scale solution, consider storing parsed cNFT events in your own database for quick queries.
Performance: For high-volume event listening, gRPC (via LaserStream or Dedicated Nodes) offers top performance and advanced filters.
Error Handling: Always implement proper error handling and retry logic for production applications.
Connection Management: For WebSocket connections, implement heartbeat/ping mechanisms to maintain connections.
Rate Limiting: Be aware of API rate limits and implement appropriate throttling in your applications.