TriportRPC
DashboardDocs

signatureSubscribe

Subscribes to a transaction signature and fires a one-shot notification when the transaction reaches the requested commitment level.

Solanasol.pubsubfree+ — per-method tier gating on /ws/sol

signatureSubscribe watches a single transaction signature and pushes a signatureNotification the moment the transaction is processed at the commitment level you asked for. It is the push-based alternative to polling getSignatureStatuses in a loop after sendTransaction: submit, subscribe, and wait for one frame instead of hammering the HTTP endpoint.

The notification carries context.slot and a value object whose err field is null on success or a TransactionError object if the transaction failed on-chain — a failed transaction still confirms, so always inspect err rather than treating the notification itself as success. With enableReceivedNotification: true you additionally get an early frame with value set to the string "receivedSignature" when the node first sees the signature, useful for showing a "propagating…" state in a UI before the real confirmation lands.

The defining quirk: this subscription is one-shot. After the notification at the requested commitment fires, the server cancels the subscription automatically — you do not need to call signatureUnsubscribe afterwards, and attempting to will fail because the id is already gone. signatureUnsubscribe is only for abandoning a wait early (for example, when your blockhash expires and you are about to re-send).

Two gotchas. The signature must be the transaction's first signature (the fee payer's) as a base-58 string. And the subscription only sees what happens from now on: if the transaction already reached the requested commitment before you subscribed, no notification will ever arrive — pair the subscription with one getSignatureStatuses check to close that race, and put a deadline on the wait tied to blockhash expiry.

Parameters

Positional params array: [signature, config?].

signaturestring (base-58)required
The transaction's first signature, as returned by sendTransaction.
configobjectoptional
Optional configuration object (see below).
commitmentstringoptional
processed, confirmed (default), or finalized — the level at which the final notification fires.
enableReceivedNotificationbooleanoptional
When true, also notify when the node first receives the signature.

Response

Subscribe ack:

The confirmation notification (after which the subscription self-cancels):

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

With enableReceivedNotification: true, an earlier frame may carry "result": { "context": {...}, "value": "receivedSignature" }.

result (on ack)integer
Subscription id.
params.result.context.slotinteger
Slot in which the transaction reached the commitment.
params.result.value.errobject | null
null = executed successfully; otherwise the on-chain TransactionError.
params.result.valuestring
The literal "receivedSignature" on the optional received-notification frame.

Errors

CodeMeaningWhen it happens
-32602Invalid paramssignature is not a valid base-58 transaction signature.
4001unauthorizedMissing or invalid API key on the upgrade / auth frame.
4029rate_limitedSubscribe rate exceeded for your tier.

Notes

  • One-shot: the subscription auto-cancels after the final notification — no unsubscribe needed on the happy path.
  • Failed ≠ missing: a transaction that errored on-chain still triggers the notification, with value.err populated. Check it.
  • Race on subscribe: confirmations that happened before you subscribed are not replayed. Combine with a one-shot getSignatureStatuses call.
  • Related methods: signatureUnsubscribe to abandon a wait early, sendTransaction to submit, and logsSubscribe to stream the transaction's logs instead of just its status.