MonitorTransaction

Stream real-time status updates for a submitted transaction.

Monitors an on-chain transaction’s progress by streaming status updates until the transaction reaches a terminal state. Call MonitorTransaction immediately after SubmitTransaction using the returned signature.

MonitorTransaction is a server-streaming RPC — the server sends multiple response messages over a single connection until the transaction reaches a terminal state. Consuming it requires a different pattern than unary calls. See the code examples below for the full stream loop.

Stream Lifecycle

When you call MonitorTransaction, the server begins watching for the transaction and emits a new response message each time the transaction advances to a new status. The stream remains open until a terminal status is reached.

The stream closes when any of the following terminal statuses are received: FINALIZED, FAILED, DROPPED, or TIMEOUT. If commitment_level is set to CONFIRMED, the stream closes on CONFIRMED without waiting for FINALIZED.

Request

signature · Base58-encoded string · required

The transaction signature to monitor. Returned by SubmitTransaction.

commitment_level · CommitmentLevel (enum)

Optional. The target commitment level — the stream closes when this level is reached (or on FINALIZED if FINALIZED was requested). Defaults to CONFIRMED.

include_logs · bool

Optional. If true, program execution logs are included in status update responses. Defaults to false.

timeout_seconds · uint32

Optional. How many seconds to monitor before emitting a TIMEOUT status and closing the stream. Defaults to 60 seconds.

Stream Responses

Each message in the stream is a MonitorTransactionResponse:

signature · Base58-encoded string

The signature being monitored.

status · TransactionStatus (enum)

The current on-chain status of the transaction. See TransactionStatus Values below.

slot · uint64

The blockchain slot where this status was recorded.

error_message · string

Human-readable error details. Populated when status is FAILED.

logs · string[]

Program execution log lines. Only populated if include_logs was true in the request.

compute_units_consumed · uint64

Compute units consumed by the transaction. Available on PROCESSED and later statuses.

current_commitment · CommitmentLevel (enum)

The commitment level that has been achieved at the time of this update.

TransactionStatus Values

Status	Value	Meaning	Stream Behavior
TRANSACTION_STATUS_UNSPECIFIED	0	Not set	—
TRANSACTION_STATUS_RECEIVED	1	Transaction received by a validator	Stream continues
TRANSACTION_STATUS_PROCESSED	2	Transaction processed (Processed commitment)	Stream continues
TRANSACTION_STATUS_CONFIRMED	3	Transaction confirmed (Confirmed commitment)	Stream continues or closes (if commitment_level = CONFIRMED)
TRANSACTION_STATUS_FINALIZED	4	Transaction finalized (Finalized commitment)	Stream closes
TRANSACTION_STATUS_FAILED	5	Transaction failed during on-chain execution	Stream closes
TRANSACTION_STATUS_DROPPED	6	Transaction dropped from the network	Stream closes
TRANSACTION_STATUS_TIMEOUT	7	Monitoring window expired	Stream closes

TIMEOUT means the monitoring window expired, not that the transaction failed. The transaction may still be processing on-chain. If you receive TIMEOUT, call GetTransaction to check current status, or start a new MonitorTransaction with the same signature.

DROPPED means the transaction was not processed. If the transaction’s blockhash has not yet expired, you may resubmit. If expired, call CompileTransaction to recompile with a fresh blockhash.

Code Examples

The following examples show the full stream consumption loop — the minimal API call plus status handling for each terminal state.

Go

stream, err := client.MonitorTransaction(ctx, &transaction_v1.MonitorTransactionRequest{
    Signature: "YourTransactionSignature1111111111111111111",
})
if err != nil {
    log.Fatal(err)
}

for {
    resp, err := stream.Recv()
    if err == io.EOF {
        break // Stream closed by server
    }
    if err != nil {
        log.Printf("Stream error: %v", err)
        break
    }

    fmt.Printf("Status: %v (slot %d)\n", resp.Status, resp.Slot)

    switch resp.Status {
    case transaction_v1.TransactionStatus_TRANSACTION_STATUS_FINALIZED:
        fmt.Println("Transaction finalized")
        return
    case transaction_v1.TransactionStatus_TRANSACTION_STATUS_FAILED:
        fmt.Printf("Transaction failed: %s\n", resp.ErrorMessage)
        return
    case transaction_v1.TransactionStatus_TRANSACTION_STATUS_DROPPED:
        fmt.Println("Transaction dropped — consider resubmitting")
        return
    case transaction_v1.TransactionStatus_TRANSACTION_STATUS_TIMEOUT:
        fmt.Println("Monitoring timed out — check GetTransaction for current status")
        return
    }
}

The examples above show the basic stream consumption loop. For production use — including reconnection logic, exponential backoff, and multi-signature monitoring — see the Monitor Transactions guide.