Skip to main content

signatureSubscribe

Subscribe to receive a notification when the transaction with the given signature reaches the specified commitment level.

Common use cases
Monitor transaction confirmationSubscribe immediately after sendTransaction to receive real-time notification when transaction reaches target commitment level. Eliminates polling overhead compared to getSignatureStatuses; subscription auto-cancels after single notification.
Track transaction receipt by RPCEnable enableReceivedNotification: true to receive intermediate notification when RPC first receives transaction, before processing completes. Improves UX by showing 'received' state before final confirmation notification arrives.
Implement confirmation timeout fallbackSubscribe for real-time notifications with timeout mechanism: if no notification within 30-60 seconds, fall back to polling getSignatureStatuses. Handles WebSocket disconnection or missed notification scenarios gracefully.
Verify failed transaction detailsSubscribe to receive notification with err field containing TransactionError details when transaction fails. Provides immediate error feedback without polling, critical for debugging transaction submission issues.

Parameters​

subscriptionId (string, required)

transaction signature, as base-58 encoded string The transaction signature must be the first signature from the transaction (see transaction id for more details).

config (object, optional)

Configuration object containing the following fields:

Fields:

  • commitment (string): The commitment describes how finalized a block is at that point in time. See Configuring State Commitment.
  • enableReceivedNotification (boolean): Whether or not to subscribe for notifications when signatures are received by the RPC, in addition to when they are processed.

Request​

wscat -c wss://solana-mainnet.api.syndica.io -x '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
    {
      "commitment": "finalized",
      "enableReceivedNotification": false
    }
  ]
}'
Network Selection

Replace mainnet with devnet in the URL to query devnet instead.

Response​

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

Response Fields​

Return value: integer

subscription id (needed to unsubscribe)

Notification Format​

The notification will be an RpcResponse JSON object with value containing an object with:

  • slot: <u64> - The corresponding slot.
  • value: <object|string> - a notification value of RpcSignatureResult, resulting in either:
    • when enableReceivedNotification is true and the signature is received: the literal string "receivedSignature", or
    • when the signature is processed: err: <object|null>:
      • null if the transaction succeeded in being processed at the specified commitment level, or
      • a TransactionError, if the transaction failed

Example responses:​

The following is an example response of a notification from a successfully processed transactions:

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

FAQ and Troubleshooting​

Why did my subscription not receive a notification?

Transaction may not have been processed yet, or WebSocket disconnected before notification sent. Implement 30-60 second timeout and fall back to polling getSignatureStatuses. Check commitment level matches transaction confirmation status.

Do I need to call signatureUnsubscribe after receiving notification?

No. Server automatically cancels subscription after sending signatureNotification. Explicit unsubscribe only needed if cancelling before notification arrives.

What does enableReceivedNotification: true do?

Sends two notifications: first when RPC receives transaction (value: "receivedSignature" string), second when processed (value: object with err field). Use for UX to show "pending" state immediately.

How do I know if my transaction succeeded or failed?

Check the err field in the notification's value object. err: null means success, err: <object> contains TransactionError details for failures. This only appears in the final processed notification, not the received notification.

Which commitment level should I use for signatureSubscribe?

Use finalized for irreversible confirmation (35+ slots, ~15-20 seconds), confirmed for optimistic confirmation (~2-4 seconds, supermajority vote), or processed for immediate inclusion (~400ms, single node). Production apps typically use confirmed or finalized.

signatureUnsubscribe
Cancels signatureSubscribe before notification arrives. Rarely needed since subscription auto-expires, but useful when abandoning transaction monitoring or closing application before confirmation.

getSignatureStatuses
HTTP fallback for polling signature confirmation status. Use when WebSocket connection unavailable or as timeout fallback if signatureSubscribe notification not received within expected timeframe.

sendTransaction
Submits transaction to network and returns signature for monitoring. Standard pattern: call sendTransaction, immediately subscribe via signatureSubscribe using returned signature to track confirmation.

getTransaction
Fetches full transaction details after confirmation. Common workflow: wait for signatureSubscribe notification confirming transaction landed, then call getTransaction to retrieve complete transaction data including logs and accounts.

External Resources​