Skip to main content

Slot Subscriptions

Slot subscriptions provide real-time notifications whenever a slot changes status at different commitment levels—processed, confirmed, or finalized. Each notification includes the current slot number along with parent and root slot information, enabling you to track blockchain progression and finality in real-time.

Slots are the fundamental time unit in Solana—each slot represents an opportunity for a validator to produce a block. A slot notification indicates when a slot has advanced to a new commitment level, helping your application understand the blockchain's current state and finality status.

Methods:

Common use cases:

  • Tracking blockchain progression and synchronization state
  • Monitoring when slots advance to confirmed or finalized states
  • Building block explorers that need real-time slot progression data
  • Detecting slot skips and validator performance issues
  • Triggering actions when the chain reaches specific commitment levels
  • Coordinating application state updates with blockchain finality

Subscribe Request​

Method: slotUpdatesSubscribe

Parameters:

network (string, required)

The Solana network to subscribe to: solana-mainnet or solana-devnet

verified (boolean, optional)

When true, ChainStream waits for multiple validators to report the same slot status before sending a notification, providing additional data correctness guarantees. This can delay notifications by up to ~400ms.

When false (default), slot updates are streamed as quickly as possible without multi-validator verification.

Defaults to false.

filter (object, optional)

Filtering options to control which slot notifications to receive.

commitment (string) — The commitment level of slot updates to receive: processed, confirmed, or finalized. Determines which slot status changes trigger notifications. Defaults to processed.

includeStatuses (array of strings) — Optionally specify which slot statuses to include in notifications. Valid values: processed, confirmed, finalized, dead, first_shred_received, created_bank, completed. By default, only processed, confirmed, and finalized are included. You must provide at least one status.

info

The commitment filter determines which commitment-level slot status updates you receive. Use includeStatuses to receive notifications for additional internal slot states like dead, first_shred_received, created_bank, and completed.

Example Subscribe Request​

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotUpdatesSubscribe",
  "params": {
    "network": "solana-mainnet",
    "verified": false
  }
}
With confirmed commitment
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotUpdatesSubscribe",
  "params": {
    "network": "solana-mainnet",
    "verified": false,
    "filter": {
      "commitment": "confirmed"
    }
  }
}
With verified mode
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotUpdatesSubscribe",
  "params": {
    "network": "solana-mainnet",
    "verified": true,
    "filter": {
      "commitment": "processed"
    }
  }
}
With all slot statuses including internal states
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotUpdatesSubscribe",
  "params": {
    "network": "solana-mainnet",
    "verified": false,
    "filter": {
      "includeStatuses": [
        "processed",
        "confirmed",
        "finalized",
        "dead",
        "first_shred_received",
        "created_bank",
        "completed"
      ]
    }
  }
}

Example Subscribe Response​

tip

Save the subscription ID if you need to explicitly unsubscribe before disconnecting. Disconnecting the WebSocket automatically unsubscribes all active subscriptions.

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

Notification Structure​

{
  "jsonrpc": "2.0",
  "method": "slotUpdateNotification",
  "params": {
    "subscription": 892647103201567,
    "result": {
      "context": {
        "nodeTime": "2025-11-01T18:42:15.321456789Z"
      },
      "value": {
        "slot": 287654321,
        "parent": 287654320,
        "status": "processed"
      }
    }
  }
}

context Object​

nodeTime (string)

ISO 8601 timestamp when the validator processed this slot update

value Object​

slot (number)

The current slot number that has reached the specified status

parent (number | null)

The parent slot number. May be null for certain slot status updates.

status (string)

The slot's current status. Can be:

  • processed - Slot has been processed by the validator
  • confirmed - Slot has been confirmed by the cluster
  • finalized - Slot has been finalized and rooted
  • dead - Slot was skipped or abandoned
  • first_shred_received - First shred of the slot received
  • created_bank - Bank created for the slot
  • completed - Slot processing completed
info

By default, only processed, confirmed, and finalized statuses are included. Use the filter.includeStatuses parameter to receive notifications for other statuses like dead, first_shred_received, created_bank, and completed.

Example Notification​

Processed slot notification
{
  "jsonrpc": "2.0",
  "method": "slotUpdateNotification",
  "params": {
    "subscription": 892647103201567,
    "result": {
      "context": {
        "nodeTime": "2025-11-01T18:42:15.321456789Z"
      },
      "value": {
        "slot": 287654321,
        "parent": 287654320,
        "status": "processed"
      }
    }
  }
}
Confirmed slot notification
{
  "jsonrpc": "2.0",
  "method": "slotUpdateNotification",
  "params": {
    "subscription": 892647103201567,
    "result": {
      "context": {
        "nodeTime": "2025-11-01T18:42:16.124567890Z"
      },
      "value": {
        "slot": 287654310,
        "parent": 287654309,
        "status": "confirmed"
      }
    }
  }
}
Finalized slot notification
{
  "jsonrpc": "2.0",
  "method": "slotUpdateNotification",
  "params": {
    "subscription": 892647103201567,
    "result": {
      "context": {
        "nodeTime": "2025-11-01T18:42:28.987654321Z"
      },
      "value": {
        "slot": 287654290,
        "parent": 287654289,
        "status": "finalized"
      }
    }
  }
}
First shred received notification
{
  "jsonrpc": "2.0",
  "method": "slotUpdateNotification",
  "params": {
    "subscription": 892647103201567,
    "result": {
      "context": {
        "nodeTime": "2025-11-01T18:42:56.963777914Z"
      },
      "value": {
        "slot": 287654318,
        "parent": null,
        "status": "first_shred_received"
      }
    }
  }
}

Unsubscribe Request​

Method: slotUpdatesUnsubscribe

Parameters:

subscriptionId (number, required)

The subscription ID returned from the subscribe response (passed as array parameter).

Example Unsubscribe Request​

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "slotUpdatesUnsubscribe",
  "params": [892647103201567]
}

Example Unsubscribe Response​

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 2
}

FAQ and Troubleshooting​

What commitment level should I use with ChainStream?

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.

Review the commitment levels documentation for deeper detail.

Why is my ChainStream connection failing?

Common causes:

  • Scale Mode not enabled (ChainStream requires it—upgrade or review plans/pricing).
  • ChainStream not enabled on your dashboard’s ChainStream API page.
  • No available streams / Error 7429 (subscription method exceeded limit) (all subscriptions in use). Close unused streams or enable additional streams—see plans/pricing for details.
  • API key missing ChainStream permissions.

Check the ChainStream API page for subscription status and limits after resolving the above.

How many concurrent ChainStream streams can I have?

Scale Mode includes one ChainStream subscription, and you can add up to nine additional subscriptions ($0.14/hour each) for a total of ten concurrent streams per account. Each subscription maps to one WebSocket connection that can host multiple event subscriptions. Configure custom rate limits for ChainStream per API key as needed, and review plans/pricing for the current limits by tier.

What happens if a validator goes offline when using ChainStream?

ChainStream aggregates data from multiple validators and automatically routes around node failures, so you keep receiving events from healthy validators without interruption—one of the primary benefits over single-node WebSocket connections.

How do I use ChainStream with devnet?

Connect to wss://solana-devnet.chainstream.syndica.io/api-key/YOUR_API_KEY and set network: "solana-devnet" in your transactionsSubscribe (or other) params. The rest of the request shape matches mainnet usage, including verified, commitment, and filter objects.

What You Can Do Next​