Docs »
web3.eth.subscribe
Edit on GitHub

Note

This documentation is work in progress and web3.js 1.0 is not yet released! You can find the current documentation for web3 0.x.x at github.com/ethereum/wiki/wiki/JavaScript-API.

web3.eth.subscribe¶

The web3.eth.subscribe function lets you subscribe to specific events in the blockchain.

subscribe¶

web3.eth.subscribe(type [, options] [, callback]);

Parameters¶

String - The subscription, you want to subscribe to.
Mixed - (optional) Optional additional parameters, depending on the subscription type.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription, and the subscription itself as 3 parameter.

Returns¶

EventEmitter - A Subscription instance

subscription.id: The subscription id, used to identify and unsubscribing the subscription.

subscription.subscribe([callback]): Can be used to re-subscribe with the same parameters.

subscription.unsubscribe([callback]): Unsubscribes the subscription and returns TRUE in the callback if successfull.

subscription.arguments: The subscription arguments, used when re-subscribing.

on("data") returns Object: Fires on each incoming log with the log object as argument.

on("changed") returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".

on("error") returns Object: Fires when an error in the subscription occours.

Notification returns¶

Mixed - depends on the subscription, see the different subscriptions for more.

Example¶

var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(log);
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

clearSubscriptions¶

web3.eth.clearSubscriptions()

Resets subscriptions.

Note

This will not reset subscriptions from other packages like web3-shh, as they use their own requestManager.

Parameters¶

Boolean: If true it keeps the "syncing" subscription.

Returns¶

Boolean

Example¶

web3.eth.subscribe('logs', {} ,function(){ ... });

...

web3.eth.clearSubscriptions();

subscribe(“pendingTransactions”)¶

web3.eth.subscribe('pendingTransactions' [, callback]);

Subscribes to incoming pending transactions.

Parameters¶

String - "pendingTransactions", the type of the subscription.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns¶

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming pending transaction.
"error" returns Object: Fires when an error in the subscription occours.

For the structure of the returned object see web3.eth.getTransaction() return values.

Notification returns¶

Object|Null - First parameter is an error object if the subscription failed.
Object - The block header object like above.

Example¶

var subscription = web3.eth.subscribe('pendingTransactions', function(error, result){
    if (!error)
        console.log(transaction);
})
.on("data", function(transaction){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“newBlockHeaders”)¶

web3.eth.subscribe('newBlockHeaders' [, callback]);

Subscribes to incoming block headers. This can be used as timer to check for changes on the blockchain.

Parameters¶

String - "newBlockHeaders", the type of the subscription.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns¶

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming block header.
"error" returns Object: Fires when an error in the subscription occours.

The structure of a returned block header is as follows:

number - Number: The block number. null when its pending block.

hash 32 Bytes - String: Hash of the block. null when its pending block.

parentHash 32 Bytes - String: Hash of the parent block.

nonce 8 Bytes - String: Hash of the generated proof-of-work. null when its pending block.

sha3Uncles 32 Bytes - String: SHA3 of the uncles data in the block.

logsBloom 256 Bytes - String: The bloom filter for the logs of the block. null when its pending block.

transactionsRoot 32 Bytes - String: The root of the transaction trie of the block

stateRoot 32 Bytes - String: The root of the final state trie of the block.

receiptRoot 32 Bytes - String: The root of the receipts.

miner - String: The address of the beneficiary to whom the mining rewards were given.

extraData - String: The “extra data” field of this block.

gasLimit - Number: The maximum gas allowed in this block.

gasUsed - Number: The total used gas by all transactions in this block.

timestamp - Number: The unix timestamp for when the block was collated.

Notification returns¶

Object|Null - First parameter is an error object if the subscription failed.
Object - The block header object like above.

Example¶

var subscription = web3.eth.subscribe('newBlockHeaders', function(error, result){
    if (!error)
        console.log(error);
})
.on("data", function(blockHeader){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“syncing”)¶

web3.eth.subscribe('syncing' [, callback]);

Subscribe to syncing events. This will return an object when the node is syncing and when its finished syncing will return FALSE.

Parameters¶

String - "syncing", the type of the subscription.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns¶

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming sync object as argument.
"changed" returns Object: Fires when the synchronisation is started with true and when finsihed with false.
"error" returns Object: Fires when an error in the subscription occours.

For the structure of a returned event Object see web3.eth.isSyncing return values.

Notification returns¶

Object|Null - First parameter is an error object if the subscription failed.
Object|Boolean - The syncing object, when started it will return true once or when finished it will return false once.

Example¶

var subscription = web3.eth.subscribe('syncing', function(error, sync){
    if (!error)
        console.log(sync);
})
.on("data", function(sync){
    // show some syncing stats
})
.on("changed", function(isSyncing){
    if(isSyncing) {
        // stop app operation
    } else {
        // regain app operation
    }
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“logs”)¶

web3.eth.subscribe('logs', options [, callback]);

Subscribes to incoming logs, filtered by the given options.

Parameters¶

"logs" - String, the type of the subscription.
Object - The subscription options

fromBlock - Number: The number of the earliest block. By default null.

address - String: An address or a list of addresses to only get logs from particular account(s).

topics - Array: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x00...']. You can also pass another array for each topic with options for that topic e.g. [null, ['option1', 'option2']]

callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns¶

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming log with the log object as argument.
"changed" returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
"error" returns Object: Fires when an error in the subscription occours.

For the structure of a returned event Object see web3.eth.getPastEvents return values.

Notification returns¶

Object|Null - First parameter is an error object if the subscription failed.
Object - The log object like in web3.eth.getPastEvents return values.

Example¶

var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(log);
})
.on("data", function(log){
})
.on("changed", function(log){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

Next Previous

Built with Sphinx using a theme provided by Read the Docs.