eth_subscribe

The eth_subscribe command allows you to subscribe to multiple types of events such as newHeads, logs, newPendingTransactions, and syncing and enables syncing via WebSockets.

warning

This method is only available when using a WebSocket connection.

All subscriptions will be removed once the WebSocket connection is dropped.

warning

eth_subscribe() method call is not available within the Public API.

Parameters

1. Subscription type
2. Optional arguments depending on the subscription type

Subscription Types

newHeads

Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interesting to them.

In case of a chain reorganization, the subscription will emit all new headers for the new chain. Therefore the subscription can emit multiple headers on the same height.

eth_subscribe Example Request and Result for newHeads Event

>> {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_subscribe",
    "params": [
        "newHeads"
    ]
}
<< {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x20b6b348ddfa17b5ba707431dc8da988"
}

>> {
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0x20b6b348ddfa17b5ba707431dc8da988",
        "result": {
            "parentHash": "0x4885842da506731b17f1719d762b281e09a153f2d61b505c5a673e0125e2d9c2",
            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "miner": "0x2a20380dca5bc24d052acfbf79ba23e988ad0050",
            "stateRoot": "0x686c48414e8540c15ec2d3e15abadb6de18aa334b048a3e2e15a2a55d306bb83",
            "transactionsRoot": "0xc016b794fecf26cb59da456240cce4effe0fa94b27cf65bdcdfb66eb657b3caa",
            "receiptsRoot": "0x189819c4ed188a2a073c22be920ab2c340943d5e9bd6de054eadf1c3a8f52c94",
            "logsBloom": "0x5fbb8bbff1fa9ca7ffe83ffecf5bf37fc52dfa7f9dde5f6e2df9f9ef9fba6dffda5fb76ba783f7f30f575fd569f15fdfde3bdf771a94bda7fadecfe2d73fa14f79df45f2f7f20d3ff9b65d3bd274fba42ce3e9968f5e7aca7ff7f611eaf3f8f96ec5d2d0dba6437e0feeb1bb7eb87f79aeb7c778e8ffb5695f6d9bfe0ddff73ab99fef67e3e2dbfeb55b7c3f5fdffdf6f5f51fff5dab666c4f29edce7fd75abee7dabd7bafbe3dbebbbc5fdafffd0f2fcf77c22fffea0ede7defaee6feef4c5b2f5ffeef09f926572cfd69e8e9ff5abf36ff77763dab0e34b2fdffef3e6a642fdffb6f6f9f1e85abe6ae97a8a9046f99ff73d5fda7dfebf620fe7fdec8867ff3",
            "difficulty": "0x2f3255c3d69584",
            "number": "0xdc01a0",
            "gasLimit": "0x1c95111",
            "gasUsed": "0x1c919bb",
            "timestamp": "0x62361896",
            "extraData": "0x706f6f6c696e2e636f6d21ed073691b505ffd2",
            "mixHash": "0xc43186c61d5589ce4247f48a288df01f35e4fc3667b46bbbce887f9a369e50e1",
            "nonce": "0xec4f61864a67e65e",
            "baseFeePerGas": "0x495990270",
            "hash": "0xae276242b8ec854b2203469cb5ad3303d595b731eba20ccbd8a703b135f5f1d2"
        }
    }
}

logs

Returns logs that are included in new imported blocks and match the given filter criteria.

In case of a chain reorganization previous sent logs that are on the old chain will be resent with the removed property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times.

Arguments

1. object with the following (optional) fields
   • address, either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
   • topics, only logs that match the specified topics (optional)

eth_subscribe Example Request and Result for logs Event

>> {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_subscribe",
    "params": [
        "logs",
        {
            "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
            "topics": [
                "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"
            ]
        }
    ]
}
<< {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4a8a4c0517381924f9838102c5a4dcb7"
}

<< {
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
        "result": {
            "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
            "blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
            "blockNumber": "0x29e87",
            "data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
            "logIndex": "0x0",
            "topics": [
                "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"
            ],
            "transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
            "transactionIndex": "0x0"
        }
    }
}

newPendingTransactions

Returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node.

When a transaction that was previously part of the canonical chain isn’t part of the new canonical chain after a reorganization its again emitted.

eth_subscribe Example Request and Result for newPendingTransactions Event

>> {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_subscribe",
    "params": [
        "newPendingTransactions"
    ]
}
<< {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0xc3b33aa549fb9a60e95d21862596617c"
}
<< {
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0xc3b33aa549fb9a60e95d21862596617c",
        "result": "0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
    }
}

syncing

Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators.

eth_subscribe Example Request and Result for syncing Event

>> {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_subscribe",
    "params": [
        "syncing"
    ]
}
<< {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0xe2ffeb2703bcf602d42922385829ce96"
}

<< {
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0xe2ffeb2703bcf602d42922385829ce96",
        "result": {
            "syncing": true,
            "status": {
                "startingBlock": 674427,
                "currentBlock": 67400,
                "highestBlock": 674432,
                "pulledStates": 0,
                "knownStates": 0
            }
        }
    }
}