> ## 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.

# transactionSubscribe

> transactionSubscribe streams real-time Solana transaction events over WebSocket with custom filters — watch accounts, exclude votes, and set the detail level.

## Endpoints

Enhanced WebSockets are available on mainnet and devnet:

* **Mainnet** `wss://mainnet.helius-rpc.com/?api-key=<api-key>`
* **Devnet** `wss://devnet.helius-rpc.com/?api-key=<api-key>`

> [!NOTE]
>
> WebSockets have a 10-minute inactivity timer; implementing health checks and sending pings every minute is heavily recommended to keep the WebSocket connection alive.

## Authorizations

**api-key** `string` *required*

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

## Body

**params** `array` *required*

**TransactionSubscribeFilter**

**vote** `boolean`

Include or exclude vote-related transactions.

**failed** `boolean`

Include or exclude transactions that failed.

**signature** `string`

Filter updates to a specific transaction by its signature.

**accountInclude** `string[]`

List of accounts to receive transaction updates for. A transaction must include **at least one** of these accounts. Supports up to 50,000 addresses.

**accountExclude** `string[]`

List of accounts to exclude from transaction updates. Supports up to 50,000 addresses.

**accountRequired** `string[]`

List of accounts that **must all** be included in a transaction for it to match. Supports up to 50,000 addresses.

**tokenAccounts** `string`

Opt in to associated token account (ATA) expansion so an `accountInclude` 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. Accepts:

* `"balanceChanged"` — match when the wallet owns a token balance whose amount changed (or whose token account was closed) in the transaction.
* `"all"` — match any transaction referencing a token balance the wallet owns, even if unchanged. Higher volume.
* `"none"` — same as omitting the field (no expansion). This is the default.

An invalid value returns JSON-RPC error `-32602`: `Invalid tokenAccounts value '<x>', expected one of: none, balanceChanged, all`.

**TransactionSubscribeOptions**

**commitment** `string`

Commitment level for fetching data. Can be `processed`, `confirmed`, or `finalized`.

**encoding** `string`

Encoding format for the returned data. Can be `base58`, `base64`, or `jsonParsed`.

**transactionDetails** `string`

Level of detail for the returned transaction data. Can be `full`, `signatures`, `accounts`, or `none`.

**showRewards** `boolean`

Whether to include reward data in the updates.

**maxSupportedTransactionVersion** `integer`

The highest transaction version to receive updates for. Set to `1` to receive legacy, v0, and v1 transactions.

> [!NOTE]
>
> Required when `transactionDetails` is set to `"accounts"` or `"full"`.

## Response

**result** `integer`

Subscription id (needed to unsubscribe)

```json Request theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 420,
  "method": "transactionSubscribe",
  "params": [
    {
      "accountInclude": ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"]
    },
    {
      "commitment": "processed",
      "encoding": "jsonParsed",
      "transactionDetails": "full",
      "showRewards": true,
      "maxSupportedTransactionVersion": 1
    }
  ]
}
```

```json Watch a wallet incl. token transfers theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "transactionSubscribe",
  "params": [
    {
      "accountInclude": ["<WALLET_PUBKEY>"],
      "tokenAccounts": "balanceChanged"
    },
    { "commitment": "confirmed", "encoding": "jsonParsed" }
  ]
}
```

```javascript Code Example theme={"system"}
const WebSocket = require("ws");

const ws = new WebSocket("wss://mainnet.helius-rpc.com/?api-key=<API_KEY>");

ws.on("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 420,
    method: "transactionSubscribe",
    params: [
      { accountInclude: ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"] },
      {
        commitment: "processed",
        encoding: "jsonParsed",
        transactionDetails: "full",
        maxSupportedTransactionVersion: 1,
      },
    ],
  }));

  // Keep connection alive
  setInterval(() => ws.ping(), 30_000);
});

ws.on("message", (data) => {
  console.log(JSON.parse(data.toString()));
});
```

```json Response theme={"system"}
{
  "jsonrpc": "2.0",
  "result": 4743323479349712,
  "id": 420
}
```

```json Notification theme={"system"}
{
  "jsonrpc": "2.0",
  "method": "transactionNotification",
  "params": {
    "subscription": 4743323479349712,
    "result": {
      "transaction": {
        "transaction": [
          "Ae6zfSExLsJ/E1+q0jI+3ueAtSoW+6HnuDohmuFwagUo2BU4OpkSdUKYNI1dJfMOonWvjaumf4Vv1ghn9f3Avg0BAAEDGycH0OcYRpfnPNuu0DBQxTYPWpmwHdXPjb8y2P200JgK3hGiC2JyC9qjTd2lrug7O4cvSRUVWgwohbbefNgKQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA0HcpwKokfYDDAJTaF/TWRFWm0Gz5/me17PRnnywHurMBAgIAAQwCAAAAoIYBAAAAAAA=",
          "base64"
        ],
        "meta": {
          "err": null,
          "status": {
            "Ok": null
          },
          "fee": 5000,
          "preBalances": [
            28279852264,
            158122684,
            1
          ],
          "postBalances": [
            28279747264,
            158222684,
            1
          ],
          "innerInstructions": [],
          "logMessages": [
            "Program 11111111111111111111111111111111 invoke [1]",
            "Program 11111111111111111111111111111111 success"
          ],
          "preTokenBalances": [],
          "postTokenBalances": [],
          "rewards": null,
          "loadedAddresses": {
            "writable": [],
            "readonly": []
          },
          "computeUnitsConsumed": 0
        }
      },
      "signature": "5moMXe6VW7L7aQZskcAkKGQ1y19qqUT1teQKBNAAmipzdxdqVLAdG47WrsByFYNJSAGa9TByv15oygnqYvP6Hn2p",
      "slot": 224341380,
      "transactionIndex": 42
    }
  }
}
```

## Managing Subscriptions

### Subscription IDs

When `transactionSubscribe` succeeds, the server returns a subscription ID in the `result` field. This is the same number that appears in `params.subscription` on every notification from that subscription:

```json Subscribe Response theme={"system"}
{
  "jsonrpc": "2.0",
  "result": 4743323479349712,
  "id": 420
}
```

```json Notification theme={"system"}
{
  "jsonrpc": "2.0",
  "method": "transactionNotification",
  "params": {
    "subscription": 4743323479349712,
    "result": {}
  }
}
```

Store the subscription ID from the response. You need it to unsubscribe.

### Unsubscribing

To stop receiving notifications, call `transactionUnsubscribe` with the subscription ID. Each `transactionSubscribe` call on the same connection creates a separate subscription with its own ID, so make sure to unsubscribe before resubscribing to avoid receiving duplicate notifications.

```json Request theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 421,
  "method": "transactionUnsubscribe",
  "params": [4743323479349712]
}
```

```json Response theme={"system"}
{
  "jsonrpc": "2.0",
  "result": true,
  "id": 421
}
```

A few in-flight messages may still arrive briefly after calling `transactionUnsubscribe`. This is expected behavior.


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