Jump to

• Request
• Response

Get Transaction Status

get

/v1/besu/transaction/operations/{operationId}

Returns the current status of a transaction operation created with lifecycle tracking. The operation is available only to the authenticated caller that created it. Requests from other callers return HTTP 404.

Request

Path Parameters

• operationId(required): string
  Unique identifier for the transaction operation.

Header Parameters

• X-Request-Id: string
  Optional correlation ID. Echoed in the response when provided.

There's no request body for this operation.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Returns the current transaction status.

Body ()

Root Schema : TransactionOperationStatusResponse

Type: object

Current status of a tracked transaction operation.

Show Source

• blockedByNonce: [ "integer", "null" ] (int64)
  Lower nonce preventing progress, when available.
• broadcastStatus: object TransactionBroadcastStatus
  Summary of transaction broadcast progress.
• callbacks: array callbacks
  Redacted callback delivery state for the operation. Callback target URLs, OAuth credentials, TLS private keys, payload bodies, and raw callback errors are excluded.
• chainId: integer (int64)
  Ethereum chain identifier for the transaction operation.
• completedAt: [ "string", "null" ]
  Timestamp when the transaction operation completed, when available.
• createdAt: string
  Timestamp when the transaction operation was created.
• diagnosticClassification: [ "string", "null" ]
  Current diagnostic classification, when available.
• diagnosticsUrl: string
  Non-public lifecycle metadata URL, when available.
• feeMode: string
  Allowed Values: [ "zero_fee" ]

  Fee profile used for the transaction operation.
• finalOutcome: [ "string", "null" ]
  Final transaction outcome, when available.
• latestAttempt: object TransactionAttemptSummary
  Summary of a transaction submission attempt.
• nextAllocatableNonce: [ "integer", "null" ] (int64)
  Next nonce available for managed allocation, when available.
• nonceQueueManaged: boolean
  Indicates whether managed nonce allocation is used for the sender.
• nonceState: [ "string", "null" ]
  Current managed nonce allocation state, when available.
• operationId: string
  Unique identifier for the transaction operation.
• queuePosition: [ "integer", "null" ] (int64)
  Number of active lower nonce allocations, when available.
• rawReceipt: [ "object", "null" ] rawReceipt
  Additional Properties Allowed: true

  Complete transaction receipt returned by Besu. Available only for by-hash lookups with `receiptDetail=full`; it can include receipt logs and topics.
• receipt:
  Receipt summary, when a receipt is available.
• receiptDetail: string
  Allowed Values: [ "summary", "full" ]

  Receipt detail level. Defaults to `summary`; `full` is returned only for by-hash lookups requested with `receiptDetail=full`.
• requestedMode: string
  Allowed Values: [ "NORMAL" ]

  Requested transaction submission mode.
• senderAddress: string
  Sender address for the transaction operation.
• status: string
  Allowed Values: [ "accepted", "signing", "submitted", "mined", "confirmed", "failed" ]

  Current lifecycle status of the transaction operation.
• statusUrl: string
  URL for retrieving the transaction operation status.
• updatedAt: string
  Timestamp when the transaction operation was last updated.
• walletId: [ "string", "null" ]
  Wallet identifier used for signing, when applicable.

