transactionStatus

Name: transactionStatus

transactionStatus is a stream that shows the real-time status of transactions as they propagate throughout the Ethereum network. For example, this allows users to know the exact moment their transaction is confirmed, i.e. has been included in enough blocks that it is considered confirmed.

To use the transactionStatus stream, you first need to subscribe to the stream. Then you need to request monitoring for transactions for which you would like to receive status updates. Transactions can be yours or someone else's. In order to monitor a transaction, you need to send the signed raw transaction to the Cloud-API (note: Sending only the transaction hash is not sufficient because the Cloud-API might not have the transaction you want to monitor.). This is a Cloud-API (wss://api.blxrbdn.com/ws) only stream. The stream will return an event every time a status is changed for one of the monitored transactions. Please review the list of possible statuses at the bottom of the page. The stream supports two methods as documented below.

Method: start_monitor_transaction

Description: Submits transactions for monitoring. Cloud-API automatically starts monitoring transactions submitted by the same sender that have the same nonce.

Parameters

Parameter	Description
transactions	[Mandatory] List of raw transaction bytes without 0x prefix.
subscription_id	[Mandatory] The returned subscription ID from initial transactionStatus stream subscription
blockchain_network	[Optional, default: Mainnet] The blockchain network for the transaction. (note: It should match with the blockchain_network provided in the initial transactionStatus subscribe request.)

Method: stop_monitor_transaction

Description: Stops monitoring a transaction.

Parameters

Parameter	Description
transaction_hash	[Mandatory] Transaction hash without 0x prefix.
subscription_id	[Mandatory] The returned subscription ID from initial transactionStatus stream subscription
blockchain_network	[Optional, default: Mainnet] The blockchain network for the transaction. (note: It should match with the blockchain_network provided in the initial transactionStatus subscribe request.)

Requests Examples

Python-Subscribe to the feed

Subscribing to the Cloud-API transactionStatus stream in Python (Line 7 creates the subscription):

import asyncio
from bxcommon.rpc.provider.cloud_wss_provider import CloudWssProvider
async def main():
    async with CloudWssProvider(
        ssl_dir="/usr/bloxroute/certificate/external_gateway/registration_only"
    ) as ws:
        subscription_id = await ws.subscribe("transactionStatus", {"include": ["tx_hash", "status"]})
        while True:
            next_notification = await ws.get_next_subscription_notification_by_id(subscription_id)
            print(next_notification)  # or process it generally
        await ws.unsubscribe(subscription_id)
if __name__ == '__main__':
    asyncio.get_event_loop().run_until_complete(main())

Python-Start Monitor

import asyncio
from bxcommon.rpc.provider.ws_provider import WsProvider
from bxcommon.rpc.rpc_request_type import RpcRequestType

async def main():
    async with WsProvider(
        uri="wss://api.blxrbdn.com/ws",
        headers={"Authorization": <YOUR_AUTHORIZATION_HEADER>}
    ) as ws:
        ... # subscrib to transactionStatus, and get the subscription_id
        result = await ws.call_bx(RpcRequestType.START_MONITOR_TRANSACTION, {"transactions": ["f86b0184...e0b58219"], "subscription_id":subscription_id})
        print(result)  # or process it generally
if __name__ == '__main__':
    asyncio.get_event_loop().run_until_complete(main())

Python-Stop Monitor

import asyncio
from bxcommon.rpc.provider.ws_provider import WsProvider
from bxcommon.rpc.rpc_request_type import RpcRequestType

async def main():
    async with WsProvider(
        uri="wss://api.blxrbdn.com/ws",
        headers={"Authorization": <YOUR_AUTHORIZATION_HEADER>}
    ) as ws:
        ... # subscrib to transactionStatus, and get the subscription_id
        result = await ws.call_bx(RpcRequestType.STOP_MONITOR_TRANSACTION, {"transaction_hash": "f86b0184...e0b58219", "subscription_id": subscription_id})
        print(result)  # or process it generally
if __name__ == '__main__':
    asyncio.get_event_loop().run_until_complete(main())

wscat

wscat -c wss://api.blxrbdn.com/ws --header "Authorization: <YOUR-AUTHORIZATION-HEADER>"
> {"jsonrpc":"2.0","id":1,"method":"subscribe","params":["transactionStatus",{"include":["tx_hash","status"]}]}
< {"jsonrpc": "2.0", "id": 1, "result": "3bb82078-c895-4b31-9f59-c376ef2b26f6"}
> {"jsonrpc":"2.0","id":1,"method":"start_monitor_transaction","params":{"transactions":["f87...581"],"subscription_id":"3bb82078-c895-4b31-9f59-c376ef2b26f6"}}
< {"jsonrpc": "2.0", "id": 1, "result": {"success": true}}
> {"jsonrpc":"2.0","id":1,"method":"stop_monitor_transaction","params":{"transaction_hash":"311...875"}}
< {"jsonrpc": "2.0", "id": 1, "result": {"success": true}}

Possible statuses are:

Status	Description
UNKNOWN	The transaction is not recognized.
TX_POOL	The transaction was received by a blockchain node and accepted to its tx pool.
MINED	The transaction was included in a block.
CANCELED	The transaction is canceled.
REPLACED	Received a new transaction with the same address and nonce as the monitored transaction.

Results Example

Transaction Status Event

<<< {"jsonrpc": "2.0", "id": null, "method": "subscribe", 
     "params": {"subscription": "909e4bae-2c48-43f3-a007-f17d4c8a3ce8",
     "result": {"txHash": "14f3d7a1553b252b89....3214f3de", 
                "status": TX_POOL
                }