Skip to main content

Subscribe to WebSocket Events

Once you've made your first RPC call, you can stream real-time blockchain events using WebSocket connections. This enables your application to react instantly to account changes, new transactions, slot updates, and program executions.

Prerequisites
Default API Key View
Your default API key from the API keys page

Understanding WebSocket Endpoints​

Syndica provides WebSocket endpoints for real-time data streaming on both mainnet and devnet. Your default API key works with both networks.

Mainnet:

wss://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY

Devnet:

wss://solana-devnet.api.syndica.io/api-key/YOUR_API_KEY

WebSocket connections are automatically routed to your nearest Edge Gateway across four global regions: Northern Virginia (us-east-1), Oregon (us-west-2), London (eu-west-2), and Singapore (ap-southeast-1).

How WebSocket Subscriptions Work​

WebSocket subscriptions follow a simple pattern:

  1. Connect - Establish a WebSocket connection to the endpoint
  2. Subscribe - Send a subscription request specifying the event type and filters
  3. Receive - Get a subscription ID confirming your subscription
  4. Stream - Receive real-time notifications as events occur
  5. Unsubscribe - Close the subscription when done

All subscription requests use JSON-RPC 2.0 format, just like HTTP RPC calls.

Subscribe to Slot Updates​

Monitor blockchain progression by subscribing to slot changes. This is useful for tracking network state and timing operations.

const ws = new WebSocket(
  'wss://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY'
);

ws.onopen = () => {
  console.log('Connected to Syndica WebSocket');
  
  // Subscribe to slot updates
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'slotSubscribe'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.result) {
    // Subscription confirmation
    console.log('Subscription ID:', data.result);
  } else if (data.method === 'slotNotification') {
    // Slot update received
    console.log('Current slot:', data.params.result.slot);
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket connection closed');
};

Subscription Confirmation:

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

Slot Notification:

{
  "jsonrpc": "2.0",
  "method": "slotNotification",
  "params": {
    "result": {
      "parent": 287654320,
      "root": 287654288,
      "slot": 287654321
    },
    "subscription": 123456
  }
}

Available Subscription Types​

Beyond slot updates, Syndica supports all standard Solana WebSocket subscriptions:

  • accountSubscribe - Monitor specific accounts for balance changes, data updates, or ownership transfers
  • logsSubscribe - Track program execution logs for debugging and monitoring
  • programSubscribe - Subscribe to all accounts owned by a specific program
  • signatureSubscribe - Get notified when a transaction is confirmed
  • rootSubscribe - Track root slot changes for finalized blocks

See the WebSocket Methods reference for detailed documentation on each subscription type.

Unsubscribe from Events​

Stop receiving notifications by unsubscribing with the subscription ID:

// Unsubscribe from slot updates
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 4,
  method: 'slotUnsubscribe',
  params: [123456] // Use your subscription ID
}));

Each subscription type has a corresponding unsubscribe method: slotUnsubscribe, accountUnsubscribe, logsUnsubscribe, etc.

Stream More with ChainStream​

For applications that need additional event types, flexibility, and reliability, Syndica offers ChainStream—a streaming service that aggregates data from multiple validators and provides access to transaction, slot, and block notifications with advanced filtering options.

ChainStream is ideal for:

  • High-frequency trading applications
  • Transaction monitoring at scale
  • Applications requiring guaranteed delivery
  • Multi-validator redundancy

Learn more in the ChainStream guide.

Monitor Your Connections​

WebSocket Analytics Screen
Real-time WebSocket analytics dashboard

Track your WebSocket activity on the analytics dashboard:

  • Active connection count and subscription status
  • Message and data throughput in real-time
  • Historical usage patterns and trends
  • Connection health and error rates

Access your WebSocket analytics from your Stack's analytics page in the dashboard.

FAQ and Troubleshooting​

How do I authenticate WebSocket connections?

Include your API key in the WebSocket URL path: wss://solana-mainnet.api.syndica.io/api-key/YOUR_API_KEY. Authentication happens during the initial connection, not per-message.

What's the difference between WebSocket subscriptions and ChainStream?