{
    "type":"object",
    "description":"Current status of a tracked transaction operation.",
    "properties":{
        "operationId":{
            "type":"string",
            "description":"Unique identifier for the transaction operation."
        },
        "status":{
            "type":"string",
            "enum":[
                "accepted",
                "signing",
                "submitted",
                "mined",
                "confirmed",
                "failed"
            ],
            "description":"Current lifecycle status of the transaction operation."
        },
        "feeMode":{
            "type":"string",
            "enum":[
                "zero_fee"
            ],
            "description":"Fee profile used for the transaction operation."
        },
        "requestedMode":{
            "type":"string",
            "enum":[
                "NORMAL"
            ],
            "description":"Requested transaction submission mode."
        },
        "senderAddress":{
            "type":"string",
            "description":"Sender address for the transaction operation."
        },
        "chainId":{
            "type":"integer",
            "format":"int64",
            "description":"Ethereum chain identifier for the transaction operation."
        },
        "walletId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Wallet identifier used for signing, when applicable."
        },
        "diagnosticClassification":{
            "type":[
                "string",
                "null"
            ],
            "description":"Current diagnostic classification, when available."
        },
        "finalOutcome":{
            "type":[
                "string",
                "null"
            ],
            "description":"Final transaction outcome, when available."
        },
        "createdAt":{
            "type":"string",
            "description":"Timestamp when the transaction operation was created."
        },
        "updatedAt":{
            "type":"string",
            "description":"Timestamp when the transaction operation was last updated."
        },
        "completedAt":{
            "type":[
                "string",
                "null"
            ],
            "description":"Timestamp when the transaction operation completed, when available."
        },
        "statusUrl":{
            "type":"string",
            "description":"URL for retrieving the transaction operation status."
        },
        "diagnosticsUrl":{
            "type":"string",
            "description":"Non-public lifecycle metadata URL, when available."
        },
        "nonceQueueManaged":{
            "type":"boolean",
            "description":"Indicates whether managed nonce allocation is used for the sender."
        },
        "nonceState":{
            "type":[
                "string",
                "null"
            ],
            "description":"Current managed nonce allocation state, when available."
        },
        "queuePosition":{
            "type":[
                "integer",
                "null"
            ],
            "format":"int64",
            "description":"Number of active lower nonce allocations, when available."
        },
        "blockedByNonce":{
            "type":[
                "integer",
                "null"
            ],
            "format":"int64",
            "description":"Lower nonce preventing progress, when available."
        },
        "nextAllocatableNonce":{
            "type":[
                "integer",
                "null"
            ],
            "format":"int64",
            "description":"Next nonce available for managed allocation, when available."
        },
        "broadcastStatus":{
            "$ref":"#/components/schemas/TransactionBroadcastStatus",
            "description":"Current transaction broadcast progress."
        },
        "latestAttempt":{
            "$ref":"#/components/schemas/TransactionAttemptSummary",
            "description":"Most recent transaction submission attempt."
        },
        "receipt":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionReceiptSummary"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Receipt summary, when a receipt is available."
        },
        "receiptDetail":{
            "type":"string",
            "enum":[
                "summary",
                "full"
            ],
            "description":"Receipt detail level. Defaults to `summary`; `full` is returned only for by-hash lookups requested with `receiptDetail=full`."
        },
        "rawReceipt":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete transaction receipt returned by Besu. Available only for by-hash lookups with `receiptDetail=full`; it can include receipt logs and topics."
        },
        "callbacks":{
            "type":"array",
            "description":"Redacted callback delivery state for the operation. Callback target URLs, OAuth credentials, TLS private keys, payload bodies, and raw callback errors are excluded.",
            "items":{
                "$ref":"#/components/schemas/TransactionCallbackDelivery"
            }
        }
    }
}

Nested Schema : TransactionBroadcastStatus

Type: object

Summary of transaction broadcast progress.

Show Source

• acceptedByNode: boolean
  Indicates whether the Besu node accepted the transaction.
• acceptedByProxy: boolean
  Indicates whether the transaction request was accepted.
• confirmed: boolean
  Indicates whether the transaction reached the required confirmation threshold.
• executionStatus: string
  Allowed Values: [ "unknown", "success", "reverted" ]

  Execution result for the mined transaction.
• feeMode: string
  Allowed Values: [ "zero_fee" ]

  Fee profile used for the transaction.
• mined: boolean
  Indicates whether the transaction was included in a block.
• observedInTxpool: string
  Allowed Values: [ "unknown", "observed", "not_observed" ]

  Indicates whether the transaction was observed in the transaction pool.
• signed: boolean
  Indicates whether the transaction was signed.
• submittedToNode: boolean
  Indicates whether the signed transaction was submitted to a Besu node.
• validated: boolean
  Indicates whether the transaction request passed validation.

{
    "type":"object",
    "description":"Summary of transaction broadcast progress.",
    "properties":{
        "acceptedByProxy":{
            "type":"boolean",
            "description":"Indicates whether the transaction request was accepted."
        },
        "validated":{
            "type":"boolean",
            "description":"Indicates whether the transaction request passed validation."
        },
        "signed":{
            "type":"boolean",
            "description":"Indicates whether the transaction was signed."
        },
        "submittedToNode":{
            "type":"boolean",
            "description":"Indicates whether the signed transaction was submitted to a Besu node."
        },
        "acceptedByNode":{
            "type":"boolean",
            "description":"Indicates whether the Besu node accepted the transaction."
        },
        "observedInTxpool":{
            "type":"string",
            "enum":[
                "unknown",
                "observed",
                "not_observed"
            ],
            "description":"Indicates whether the transaction was observed in the transaction pool."
        },
        "mined":{
            "type":"boolean",
            "description":"Indicates whether the transaction was included in a block."
        },
        "confirmed":{
            "type":"boolean",
            "description":"Indicates whether the transaction reached the required confirmation threshold."
        },
        "executionStatus":{
            "type":"string",
            "enum":[
                "unknown",
                "success",
                "reverted"
            ],
            "description":"Execution result for the mined transaction."
        },
        "feeMode":{
            "type":"string",
            "enum":[
                "zero_fee"
            ],
            "description":"Fee profile used for the transaction."
        }
    }
}

Nested Schema : callbacks

Type: array

Redacted callback delivery state for the operation. Callback target URLs, OAuth credentials, TLS private keys, payload bodies, and raw callback errors are excluded.

Show Source

• Array of: object TransactionCallbackDelivery
  Redacted callback delivery status for a tracked transaction.

{
    "type":"array",
    "description":"Redacted callback delivery state for the operation. Callback target URLs, OAuth credentials, TLS private keys, payload bodies, and raw callback errors are excluded.",
    "items":{
        "$ref":"#/components/schemas/TransactionCallbackDelivery"
    }
}

Nested Schema : TransactionAttemptSummary

