signatureSubscribe

The Solana signatureSubscribe method creates a subscription to receive a notification when a specific transaction signature reaches a specified commitment level.

Usage Notes

• Must be called via a WebSocket endpoint; HTTP is not supported.
• This is a single-notification subscription. The subscription is automatically cancelled after the server sends a signatureNotification.
• CU is consumed based on the amount of data subscribed, so it is recommended to use appropriate filtering options to subscribe only to the data you need.

---

1. Request

Parameters

The signature subscription request has the following parameters.

Parameter	Type	Required	Description
id	integer or string	required	Unique identifier for the request. Used by the client to match requests with responses.
jsonrpc	string	required	JSON-RPC protocol version. Always set to "2.0".
method	string	required	Name of the method to execute. Enter "signatureSubscribe" here.
params	array	required	Signature information and options to subscribe to. The first element is the transaction signature, and the second is the configuration object.
params[0]	string	required	The transaction signature to subscribe to (base-58 encoded string). Must be the first signature of the transaction.
params[1].commitment	string	optional	Specifies the level of block finality. - finalized: Queries the most recent block confirmed as finalized by a supermajority of the cluster at maximum lockout. The cluster recognizes this block as final. - confirmed: Queries the most recent block voted on by a supermajority of the cluster. - processed: Queries the node's most recent block. This block may still be skipped by the cluster.
params[1].enableReceivedNotification	boolean	optional	Specifies whether to also receive a notification when the signature is received by the RPC. If true, notifications are received both at receipt and upon processing completion.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
    {
      "commitment": "finalized",
      "enableReceivedNotification": false
    }
  ]
}

---

2. Response

Subscription Response

When the subscription is successfully created, a subscription ID is returned.

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

This subscription ID is required when calling the signatureUnsubscribe method.

Notifications

Once the subscription is active, the server pushes a notification when the transaction reaches the specified commitment level.

Notification format:

Field	Type	Description
slot	u64	The slot number
value	object | string	RpcSignatureResult notification value

value field details:

• Signature received notification (when enableReceivedNotification is true and the signature is received):

  • Type: string
  • Value: "receivedSignature"
  • Description: Indicates the signature has been received by the RPC

• Transaction processing complete notification (when the signature has been processed):

  • Type: object
  • Value: { "err": null } (success) or { "err": TransactionError } (failure)
  • Description: The transaction has been processed at the specified commitment level

Examples

{
  "jsonrpc": "2.0",
  "method": "signatureNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5207624
      },
      "value": {
        "err": null
      }
    },
    "subscription": 24006
  }
}

{
  "jsonrpc": "2.0",
  "method": "signatureNotification",
  "params": {
    "result": {
      "context": {
        "slot": 5207624
      },
      "value": "receivedSignature"
    },
    "subscription": 24006
  }
}

---

3. How to Use

Connect to WebSocket Channel

wscat -c wss://api.mainnet-beta.solana.com

Subscribe to Signature

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
    {
      "commitment": "finalized",
      "enableReceivedNotification": false
    }
  ]
}

Receive Notification

• Initial response: subscription ID is returned
• Subsequently: when a matching transaction reaches the specified commitment level, the server automatically sends a notification, and the subscription is automatically cancelled after receiving the notification (single-notification subscription)

Unsubscribe

There are two ways to unsubscribe:

1. Close the connection: Press Ctrl+C in the terminal window to terminate the WebSocket connection, which automatically cancels all subscriptions.

2. Cancel a specific subscription: Use signatureUnsubscribe to cancel only a specific subscription while keeping the connection open.

Unsubscribe request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureUnsubscribe",
  "params": [10]
}

Response after unsubscribing:

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