Introduction

Helius provides a standard Solana WebSocket interface that allows you to receive real-time updates about accounts, programs, transactions, and blockchain state. Our WebSocket implementation follows the standard Solana WebSocket API, making it compatible with existing Solana clients and libraries, while benefiting from Helius’s infrastructure for improved reliability.

Connection Setup

To connect to the Helius WebSocket endpoint, use the following URL format:

wss://mainnet.helius-rpc.com?api-key=YOUR_API_KEY

Replace YOUR_API_KEY with your Helius API key. You can also use our other network endpoints:

  • Mainnet: wss://mainnet.helius-rpc.com?api-key=YOUR_API_KEY
  • Devnet: wss://devnet.helius-rpc.com?api-key=YOUR_API_KEY

Subscription Methods

Helius supports all standard Solana WebSocket subscription methods:

Account Subscriptions

Subscribe to changes for a specific account:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "accountSubscribe",
  "params": [
    "9PejEmViKHgUkVFWN57cNEZnFS4Qo6SzsLj5UPAXfDTF",
    {
      "encoding": "jsonParsed",
      "commitment": "confirmed"
    }
  ]
}

// Response
{
  "jsonrpc": "2.0",
  "result": 23784,
  "id": 1
}

// Notification
{
  "jsonrpc": "2.0",
  "method": "accountNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5199307
      },
      "value": {
        "data": ["base64-encoded-data", "base64"],
        "executable": false,
        "lamports": 1000000000,
        "owner": "11111111111111111111111111111111",
        "rentEpoch": 18
      }
    },
    "subscription": 23784
  }
}

Learn more about accountSubscribe

Program Subscriptions

Subscribe to changes for all accounts owned by a program:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "programSubscribe",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "encoding": "jsonParsed",
      "commitment": "confirmed"
    }
  ]
}

// Response
{
  "jsonrpc": "2.0",
  "result": 24040,
  "id": 1
}

Learn more about programSubscribe

Logs Subscriptions

Subscribe to transaction log messages:

// Request - subscribe to all logs
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logsSubscribe",
  "params": [
    "all",
    {
      "commitment": "confirmed"
    }
  ]
}

// Request - subscribe to specific program logs
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logsSubscribe",
  "params": [
    {
      "mentions": ["11111111111111111111111111111111"]
    },
    {
      "commitment": "confirmed"
    }
  ]
}

Learn more about logsSubscribe

Signature Subscriptions

Subscribe to transaction status updates:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "5UfDuA1mQcZeb7BZyWU5T6CvZsYqsRwBUHFyMeTzwcnn8S6W9vzVDjp3NgjV7qHJQvw5qQbbGvGxoULZKHGUdSmo",
    {
      "commitment": "confirmed"
    }
  ]
}

Learn more about signatureSubscribe

Slot Subscriptions

Subscribe to new slots:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotSubscribe"
}

Learn more about slotSubscribe

Slot Updates Subscriptions

Subscribe to detailed information about slots:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotsUpdatesSubscribe"
}

Learn more about slotsUpdatesSubscribe

Root Subscriptions

Subscribe to new roots (finalized blocks):

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rootSubscribe"
}

Learn more about rootSubscribe

Vote Subscriptions

Subscribe to vote activity:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voteSubscribe"
}

Learn more about voteSubscribe

Unsubscribing

To stop receiving updates for any subscription:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "unsubscribe",
  "params": [23784]
}

// Response
{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1
}

Replace the number in the params array with your actual subscription ID.

JavaScript Examples

Here are complete Node.js examples showing how to use the WebSocket API with JavaScript.

Program Subscribe Example

This example shows how to subscribe to all account changes for a specific program:

const WebSocket = require('ws');

// Create a WebSocket connection
const ws = new WebSocket('wss://mainnet.helius-rpc.com/?api-key=<api-key>');

// Function to send a request to the WebSocket server
function sendRequest(ws) {
    const request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "programSubscribe",
        "params": [
          "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          {
            "encoding": "jsonParsed"
          }
        ]
      };
    ws.send(JSON.stringify(request));
}

// Function to send a ping to the WebSocket server
function startPing(ws) {
    setInterval(() => {
        if (ws.readyState === WebSocket.OPEN) {
            ws.ping();
            console.log('Ping sent');
        }
    }, 30000); // Ping every 30 seconds
}

// Define WebSocket event handlers
ws.on('open', function open() {
    console.log('WebSocket is open');
    sendRequest(ws); // Send a request once the WebSocket is open
    startPing(ws); // Start sending pings
});

ws.on('message', function incoming(data) {
    const messageStr = data.toString('utf8');
    try {
        const messageObj = JSON.parse(messageStr);
        console.log('Received:', messageObj);
    } catch (e) {
        console.error('Failed to parse JSON:', e);
    }
});

ws.on('error', function error(err) {
    console.error('WebSocket error:', err);
});

ws.on('close', function close() {
    console.log('WebSocket is closed');
});

Signature Subscribe Example

This example shows how to subscribe to a transaction signature to get notified when its status changes. This subscription is for a single notification - the server automatically cancels it after sending the signatureNotification:

const WebSocket = require('ws');

// Create a WebSocket connection
const ws = new WebSocket('wss://mainnet.helius-rpc.com/?api-key=<api-key>');

// Function to send a request to the WebSocket server
function sendRequest(ws) {
    const request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "signatureSubscribe",
        "params": [
          "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
          {
            "commitment": "finalized",
            "enableReceivedNotification": false
          }
        ]
      };
    ws.send(JSON.stringify(request));
}

// Function to send a ping to the WebSocket server
function startPing(ws) {
    setInterval(() => {
        if (ws.readyState === WebSocket.OPEN) {
            ws.ping();
            console.log('Ping sent');
        }
    }, 30000); // Ping every 30 seconds
}

// Define WebSocket event handlers
ws.on('open', function open() {
    console.log('WebSocket is open');
    sendRequest(ws); // Send a request once the WebSocket is open
    startPing(ws); // Start sending pings
});

ws.on('message', function incoming(data) {
    const messageStr = data.toString('utf8');
    try {
        const messageObj = JSON.parse(messageStr);
        console.log('Received:', messageObj);
    } catch (e) {
        console.error('Failed to parse JSON:', e);
    }
});

ws.on('error', function error(err) {
    console.error('WebSocket error:', err);
});

ws.on('close', function close() {
    console.log('WebSocket is closed');
});

Error Handling

WebSocket errors follow the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  },
  "id": 1
}

Rate Limits

Websockets are subject to rate limits based on your Helius plan. If you exceed these limits, connections may be dropped or throttled. For high-volume applications, consider upgrading to a higher tier plan or using LaserStream for enhanced capabilities.

Enhanced Capabilities with LaserStream

For applications requiring more advanced streaming features, Helius offers LaserStream, which provides:

  • Historical replay to catch up on missed data
  • Enhanced stability through multi-node aggregation
  • Multiple protocol options (gRPC, Enhanced WebSockets)
  • Higher throughput and lower latency

Learn more about LaserStream for enterprise-grade data streaming capabilities.