Standard WebSocket subscriptions connect directly to whichever validator your connection reaches and expose the base Solana RPC methods (slotSubscribe, logsSubscribe, accountSubscribe, etc.). That keeps them lightweight and available on every plan, but you own the operational work: detecting missed slots, replaying signatures, managing ordering, and reconciling state when the validator you hit lags or restarts.

ChainStream is a separate endpoint (wss://solana-mainnet.chainstream.syndica.io/api-key/...) that fans out each subscription across multiple validators. The service delivers the earliest notification using a "fastest wins" strategy, backfills if a source misses data, and deduplicates events before they reach your client. It also unlocks capabilities that standard WebSockets don't provide:

  • transactionsSubscribe, blockSubscribe, and encodedBlockSubscribe for full transaction/block payload streaming
  • Rich account filtering via all, oneOf, and exclude matchers plus the verified flag for multi-validator confirmation
  • Built-in delivery guarantees so you no longer maintain your own resend buffers or roll-your-own analytics

ChainStream requires Scale Mode or higher (see plans and pricing); standard WebSockets work on all plans.

Can I have multiple subscriptions on one WebSocket connection?

Yes. A single connection can host hundreds of subscriptions (Standard Mode: up to 100 per connection; Scale Mode: up to 600). Each *Subscribe call returns a numeric ID—store it so you can *Unsubscribe later and keep the connection within limits. Reuse connections when possible to avoid extra handshakes, but remove idle subscriptions so they don't count toward your plan's method-specific caps (see Rate Limits and plans/pricing for details). If a connection closes, reconnect once and resubscribe using the IDs you tracked.

Why did my WebSocket connection close?

Connections close automatically when they violate one of our guardrails:

  • No active subscriptions: After the handshake we wait ~5 seconds for your client to create a subscription or send a keepalive. If nothing happens, the socket is recycled.
  • Inactivity timeout: If we don't observe any traffic (notifications, client messages, or ping/pong) for 60 seconds, we close the connection. Send ping frames every 20‑30 seconds to keep the session warm.
  • Credential or auth errors: Missing/invalid API keys or revoked credentials trigger immediate disconnects—check for 401 errors during the initial upgrade.
  • Connection limits exceeded: Standard Mode allows up to 100 concurrent WebSocket connections and 100 total subscriptions; Scale Mode raises those limits to 300 connections and 600 subscriptions. Method-specific caps also apply—see Rate Limits and plans/pricing for the full matrix.

Always implement reconnection logic with exponential backoff, resubscribe on reconnect, and see Error Handling plus Observability for guidance on interpreting disconnects.

What commitment level should I use?

Choose based on your use case:

  • Processed: Fastest notifications, ideal for price feeds and applications that can tolerate potential rollbacks
  • Confirmed: Balanced option with network consensus, good for most applications
  • Finalized: Guaranteed by network finality, ~13 second delay, required for financial settlement

See commitment levels documentation for details.

How do I reduce bandwidth usage?

Syndica automatically offers Per-Message Deflate compression (RFC 7692) on every WebSocket endpoint, typically reducing bandwidth by 70-90%. Most client libraries negotiate this extension automatically, but some require you to enable compression explicitly or install an additional dependency—check your client's docs to confirm it advertises permessage-deflate during the handshake.

Are there rate limits for WebSocket subscriptions?

Yes. Each plan defines ceilings for active WebSocket connections, total subscriptions, and per-method concurrency, plus optional per-IP enforcement. Review the WebSocket limits table for your tier, check plans/pricing for current allowances, and use custom rate limits to set credential-specific caps (connections, subscriptions, or per-method) when you need finer control.

How do I subscribe to multiple event types on one connection?

You can create multiple subscriptions on a single WebSocket connection. Each subscription receives its own ID:

// Subscribe to both slots and accounts
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'slotSubscribe'
}));

ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 2,
  method: 'accountSubscribe',
  params: ['YourAccountPublicKeyHere', { commitment: 'confirmed' }]
}));

See the WebSocket Methods reference for all available subscription types.

What You Can Do Next​

Now that you can stream real-time events: