# signatureSubscribe

> Emits a one-shot notification when a transaction signature reaches the requested commitment.

Source: https://docs.constant-k.com/rpc/websocket/signaturesubscribe/

`signatureSubscribe` is the push equivalent of polling `getSignatureStatuses` for a single signature. It fires exactly one terminal notification — `value.err` is `null` on success or the transaction's error object on failure — once the signature reaches the requested `commitment`, and the server automatically unsubscribes afterward; calling `signatureUnsubscribe` is normally unnecessary.

Setting `enableReceivedNotification` adds an earlier, best-effort notification (`value` is the literal string `"receivedSignature"`) the moment the node first sees the signature, before it has necessarily been processed at all — the basis for an optimistic "transaction received" UI state ahead of real confirmation.

- Transport: WebSocket, JSON-RPC 2.0 over `wss://ws-newyork.constant-k.com:1337/ws?api-key=YOUR_API_KEY`
- Category: Subscriptions
- Availability: Operator and above

## Parameters

`params` is a positional JSON array, in this order:

- `signature` (string, required): Base58-encoded transaction signature (the transaction's first/fee-payer signature) to watch.
- `config` (object, optional): Optional subscription settings.
  - `commitment` (string, optional, one of `processed`, `confirmed`, `finalized`, default `"finalized"`): How settled the account/transaction state must be before the node acts on it. `processed` is fastest and can roll back; `finalized` is slowest and never rolls back.
  - `enableReceivedNotification` (boolean, optional, default `false`): Sends an extra early notification as soon as the node receives the signature, ahead of the terminal confirmation notification.

## Result

- `result` (integer, optional): The subscription id, returned once in the initial RPC response. Passed to `signatureUnsubscribe`, it cancels the stream before the terminal notification arrives.

## Notifications

Updates arrive as `signatureNotification` messages. For the terminal notification, `result.value` is `{"err": null}` on success or `{"err": {...}}` on failure. If `enableReceivedNotification` was set, an earlier notification may arrive first with `result.value` equal to the literal string `"receivedSignature"` instead of an object.

- `params.result` (object, optional)
  - `context` (object, optional): Response context, including the slot the data was read at.
    - `slot` (integer, optional): Slot number this applies to.
  - `value` (object | string, optional): The requested data; see the fields below.
    - `option 1` (object, optional): Terminal notification: the transaction's outcome.
      - `err` (object | null, optional): Null on success, or an error object/string describing the failure.
    - `option 2` (string, optional, one of `receivedSignature`): Early notification, only when `enableReceivedNotification` is true.

## Unsubscribe

`signatureUnsubscribe`, called with the subscription id, returns `true` once the subscription is removed.

## Example: Subscribe to a transaction signature

Request (send after connecting):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "3AACzdSv9T3wkS41t9yES9ou22SyTk842gqsEakANtPjoSjPSVJ3isndabWCiTAmC8yqTnEhCCPVG1b8WgMAPPmT",
    {
      "commitment": "confirmed",
      "enableReceivedNotification": false
    }
  ]
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "result": 61234,
  "id": 1
}
```

Notification:

```json
{
  "jsonrpc": "2.0",
  "method": "signatureNotification",
  "params": {
    "result": {
      "context": {
        "slot": 337812501
      },
      "value": {
        "err": null
      }
    },
    "subscription": 61234
  }
}
```

## Notes

- WebSocket access is included on the Operator plan and above; it is not available on Free.
- Concurrent connections are capped per API key: 10 on Operator, 50 on Blade Runner, 100 on Nexus.
- Subscribe and unsubscribe calls draw from the same global per-plan request-rate limit as HTTP calls: 50 req/s on Operator, 200 req/s on Blade Runner, 500 req/s on Nexus.
- Only subscription methods (the `*Subscribe` / `*Unsubscribe` family) are accepted on the WebSocket endpoint; standard request/response RPC methods must go over HTTPS instead.
- A `getHealth` request sent over the open socket on a regular interval serves as a keepalive; connections that go quiet can be dropped by intermediate load balancers.
- Each region has its own WebSocket hostname, for example `wss://ws-newyork.constant-k.com:1337/ws?api-key=YOUR_API_KEY`; every region is listed on the Endpoints page.
- Hand-built rather than captured live: catching a real, still-in-flight signature inside a short scripted WebSocket session isn't reliable, since the terminal notification only fires for state changes happening after the subscription starts.
- The subscription must start before, or immediately as, the transaction is sent. There is no historical replay: a signature that already reached the requested commitment before the subscription started produces no notification.