---
title: blockSubscribe
description:
  Subscribe to block notifications as blocks reach confirmed or finalized
  commitment.
url: /docs/rpc/websocket/blocksubscribe
type: reference
hideTableOfContents: true
---

Subscribe to receive notifications when a new block reaches `confirmed` or
`finalized` commitment.

<Callout type="info" title="Source">
  [`block_subscribe`](https://github.com/anza-xyz/agave/blob/v3.1.8/rpc/src/rpc_pubsub.rs#L545)
</Callout>

<Callout type="warn" title="Unstable Method">
  Agave documents this as an [unstable RPC PubSub `blockSubscribe`
  subscription](https://github.com/anza-xyz/agave/blob/v3.1.8/validator/src/commands/run/args/pub_sub_config.rs#L82-L86).
  It is only available if the validator was started with
  `--rpc-pubsub-enable-block-subscription`, which also requires
  `--enable-rpc-transaction-history`.
</Callout>

<APIMethod>

```jsonc !!request curl
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blockSubscribe",
  "params": [
    // !hover(1:3) filter
    {
      "mentionsAccountOrProgram": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"
    },
    // !hover(1:7) config
    {
      // !hover commitment
      "commitment": "confirmed",
      // !hover encoding
      "encoding": "base64",
      // !hover transactionDetails
      "transactionDetails": "full",
      // !hover maxSupportedTransactionVersion
      "maxSupportedTransactionVersion": 0,
      // !hover showRewards
      "showRewards": true
    }
  ]
}
```

```rs !!request title="Rust"
use anyhow::Result;
use futures::StreamExt;
use solana_client::{
    nonblocking::pubsub_client::PubsubClient,
    rpc_config::{RpcBlockSubscribeConfig, RpcBlockSubscribeFilter},
};
use solana_commitment_config::CommitmentConfig;
use solana_transaction_status::TransactionDetails;

#[tokio::main]
async fn main() -> Result<()> {
    let pubsub_client = PubsubClient::new("wss://api.devnet.solana.com/").await?;

    let filter = RpcBlockSubscribeFilter::MentionsAccountOrProgram(
        "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op".to_string(),
    );

    let config = RpcBlockSubscribeConfig {
        commitment: Some(CommitmentConfig::confirmed()),
        encoding: None,
        transaction_details: Some(TransactionDetails::Full),
        show_rewards: Some(true),
        max_supported_transaction_version: Some(0),
    };

    let (mut notifications, unsubscribe) = pubsub_client
        .block_subscribe(filter, Some(config))
        .await?;

    while let Some(notification) = notifications.next().await {
        println!("{:?}", notification);
    }

    unsubscribe().await;

    Ok(())
}
```

### !params

#### !! filter

!type string | object !required

Filter describing which blocks should produce notifications.

- `all` returns every matching block
- `{ "mentionsAccountOrProgram": <pubkey> }` returns only blocks that contain a
  transaction mentioning the provided base-58 encoded address

#### !! config

!type object

Optional configuration object.

##### !! commitment

!type string !values confirmed finalized !default finalized

The commitment describes how finalized a block is at that point in time. See
[Configuring State Commitment](/docs/rpc#configuring-state-commitment).

This method does not accept `processed`.

##### !! encoding

!type string !values binary base58 base64 json jsonParsed !default base64

Encoding format for each returned transaction.

- `jsonParsed` uses program-specific parsers for
  `transaction.message.instructions` when available
- If no parser is available, the RPC node falls back to standard JSON
  instruction fields
- `binary` is a deprecated legacy alias for `base58`

##### !! transactionDetails

!type string !values full accounts signatures none !default full

Level of transaction detail to return.

- `accounts` returns signatures plus an annotated account list for each
  transaction
- `signatures` omits full transaction objects and returns only block signatures
- `none` omits both transaction objects and signatures

##### !! maxSupportedTransactionVersion

!type number

Highest transaction version your client supports. If omitted, only legacy
transactions can be returned. If a matching block requires a higher transaction
version, the notification populates `value.err` instead of returning block data.

This field accepts any `u8`. Today, the versioned transactions exposed by RPC
use version `0`.

##### !! showRewards

!type bool !values true false !default false

Whether to populate the block `rewards` array. If omitted, the response omits
rewards.

### !!result

```jsonc !response
{
  "jsonrpc": "2.0",
  // !hover result
  "result": 0,
  "id": 1
}
```

!type integer

Subscription id. Pass this to
[blockUnsubscribe](/docs/rpc/websocket/blockunsubscribe).

</APIMethod>

### Notification format

Notifications are delivered as `blockNotification`.

The example below was captured from a subscription with
`transactionDetails: "full"`, `showRewards: true`, and
`maxSupportedTransactionVersion: 0`.

<CodeReference>

```jsonc !!
{
  // !hover jsonrpc
  "jsonrpc": "2.0",
  // !hover method
  "method": "blockNotification",
  // !hover(1:60) params
  "params": {
    // !hover(1:57) params.result
    "result": {
      // !hover(1:3) params.result.context
      "context": {
        // !hover params.result.context.slot
        "slot": 3537
      },
      // !hover(1:52) params.result.value
      "value": {
        // !hover params.result.value.slot
        "slot": 3537,
        // !hover params.result.value.block
        "block": {
          "previousBlockhash": "J48KViVe4DpE5Xgkv5weChwBcsxzqmdZscUBE7eoeoCW",
          "blockhash": "51kbSjt8yVnmTWLzXSYyNS6KLuLhbFZuyoLJ36jz3Wpo",
          "parentSlot": 3536,
          "transactions": [
            {
              "transaction": [
                "AZTncP5v/zgbhG9gjGTB7U+lcT9ZqN70DXRGzCeoVqQ7ZOSUMDpfqiyIX2zKlyZefFYLLLkWJZfodF9VH6IgtggBAAEDB7ff3j2h8EhabhQ6/UsQ9Ff0qHRbDoFi8nyq1L7LuCrmza099j6XR/M+lQUi1PxTs6S67zfyGIc61J4Fgbx1gwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/WOyFspSu8OOPcxRVf/2cUIqYc/gtPOkSZH9Wx6m0dsBAgIAAQwCAAAAgJaYAAAAAAA=",
                "base64"
              ],
              "meta": {
                "err": null,
                "status": {
                  "Ok": null
                },
                "fee": 5000,
                "preBalances": [9959990000, 40000000, 1],
                "postBalances": [9949985000, 50000000, 1],
                "innerInstructions": [],
                "logMessages": [
                  "Program 11111111111111111111111111111111 invoke [1]",
                  "Program 11111111111111111111111111111111 success"
                ],
                "preTokenBalances": [],
                "postTokenBalances": [],
                "rewards": [],
                "loadedAddresses": {
                  "writable": [],
                  "readonly": []
                },
                "computeUnitsConsumed": 150,
                "costUnits": 1481
              },
              "version": "legacy"
            }
          ],
          "rewards": [
            {
              "pubkey": "BpdYYo2Vw1NVbzE2DqJxCX2xEfr42xvMYFU2dKd1CW57",
              "lamports": 7500,
              "postBalance": 499982330000,
              "rewardType": "Fee",
              "commission": null
            }
          ],
          "blockTime": 1774645307,
          "blockHeight": 3537
        },
        // !hover params.result.value.err
        "err": null
      }
    },
    // !hover params.subscription
    "subscription": 13
  }
}
```

## !reference

### !! jsonrpc

!type string

Always `"2.0"`.

### !! method

!type string

Always `"blockNotification"`.

### !! params

!type object

Notification wrapper with the block update payload and the subscription id.

#### !! result

!type object

Notification result object with `context` and `value`. For PubSub notifications,
`context` includes `slot` and omits `apiVersion`.

##### !! context

!type object

Context for the slot that triggered the notification.

###### !! slot

!type u64

Slot associated with the notification.

##### !! value

!type object

Block update payload for the subscribed filter.

###### !! slot

!type u64

Slot of the block update.

###### !! block

!type object | null

Block data using the same structure documented for
[getBlock](/docs/rpc/http/getblock). When `err` is non-null, this may be `null`.

###### !! err

!type null | "BlockStoreError" | object

`null` on success, `"BlockStoreError"` if the block could not be loaded, or an
object such as `{ "UnsupportedTransactionVersion": 0 }` when the block contains
a transaction version above `maxSupportedTransactionVersion`.

#### !! subscription

!type integer

Subscription id that produced this notification.

</CodeReference>