Skip to main content

Block Subscriptions

Block subscriptions provide real-time notifications whenever a new block is processed by Syndica's validators. Each notification contains block metadata including slot information, blockhash, rewards, transaction counts, and timestamps—without the full transaction payload data.

For applications requiring complete block data including all transactions with their full instruction sets, logs, and account changes, see encoded block subscriptions.

Methods:

Common use cases:

  • Tracking block production and validator performance
  • Monitoring block height and slot progression for blockchain state synchronization
  • Triggering application processes that need to run on each new block
  • Observing validator rewards and staking information
  • Building block explorers and analytics dashboards

Subscribe Request​

Method: blocksSubscribe

Parameters:

network (string, required)

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

verified (boolean, optional)

Only receive verified blocks (finalized by supermajority). Defaults to false.

info

For block subscriptions, the verified parameter has minimal impact since block data is already verified by the cluster consensus process.

Example Subscribe Request​

{
  "jsonrpc": "2.0",
  "id": 123,
  "method": "blocksSubscribe",
  "params": {
    "network": "solana-mainnet",
    "verified": false
  }
}

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": 32026100100140,
  "id": 123
}

Notification Structure​

{
  "jsonrpc": "2.0",
  "method": "blockNotification",
  "params": {
    "subscription": 32026100100140,
    "result": {
      "context": {
        "nodeTime": "2025-11-12T21:13:24.191443489Z"
      },
      "value": {
        "slot": 379670681,
        "blockhash": "EwL4joCFuUai4y7oqJLLJztRwm1G3gHzvj5cA4GzWZuQ",
        "rewards": [{
          "pubkey": "q9XWcZ7T1wP4bW9SB4XgNNwjnFEJ982nE8aVbbNuwot",
          "lamports": 14488196,
          "postBalance": 94791313957,
          "rewardType": 0,
          "commission": null
        }],
        "blockTime": "2025-11-12T21:13:23Z",
        "blockHeight": 357824147,
        "parentSlot": 379670680,
        "parentBlockhash": "FbJssKZiDZb4bAKiRochj4ykAMC3pp92xXQtE2Ty1h6N",
        "executedTransactionCount": 1104,
        "numPartitions": null,
        "entryCount": null
      }
    }
  }
}

context Object​

nodeTime (string)

ISO 8601 timestamp when the validator processed this block

value Object​

slot (number)

The slot number for this block

blockhash (string)

The blockhash for this block

blockTime (string)

ISO 8601 timestamp when the block was produced

blockHeight (number)

The block height (number of blocks since genesis)

parentSlot (number)

The slot number of the parent block

previousBlockhash (string)

The blockhash of the previous block

executedTransactionCount (number)

Number of transactions executed in this block

numPartitions (number, nullable)

Number of partitions (may be null)

entryCount (number, nullable)

Number of entries (may be null)

rewards (array)

Array of validator rewards for this block, each containing:

pubkey (string) — Validator's public key

lamports (number) — Reward amount in lamports

postBalance (number) — Validator's balance after reward

rewardType (number) — Type of reward (0 for staking rewards)

commission (number, nullable) — Commission rate (if applicable)

Example Notification​

{
  "jsonrpc": "2.0",
  "method": "blockNotification",
  "params": {
    "subscription": 32026100100140,
    "result": {
      "context": {
        "nodeTime": "2025-05-15T22:25:32.124724202Z"
      },
      "value": {
        "slot": 340268123,
        "blockhash": "4vvb3Wa2NG8NiniyPrk4bKnXDGpAaxkdQmoBUDt2yCgY",
        "rewards": [
          {
            "pubkey": "BkoS26vBuaXnSowACdChi4WKid8UwmuPNhEJWa8KsLHd",
            "lamports": 40545537,
            "postBalance": 95810488820,
            "rewardType": 0,
            "commission": null
          }
        ],
        "blockTime": "2025-05-15T22:25:31Z",
        "blockHeight": 318487251,
        "parentSlot": 340268122,
        "parentBlockhash": "7tnEf9LauEcVwu9XGZrnu1PSb7AvhphYPyXj1bScmEAw",
        "executedTransactionCount": 1730,
        "numPartitions": null,
        "entryCount": null
      }
    }
  }
}

Unsubscribe Request​

Method: blocksUnsubscribe

Parameters:

subscriptionId (number, required)

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

Example Unsubscribe Request​

{
  "jsonrpc": "2.0",
  "id": 124,
  "method": "blocksUnsubscribe",
  "params": [32026100100140]
}

Example Unsubscribe Response​

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

FAQ and Troubleshooting​

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.

What latency should I expect from ChainStream?

Once a validator feeding ChainStream timestamps an event at the geyser interface, it reaches clients co-located in the same AWS region in ≤10 ms (round-trip latency under 10 ms). Across typical public-internet links you should expect roughly 50–100 ms end-to-end latency, depending on your network path and geography. To measure your actual performance, compare the nodeTime field (UTC timestamp) in each ChainStream message with your local clock and log the delta over time.

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.

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​