blockSubscribe

Subscribe to receive notification anytime a new block is confirmed or finalized.

Parameters

filter (string | object, required)

Description: Filter criteria for the logs to receive results based on account type.

String Options:

• all: Include all transactions in the block.

Object Options:

A JSON object with the following field:

• mentionsAccountOrProgram (string): Return only transactions that mention the provided public key (as a base-58 encoded string). If no mentions occur in a given block, no notification will be sent.

---

object (optional)

Description: Configuration object containing the following fields:

• commitment (string, optional): Default: finalized. Note: processed is not supported.

• encoding (string, optional): Default: json. Specifies the encoding format for each returned transaction. Values:

  • json

  • jsonParsed

  • base58

  • base64

  Details:

  • jsonParsed attempts to use program-specific instruction parsers to return more human-readable and explicit data in the transaction.message.instructions list.

  • If jsonParsed is requested but a parser cannot be found, the instruction falls back to regular JSON encoding (accounts, data, and programIdIndex fields).

• transactionDetails (string, optional): Default: full. Specifies the level of transaction detail to return. Values:

  • full

  • accounts

  • signatures

  • none

  Details:

  • If accounts is requested, transaction details only include signatures and an annotated list of accounts in each transaction.

  • Transaction metadata is limited to: fee, err, pre_balances, post_balances, pre_token_balances, and post_token_balances.

• maxSupportedTransactionVersion (number, optional): Specifies the maximum transaction version to return in responses.

  Details:

  • If the requested block contains a transaction with a higher version, an error will be returned.

  • If omitted, only legacy transactions will be returned, and a block containing any versioned transaction will prompt an error.

• showRewards (bool, optional): Whether to populate the rewards array. Default behavior includes rewards if this parameter is not provided.

---

Result

Returns an integer which serves as the subscription ID. This ID is required to unsubscribe.

---

Code Samples

Request Example 1 (Subscribe to all transactions in a block):

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "blockSubscribe",
  "params": ["all"]
}

Request Example 2 (Filter by account and include optional configuration):

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "blockSubscribe",
  "params": [
    {
      "mentionsAccountOrProgram": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"
    },
    {
      "commitment": "confirmed",
      "encoding": "base64",
      "showRewards": true,
      "transactionDetails": "full"
    }
  ]
}

Response Example:

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

---

Notification Format

The notification is an object with the following fields:

• slot (u64): The corresponding slot.

• err (object | null): Error if an issue occurs while publishing the notification; otherwise null.

• block (object | null): A block object as seen in the getBlock RPC HTTP method.

---

Example Notification

{
  "jsonrpc": "2.0",
  "method": "blockNotification",
  "params": {
    "result": {
      "context": {
        "slot": 112301554
      },
      "value": {
        "slot": 112301554,
        "block": {
          "previousBlockhash": "GJp125YAN4ufCSUvZJVdCyWQJ7RPWMmwxoyUQySydZA",
          "blockhash": "6ojMHjctdqfB55JDpEpqfHnP96fiaHEcvzEQ2NNcxzHP",
          "parentSlot": 112301553,
          "transactions": [
            {
              "transaction": [
                "OpltwoUvWxYi1P2U8vbIdE/aPntjYo5Aa0VQ2JJyeJE2g9Vvxk8dDGgFMruYfDu8/IfUWb0REppTe7IpAuuLRgIBAAkWnj4KHRpEWWW7gvO1c0BHy06wZi2g7/DLqpEtkRsThAXIdBbhXCLvltw50ZnjDx2hzw74NVn49kmpYj2VZHQJoeJoYJqaKcvuxCi/2i4yywedcVNDWkM84Iuw+cEn9/ROCrXY4qBFI9dveEERQ1c4kdU46xjxj9Vi+QXkb2Kx45QFVkG4Y7HHsoS6WNUiw2m4ffnMNnOVdF9tJht7oeuEfDMuUEaO7l9JeUxppCvrGk3CP45saO51gkwVYEgKzhpKjCx3rgsYxNR81fY4hnUQXSbbc2Y55FkwgRBpVvQK7/+clR4Gjhd3L4y+OtPl7QF93Akg1LaU9wRMs5nvfDFlggqI9PqJl+IvVWrNRdBbPS8LIIhcwbRTkSbqlJQWxYg3Bo2CTVbw7rt1ZubuHWWp0mD/UJpLXGm2JprWTePNULzHu67sfqaWF99LwmwjTyYEkqkRt1T0Je5VzHgJs0N5jY4iIU9K3lMqvrKOIn/2zEMZ+ol2gdgjshx+sphIyhw65F3J/Dbzk04LLkK+CULmN571Y+hFlXF2ke0BIuUG6AUF+4214Cu7FXnqo3rkxEHDZAk0lRrAJ8X/Z+iwuwI5cgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpDLAp8axcEkaQkLDKRoWxqp8XLNZSKial7Rk+ELAVVKWoWLRXRZ+OIggu0OzMExvVLE5VHqy71FNHq4gGitkiKYNFWSLIE4qGfdFLZXy/6hwS+wq9ewjikCpd//C9BcCL7Wl0iQdUslxNVCBZHnCoPYih9JXvGefOb9WWnjGy14sG9j70+RSVx6BlkFELWwFvIlWR/tHn3EhHAuL0inS2pwX7ZQTAU6gDVaoqbR2EiJ47cKoPycBNvHLoKxoY9AZaBjPl6q8SKQJSFyFd9n44opAgI6zMTjYF/8Ok4VpXEESp3QaoUyTI9sOJ6oFP6f4dwnvQelgXS+AEfAsHsKXxGAIUDQENAgMEBQAGBwgIDg8IBJCER3QXl1AVDBADCQoOAAQLERITDAjb7ugh3gOuTy==",
                "base64"
              ],
              "meta": {
                "err": null,
                "status": {
                  "Ok": null
                },
                "fee": 5000
              }
            }
          ],
          "blockTime": 1639926816,
          "blockHeight": 101210751
        },
        "err": null
      }
    },
    "subscription": 14
  }
}