Type: object

Summary of a transaction submission attempt.

Show Source

• attemptId: string
  Unique identifier for the transaction submission attempt.
• attemptNumber: integer
  Sequential number of the submission attempt.
• createdAt: string
  Timestamp when the attempt was created.
• nonce: [ "integer", "null" ] (int64)
  Nonce used for the attempt, when available.
• normalizedErrorCode: [ "string", "null" ]
  Standardized error code for the submission attempt, when available. Use this value to classify failures programmatically.
• sendStatus: string
  Current submission status for the attempt.
• txHash: [ "string", "null" ]
  Transaction hash for the attempt, when available.
• updatedAt: string
  Timestamp when the attempt was last updated.

{
    "type":"object",
    "description":"Summary of a transaction submission attempt.",
    "properties":{
        "attemptId":{
            "type":"string",
            "description":"Unique identifier for the transaction submission attempt."
        },
        "attemptNumber":{
            "type":"integer",
            "description":"Sequential number of the submission attempt."
        },
        "txHash":{
            "type":[
                "string",
                "null"
            ],
            "description":"Transaction hash for the attempt, when available."
        },
        "nonce":{
            "type":[
                "integer",
                "null"
            ],
            "format":"int64",
            "description":"Nonce used for the attempt, when available."
        },
        "sendStatus":{
            "type":"string",
            "description":"Current submission status for the attempt."
        },
        "normalizedErrorCode":{
            "type":[
                "string",
                "null"
            ],
            "description":"Standardized error code for the submission attempt, when available. Use this value to classify failures programmatically."
        },
        "createdAt":{
            "type":"string",
            "description":"Timestamp when the attempt was created."
        },
        "updatedAt":{
            "type":"string",
            "description":"Timestamp when the attempt was last updated."
        }
    }
}

Nested Schema : rawReceipt

Type: object

Additional Properties Allowed: true

Complete transaction receipt returned by Besu. Available only for by-hash lookups with `receiptDetail=full`; it can include receipt logs and topics.

Nested Schema : TransactionCallbackDelivery

Type: object

Redacted callback delivery status for a tracked transaction.

Show Source

• attemptCount: integer
  Number of delivery attempts performed.
• callbackId: integer (int64)
  Unique identifier for the callback delivery.
• createdAt: string
  Timestamp when callback delivery was created.
• deadLetteredAt: [ "string", "null" ]
  Timestamp when delivery entered the dead-letter state, when available.
• deliveredAt: [ "string", "null" ]
  Timestamp when callback delivery succeeded, when available.
• deliveryState: string
  Allowed Values: [ "registered", "pending", "claimed", "delivered", "dead_letter" ]

  Current delivery state of the callback.
• eventType: string
  Transaction lifecycle event associated with the callback.
• lastAttemptAt: [ "string", "null" ]
  Timestamp of the most recent delivery attempt, when available.
• lastError: [ "string", "null" ]
  Concise, sanitized delivery error classification.
• nextAttemptAt: [ "string", "null" ]
  Timestamp of the next scheduled delivery attempt, when available.
• updatedAt: string
  Timestamp when callback delivery was last updated.

{
    "type":"object",
    "description":"Redacted callback delivery status for a tracked transaction.",
    "properties":{
        "callbackId":{
            "type":"integer",
            "format":"int64",
            "description":"Unique identifier for the callback delivery."
        },
        "eventType":{
            "type":"string",
            "description":"Transaction lifecycle event associated with the callback."
        },
        "deliveryState":{
            "type":"string",
            "enum":[
                "registered",
                "pending",
                "claimed",
                "delivered",
                "dead_letter"
            ],
            "description":"Current delivery state of the callback."
        },
        "attemptCount":{
            "type":"integer",
            "description":"Number of delivery attempts performed."
        },
        "nextAttemptAt":{
            "type":[
                "string",
                "null"
            ],
            "description":"Timestamp of the next scheduled delivery attempt, when available."
        },
        "lastAttemptAt":{
            "type":[
                "string",
                "null"
            ],
            "description":"Timestamp of the most recent delivery attempt, when available."
        },
        "deliveredAt":{
            "type":[
                "string",
                "null"
            ],
            "description":"Timestamp when callback delivery succeeded, when available."
        },
        "deadLetteredAt":{
            "type":[
                "string",
                "null"
            ],
            "description":"Timestamp when delivery entered the dead-letter state, when available."
        },
        "lastError":{
            "type":[
                "string",
                "null"
            ],
            "description":"Concise, sanitized delivery error classification."
        },
        "createdAt":{
            "type":"string",
            "description":"Timestamp when callback delivery was created."
        },
        "updatedAt":{
            "type":"string",
            "description":"Timestamp when callback delivery was last updated."
        }
    }
}

Examples

Select an example Submitted tracked operation before receipt correlation Confirmed operation with redacted receipt summary and callback state Operation blocked by a lower managed sender nonce

400 Response

Validation failed.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

404 Response

Transaction operation not found.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

503 Response

Transaction lifecycle service is unavailable.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Back to Top