> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscribe

> Subscribe to accounts, transactions, blocks, and slot updates to receive real-time notifications using the high-performance gRPC API.

<hide>
  ## Endpoints

  gRPC services are available on mainnet and devnet with the following URLs:

  * **Mainnet** `https://laserstream-mainnet.helius-rpc.com:443`
  * **Devnet** `https://laserstream-devnet.helius-rpc.com:443`
</hide>

## Authorizations

**x-token** `string` *required*

Your Helius API key. You can get one for free in the
[dashboard](https://dashboard.helius.dev/api-keys).

## Message

The gRPC API supports multiple subscription types that can be combined in a single request:

**accounts** `object`

Subscribe to account updates. Returns data when specified accounts are
modified.

**properties**

**account** `array`

Array of account pubkeys to monitor.

**owner** `array`

Array of owner pubkeys to monitor (all accounts owned by these programs).

**filters** `object`

Optional filters to apply.

**filter options**

**memcmp** `object`

Filter by specific bytes at an offset in account data.

**properties**

**offset** `integer`

Position in bytes to start comparing data.

**bytes** `string`

The data to compare against (bytes format).

**base58** `string`

The data to compare against (base58 format).

**base64** `string`

The data to compare against (base64 format).

**datasize** `integer`

Filter by exact account data size in bytes.

**token\_account\_state** `boolean`

Filter to only token accounts.

**lamports** `object`

Filter by SOL balance with comparisons.

**comparison operators**

**eq** `integer`

Equal to specified amount.

**ne** `integer`

Not equal to specified amount.

**lt** `integer`

Less than specified amount.

**gt** `integer`

Greater than specified amount.

**nonempty\_txn\_signature** `boolean`

If `true`, only include updates caused by a transaction. If `false`, only include updates not caused by a transaction. If `undefined`, include all updates.

**slots** `object`

Subscribe to slot updates.

**properties**

**filter\_by\_commitment** `boolean`

Filter slots by commitment level.

**interslot\_updates** `boolean`

Include intermediate slot status updates (PROCESSED, CONFIRMED, FINALIZED,
FIRST\_SHRED\_RECEIVED, COMPLETED, CREATED\_BANK, DEAD).

**transactions** `object`

Subscribe to transaction updates.

**properties**

**vote** `boolean`

Include vote transactions.

**failed** `boolean`

Include failed transactions.

**signature** `string`

Monitor specific transaction signature.

**account\_include** `array`

Only include transactions affecting these accounts.

**account\_exclude** `array`

Exclude transactions affecting these accounts.

**account\_required** `array`

Transactions must affect all of these accounts.

**token\_accounts** `enum`

Optional associated token account (ATA) expansion (field tag 30, `TokenAccountExpansionControlFlag`). When set, an `account_include` wallet also matches transactions where it **owns** an SPL token balance — for example, incoming token transfers that touch the wallet's token account rather than its pubkey. Two variants:

* `ALL` (**0**) — match any transaction referencing a token balance the wallet owns, even if unchanged. Higher volume.
* `BALANCE_CHANGED` (**1**) — match when the wallet owns a token balance whose amount changed (or whose token account was closed) in the transaction.

To disable expansion, **leave the field absent** (`None`) — there is no "off" enum value. An out-of-range integer is rejected at config build: `Invalid token_accounts value, expected ALL (0) or BALANCE_CHANGED (1)`.

> [!WARNING]
>
> `ALL` is the **zero value**. A client that sets the enum to `0` expecting "default/off" gets `ALL` — the broadest, highest-volume mode. The only way to mean "no expansion" is to omit the field entirely.

**match\_mints** `boolean` (default: false)

Also match `account_include`, `account_exclude`, and `account_required` against the mints in the transaction's pre/post token balances (field tag 32). Put a mint in `account_include` to receive every transaction that touches that token, including plain SPL transfers whose account keys never reference the mint. Transactions with no token balances fall back to keys-only matching. `match_mints` alone does not restrict the stream; at least one list must still contain a key or mint. Composes with `token_accounts`. Honored during historical replay. See [Token Mint Filtering](https://www.helius.dev/docs/laserstream/mint-filtering.md).

**transactions\_status** `object`

Subscribe to transaction status updates.

**properties**

**vote** `boolean`

Include vote transactions.

**failed** `boolean`

Include failed transactions.

**signature** `string`

Monitor specific transaction signature.

**account\_include** `array`

Only include transactions affecting these accounts.

**account\_exclude** `array`

Exclude transactions affecting these accounts.

**account\_required** `array`

Transactions must affect all of these accounts.

**blocks** `object`

Subscribe to block updates.

**properties**

**account\_include** `array`

Only include blocks with transactions affecting these accounts.

**include\_transactions** `boolean`

Include full transaction details.

**include\_accounts** `boolean`

Include account updates.

**include\_entries** `boolean`

Include block entries.

**blocks\_meta** `object`

Subscribe to block metadata updates (lighter than full block updates).

**returns**

**slot** `integer`

Slot number.

**blockhash** `string`

Blockhash.

**rewards** `array`

Rewards information.

**block\_time** `integer`

Block time.

**block\_height** `integer`

Block height.

**parent\_slot** `integer`

Parent slot.

**parent\_blockhash** `string`

Parent blockhash.

**executed\_transaction\_count** `integer`

Transaction count.

**entries\_count** `integer`

Entry count.

**entry** `object`

Subscribe to entry updates.

**returns**

**slot** `integer`

Slot number.

**index** `integer`

Entry index.

**num\_hashes** `integer`

Number of hashes.

**hash** `string`

Hash.

**executed\_transaction\_count** `integer`

Transaction count.

**starting\_transaction\_index** `integer`

Starting transaction index.

**commitment** `enum`

The commitment level for the subscription:

**levels**

**PROCESSED** `integer`

(0): Processed by the current node.

**CONFIRMED** `integer`

(1): Confirmed by supermajority of the cluster.

**FINALIZED** `integer`

(2): Finalized by the cluster.

**accounts\_data\_slice** `array`

Specifies partial account data to receive:

**properties**

**offset** `integer`

Position in bytes to start reading data.

**length** `integer`

Number of bytes to read.

**ping** `object`

Enable ping-pong messages for connection health monitoring.

**properties**

**id** `integer`

Numeric identifier for the ping.

**from\_slot** `integer`

Starting slot to receive updates from. Updates for slots before this value
will be excluded. Use [SubscribeReplayInfo](https://www.helius.dev/docs/api-reference/laserstream/grpc/subscribereplayinfo.md)
to discover the earliest available replay slot before opening a subscription.

```json Accounts Subscription theme={"system"}
{
  "slots": {
      "slots": {}
  },
  "accounts": {
      "user-defined-label": {
          "account": [
              "DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu",
              "5U3bH5b6XtG99aVCE9ycvDgBKQx3fVT8WwTNbMToFuEr"
          ],
          "owner": [
              "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
          ],
          "filter": {
              "memcmp": {
                  "offset": 0,
                  "bytes": "0102030405"
              },
              "datasize": 165,
              "token_account_state": true,
              "lamports": {
                  "gt": 100000000
              }
          },
          "nonempty_txn_signature": true
      }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "commitment": 1
}
```

```json Slots Subscription theme={"system"}
{
  "slots": {
    "incoming_slots": {}
  },
  "commitment": 1
}
```

```json Transactions Subscription theme={"system"}
{
  "transactions": {
    "vote": false,
    "failed": true,
    "signature": "4RPMxKBhCBubFmZ1r9BC52ztjG3qBTW9Gp1PXfufUSATQaLKTW3Dj6vQBYyVrhfjgJ4PjZLzwYs4Z92KDCPw8Qym",
    "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
    "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
    "account_required": ["11111111111111111111111111111111"]
  },
  "commitment": 2
}
```

```json Wallet + Token Transfers (ATA expansion) theme={"system"}
{
  "transactions": {
    "wallet": {
      "vote": false,
      "failed": false,
      "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
      "account_exclude": [],
      "account_required": [],
      "token_accounts": 1
    }
  },
  "commitment": 1
}
```

```json Token Mint Subscription (match_mints) theme={"system"}
{
  "transactions": {
    "usdc": {
      "vote": false,
      "failed": false,
      "account_include": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
      "account_exclude": [],
      "account_required": [],
      "match_mints": true
    }
  },
  "commitment": 1
}
```

```json Transaction Status Subscription theme={"system"}
{
  "transactions_status": {
    "vote": false,
    "failed": true,
    "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
    "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
    "account_required": ["11111111111111111111111111111111"]
  },
  "commitment": 2
}
```

```json Blocks Subscription theme={"system"}
{
  "blocks": {
    "account_include": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
    "include_transactions": 1,
    "include_accounts": 1,
    "include_entries": 0
  },
  "commitment": 2
}
```

```json Block Metadata Subscription theme={"system"}
{
  "blocks_meta": {},
  "commitment": 2,
  "from_slot": 139000000
}
```

```json Entry Subscription theme={"system"}
{
  "entry": {},
  "commitment": 1
}
```

```json Partial Account Data Subscription theme={"system"}
{
  "accounts": {
    "account": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"]
  },
  "accounts_data_slice": [
    {
      "offset": 0,
      "length": 64
    },
    {
      "offset": 128,
      "length": 32
    }
  ],
  "commitment": 2
}
```

```json Ping Subscription theme={"system"}
{
  "ping": {
    "id": 1
  }
}
```

```json Combined Subscription theme={"system"}
{
  "accounts": {
    "account": ["DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu"],
    "nonempty_txn_signature": true
  },
  "slots": {
    "filter_by_commitment": 1,
    "interslot_updates": 1
  },
  "commitment": 2,
  "from_slot": 139000000,
  "ping": {
    "id": 123
  }
}
```

## Commitment Levels

All subscriptions support the following commitment levels:

* `PROCESSED`: Processed by the current node (0)
* `CONFIRMED`: Confirmed by supermajority of the cluster (1)
* `FINALIZED`: Finalized by the cluster (2)

## Response Structure

Subscription responses include:

* `filters`: The filter names that matched this update
* One of the following update types:
  * `account`: Account data, owner, lamports, executable status, etc.
  * `slot`: Slot information and status updates
  * `transaction`: Full transaction details, signature, and metadata
  * `transaction_status`: Transaction execution status (success/error)
  * `block`: Complete block data with transactions, accounts, rewards, etc.
  * `block_meta`: Lightweight block metadata without full transaction details
  * `entry`: Entry details within a block
  * `ping`/`pong`: Connection health check messages
* `created_at`: Timestamp when the update was created

```json Account Update theme={"system"}
{
  "filters": ["accounts"],
  "account": {
    "account": {
      "pubkey": "BASE58_ENCODED_PUBKEY",
      "lamports": 12345678,
      "owner": "BASE58_ENCODED_OWNER",
      "executable": false,
      "rent_epoch": 361,
      "data": "BASE64_ENCODED_DATA",
      "write_version": 123,
      "txn_signature": "BASE58_ENCODED_SIGNATURE"
    },
    "slot": 189554321,
    "is_startup": false
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```

```json Slot Update theme={"system"}
{
  "filters": ["slots"],
  "slot": {
    "slot": 189554321,
    "parent": 189554320,
    "status": 2,
    "dead_error": null
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```

```json Transaction Update theme={"system"}
{
  "filters": ["transactions"],
  "transaction": {
    "transaction": {
      "signature": "BASE58_ENCODED_SIGNATURE",
      "is_vote": false,
      "transaction": {
        "signatures": ["BASE58_ENCODED_SIGNATURE"],
        "message": {
          "header": {
            "num_required_signatures": 1,
            "num_readonly_signed_accounts": 0,
            "num_readonly_unsigned_accounts": 1
          },
          "account_keys": ["BASE58_ENCODED_PUBKEY1", "BASE58_ENCODED_PUBKEY2"],
          "recent_blockhash": "BASE58_ENCODED_BLOCKHASH",
          "instructions": [
            {
              "program_id_index": 1,
              "accounts": [0],
              "data": "BASE64_ENCODED_INSTRUCTION_DATA"
            }
          ]
        }
      },
      "meta": {
        "err": null,
        "fee": 5000,
        "pre_balances": [10000000, 1],
        "post_balances": [9995000, 1],
        "pre_token_balances": [],
        "post_token_balances": [],
        "log_messages": ["Program log: Instruction executed"],
        "rewards": []
      },
      "index": 2
    },
    "slot": 189554321
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```

```json Block Metadata Update theme={"system"}
{
  "filters": ["blocks_meta"],
  "block_meta": {
    "slot": 189554321,
    "blockhash": "BASE58_ENCODED_BLOCKHASH",
    "rewards": [
      {
        "pubkey": "BASE58_ENCODED_PUBKEY",
        "lamports": 1785000,
        "post_balance": 48589432109,
        "reward_type": 0,
        "commission": 10
      }
    ],
    "block_time": 1682684096,
    "block_height": 185432109,
    "parent_slot": 189554320,
    "parent_blockhash": "BASE58_ENCODED_PARENT_BLOCKHASH",
    "executed_transaction_count": 2576,
    "entries_count": 16
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```

```json Entry Update theme={"system"}
{
  "filters": ["entry"],
  "entry": {
    "slot": 189554321,
    "index": 5,
    "num_hashes": 8765432,
    "hash": "BASE58_ENCODED_HASH",
    "executed_transaction_count": 128,
    "starting_transaction_index": 1024
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```

```json Pong Response theme={"system"}
{
  "filters": [],
  "pong": {
    "id": 1
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.