The blockSubscribe method opens a stream that emits a notification every time a new block is confirmed or finalized. Pair it with blockUnsubscribe to stop receiving notifications.

Block notifications are large: a single confirmed Solana block routinely runs into multiple megabytes (~1–5 MB per notification with transactionDetails: "full"). Filter with mentionsAccountOrProgram or reduce payload size with transactionDetails: "signatures" / "none" whenever possible.

Parameters

• filter: string | object - Filter describing which blocks to receive:

  • "all" - Include every transaction in the block.
  • { "mentionsAccountOrProgram": <base58 pubkey> } - Only include transactions that reference the given account or program. If a block contains no matching transactions, no notification is emitted.

• config (optional): object - Configuration object containing:

  • commitment: string - The commitment level. One of confirmed, finalized. Defaults to finalized. processed is not supported for this subscription.
  • encoding: string - Encoding for transaction data. One of json, jsonParsed, base58, base64. Defaults to json. Note: base64+zstd is not supported by blockSubscribe (it applies to account-data encodings only).
  • transactionDetails: string - Level of transaction detail to return. One of full, accounts, signatures, none. Defaults to full.
  • maxSupportedTransactionVersion: number - The maximum transaction version to return. Set to 0 to receive versioned transactions. If a block contains a transaction with a higher version and this field is not set, that block's block field will be null and its err field will contain UnsupportedTransactionVersion.
  • showRewards: boolean - Whether to include the block's rewards array. Defaults to false.

Request

// initiate websocket stream against the streaming endpoint
wscat -c wss://solana-mainnet.streaming.alchemy.com/v2/<-- ALCHEMY APP API KEY -->
 
// then call subscription
{"jsonrpc":"2.0","id":1,"method":"blockSubscribe","params":["all",{"commitment":"confirmed","encoding":"base64","transactionDetails":"signatures","showRewards":false,"maxSupportedTransactionVersion":0}]}

// @solana/web3.js does not wrap blockSubscribe, so use a raw WebSocket.
import WebSocket from 'ws'
 
const ws = new WebSocket(
  'wss://solana-mainnet.streaming.alchemy.com/v2/<-- ALCHEMY APP API KEY -->'
)
 
ws.on('open', () => {
  ws.send(
    JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'blockSubscribe',
      params: [
        'all',
        {
          commitment: 'confirmed',
          encoding: 'base64',
          transactionDetails: 'signatures',
          showRewards: false,
          maxSupportedTransactionVersion: 0
        }
      ]
    })
  )
})
 
ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString())
  if (msg.method === 'blockNotification') {
    const { slot, block, err } = msg.params.result.value
    console.log('Block notification at slot', slot, {
      blockhash: block?.blockhash,
      parentSlot: block?.parentSlot,
      txCount: block?.signatures?.length,
      err
    })
  } else {
    console.log('subscribe response', msg)
  }
})

Result

// subscribe response
{"jsonrpc":"2.0","result":280,"id":1}
 
// notification
{
  "jsonrpc": "2.0",
  "method": "blockNotification",
  "params": {
    "subscription": 280,
    "result": {
      "context": { "slot": 441702602 },
      "value": {
        "slot": 441702602,
        "block": {
          "previousBlockhash": "V9999asiQtzKZFRaCqAEYw7uWaaPKbKEo8ujuRBFgPB",
          "blockhash": "FRR9TCXheEm3Bpu6FcGepMo9KdrtgiCkUm6Ur9Ec2B8S",
          "parentSlot": 441702601,
          "signatures": [
            "39utTm8Wq5sXFPKgqvCvdpm46gQkfkL2hzcza1MU6ziD9Zteb1i38E89PzLwDVwnW4E4i1h7N2ujr4rv4pasH2nt",
            "3ki2ebyMMPGMhY9ubiwhFaMbeNzv3UXQmRipq9dkG1V57DkxphWc2rzQxTfhuRJr1wY2cZG2Qn4geftGk2fX3wHe",
            "3xUVBEGsaihVPvUX8XyaD46tyutxzYdHysZ1E54A45JTnE7r2SqA4xTREXFkkkxP4WW9K4dTpWzGbJKjqyW6a3Yg"
          ],
          "blockTime": 1787687322,
          "blockHeight": 419751272
        },
        "err": null
      }
    }
  }
}

Unsubscribe

Use blockUnsubscribe with the subscription id returned by blockSubscribe to cancel the stream.

• subscription_id: number - The subscription id to cancel.

{"jsonrpc":"2.0","id":1,"method":"blockUnsubscribe","params":[subscription_id]}

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