For the most part, you will likely interact with the blockchain using the Contracts API instead of this low-level API. But there may be rare instanced where you wish to query the blockchain directly.


ethers.blockchain . getBalance ( address [ , blockTag ] )

Returns a Promise with the balance of address (in wei) at blockTag. An address may represent either an account or a contract.

default: blockTag=latest

ethers.blockchain . getTransactionCount ( address [ , blockNumber ] )

Returns a Promise with the number of transactions address has ever sent at blockTag. This is the value required for the nonce in a transaction; both the Contracts API and Wallet API automatically populate this.

default: blockTag=latest



var address = '....';

var balancePromise = ethers.blockchain.getBalance(address, 'latest');
balancePromise.then(function(balance) {

    // The balance is in wei, as a BigNumber object

    // Convert wei to a string in ether
    var etherString = ethers.utils.formatEther(balance);

    console.log('Balance: ' + etherString);

Transaction Count

var transactionCount = ethers.blockchain.getTransactionCount(address, 'latest');

transactionCount.then(function(transactionCount) {
    // The transactionCount is a normal JavaScript Number

    console.log('Transactions Sent: ' + transactionCount);

Blockchain State

ethers.blockchain . getGasPrice ( )
Return a Promise with the current gas price, in wei.
ethers.blockchain . getBlockNumber ( )
Return a Promise with the number of the most recent block.
ethers.blockchain . getBlock ( blockhashOrNumber )
Return a Promise with the block details of blockhashOrNumber.
ethers.blockchain . getTransaction ( transactionHash )
Return a Promise with the transaction details of transactionHash.
ethers.blockchain . getTransactionReceipt ( transactionHash )
Return a Promise with the transaction receipt of hash. A transaction receipt includes information about a mined transaction, such as actualy gas costs.



Running Code

ethers.blockchain . call ( transaction ):
Returns a Promise with the result of executing the read-only (constant) transaction.
ethers.blockchain . estimateGas ( transaction ):
Returns a Promise with the estimated cost of executing transaction. This may be useful if you wish to override the gasLimit when calling ethers.sendTransaction().


Calling read-only (constant) Functions

var transaction = {

    // This is the address of Zen Messenger on Testnet
    to: "",

    // This is the name of the compiled function
    data: "",

var callPromise =;

callPromise.then(function(result) {
    // 0x....
    // This is the length-prefixed, UTF-8 encoded string of "Hello World"


ethers.blockchain . onblock
This event callback is triggered everytime a new block has been mined.


ethers.blockchain.onblock = function(blockNumber) {
    console.log('New Block Mined: ' + blockNumber);