Ethereum-JavaScript API

JavaScript API

Contents

• Web3 JavaScript app API for 0.2x.x
  • Getting Started
    • Adding web3
    • Using callbacks
    • Batch requests
    • A note on big numbers in web3.js
  • Web3.js API Reference
    • Usage
      • web3
        • Example
          • Example using HTTP Basic Authentication
      • web3.version.api
        • Returns
        • Example
      • web3.version.node
        • Returns
        • Example
      • web3.version.network
        • Returns
        • Example
      • web3.version.ethereum
        • Returns
        • Example
      • web3.version.whisper
        • Returns
        • Example
      • web3.isConnected
        • Parameters
        • Returns
        • Example
      • web3.setProvider
        • Parameters
        • Returns
        • Example
      • web3.currentProvider
        • Returns
        • Example
      • web3.reset
        • Parameters
        • Returns
        • Example
      • web3.sha3
        • Parameters
        • Returns
        • Example
      • web3.toHex
        • Parameters
        • Returns
        • Example
      • web3.toAscii
        • Parameters
        • Returns
        • Example
      • web3.fromAscii
        • Parameters
        • Returns
        • Example
      • web3.toDecimal
        • Parameters
        • Returns
        • Example
      • web3.fromDecimal
        • Parameters
        • Returns
        • Example
      • web3.fromWei
        • Parameters
        • Returns
        • Example
      • web3.toWei
        • Parameters
        • Returns
        • Example
      • web3.toBigNumber
        • Parameters
        • Returns
        • Example
      • web3.isAddress
        • Parameters
        • Returns
        • Example
    • web3.net
      • web3.net.listening
        • Returns
        • Example
      • web3.net.peerCount
        • Returns
        • Example
    • web3.eth
      • Example
      • web3.eth.defaultAccount
        • Values
        • Returns
        • Example
      • web3.eth.defaultBlock
        • Values
        • Returns
        • Example
      • web3.eth.syncing
        • Returns
        • Example
      • web3.eth.isSyncing
        • Returns
        • Callback return value
        • Example
      • web3.eth.coinbase
        • Returns
        • Example
      • web3.eth.mining
        • Returns
        • Example
      • web3.eth.hashrate
        • Returns
        • Example
      • web3.eth.gasPrice
        • Returns
        • Example
      • web3.eth.accounts
        • Returns
        • Example
      • web3.eth.blockNumber
        • Returns
        • Example
      • web3.eth.register
        • Parameters
        • Returns
        • Example
      • web3.eth.unRegister
        • Parameters
        • Returns
        • Example
      • web3.eth.getBalance
        • Parameters
        • Returns
        • Example
      • web3.eth.getStorageAt
        • Parameters
        • Returns
        • Example
      • web3.eth.getCode
        • Parameters
        • Returns
        • Example
      • web3.eth.getBlock
        • Parameters
        • Returns
        • Example
      • web3.eth.getBlockTransactionCount
        • Parameters
        • Returns
        • Example
      • web3.eth.getUncle
        • Parameters
        • Returns
        • Example
      • web3.eth.getTransaction
        • Parameters
        • Returns
        • Example
      • web3.eth.getTransactionFromBlock
        • Parameters
        • Returns
        • Example
      • web3.eth.getTransactionReceipt
        • Parameters
        • Returns
        • Example
      • web3.eth.getTransactionCount
        • Parameters
        • Returns
        • Example
      • web3.eth.sendTransaction
        • Parameters
        • Returns
        • Example
      • web3.eth.sendRawTransaction
        • Parameters
        • Returns
        • Example
      • web3.eth.sign
        • Parameters
        • Returns
        • Example
      • web3.eth.call
        • Parameters
        • Returns
        • Example
      • web3.eth.estimateGas
        • Parameters
        • Returns
        • Example
      • web3.eth.filter
        • Parameters
        • Returns
        • Watch callback return value
        • Example
      • web3.eth.contract
        • Parameters
        • Returns
        • Example
      • Contract Methods
        • Parameters
        • Returns
        • Example
      • Contract Events
        • Parameters
        • Callback return
        • Example
      • Contract allEvents
        • Parameters
        • Callback return
        • Example
      • web3.eth.getCompilers
  • Compiling features being deprecated https://github.com/ethereum/EIPs/issues/209 - Parameters - Returns - Example
    • web3.eth.compile.solidity
      • Parameters
      • Returns
      • Example
    • web3.eth.compile.lll
      • Parameters
      • Returns
      • Example
    • web3.eth.compile.serpent
      • Parameters
      • Returns
    • web3.eth.namereg
      • Usage
    • web3.db
      • web3.db.putString
        • Parameters
        • Returns
        • Example
      • web3.db.getString
        • Parameters
        • Returns
        • Example
      • web3.db.putHex
        • Parameters
        • Returns
        • Example
      • web3.db.getHex
        • Parameters
        • Returns
        • Example
    • web3.shh
      • Example
      • web3.shh.post
        • Parameters
        • Returns
        • Example
      • web3.shh.newIdentity
        • Parameters
        • Returns
        • Example
      • web3.shh.hasIdentity
        • Parameters
        • Returns
        • Example
      • web3.shh.newGroup
        • Example
      • web3.shh.addToGroup
        • Example
      • web3.shh.filter
        • Parameters
        • Callback return
      • web3.eth.sendIBANTransaction
        • Parameters
      • web3.eth.iban
      • web3.eth.iban.fromAddress
      • web3.eth.iban.fromBban
      • web3.eth.iban.createIndirect
      • web3.eth.iban.isValid
      • web3.eth.iban.isDirect
      • web3.eth.iban.isIndirect
      • web3.eth.iban.checksum
      • web3.eth.iban.institution
      • web3.eth.iban.client
      • web3.eth.iban.address
      • web3.eth.iban.toString

Web3 JavaScript app API for 0.2x.x

NOTE: These docs are for web3.js version 0.2x.x. If you’re using web3.js 1.0 please refer to this documentation.

To make your app work on Ethereum, you can use the web3 object provided by the web3.js library. Under the hood it communicates to a local node through RPC calls. web3.js works with any Ethereum node, which exposes an RPC layer.

web3 contains the eth object - web3.eth (for specifically Ethereum blockchain interactions) and the shh object - web3.shh (for Whisper interaction). Over time we'll introduce other objects for each of the other web3 protocols. Working examples can be found here.

If you want to look at some more sophisticated examples using web3.js check out these useful app patterns.

Getting Started

• Adding web3
• Using Callbacks
• Batch requests
• A note on big numbers in web3.js
• -> API Reference

Adding web3

First you need to get web3.js into your project. This can be done using the following methods:

• npm: npm install web3
• bower: bower install web3
• meteor: meteor add ethereum:web3
• vanilla: link the dist./web3.min.js

Then you need to create a web3 instance, setting a provider. To make sure you don't overwrite the already set provider when in mist, check first if the web3 is available:

if (typeof web3 !== 'undefined') {
  web3 = new Web3(web3.currentProvider);
} else {
  // set the provider you want from Web3.providers
  web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545"));
}

After that you can use the API of the web3 object.

Using callbacks

As this API is designed to work with a local RPC node, all its functions use synchronous HTTP requests by default.

If you want to make an asynchronous request, you can pass an optional callback as the last parameter to most functions. All callbacks are using an error first callback style:

web3.eth.getBlock(48, function(error, result){
    if(!error)
        console.log(JSON.stringify(result));
    else
        console.error(error);
})

Batch requests

Batch requests allow queuing up requests and processing them at once.

Note Batch requests are not faster! In fact making many requests at once will in some cases be faster, as requests are processed asynchronously. Batch requests are mainly useful to ensure the serial processing of requests.

var batch = web3.createBatch();
batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
batch.add(web3.eth.contract(abi).at(address).balance.request(address, callback2));
batch.execute();

A note on big numbers in web3.js

You will always get a BigNumber object for number values as JavaScript is not able to handle big numbers correctly. Look at the following examples:

"101010100324325345346456456456456456456"
// "101010100324325345346456456456456456456"
101010100324325345346456456456456456456
// 1.0101010032432535e+38

web3.js depends on the BigNumber Library and adds it automatically.

var balance = new BigNumber('131242344353464564564574574567456');
// or var balance = web3.eth.getBalance(someAddress);

balance.plus(21).toString(10); // toString(10) converts it to a number string
// "131242344353464564564574574567477"

The next example wouldn't work as we have more than 20 floating points, therefore it is recommended to always keep your balance in wei and only transform it to other units when presenting to the user:

var balance = new BigNumber('13124.234435346456466666457455567456');

balance.plus(21).toString(10); // toString(10) converts it to a number string, but can only show upto 20 digits
// "13145.23443534645646666646" // your number will be truncated after the 20th digit

Web3.js API Reference

• web3
  • version
    • api
    • node/getNode
    • network/getNetwork
    • ethereum/getEthereum
    • whisper/getWhisper
  • isConnected()
  • setProvider(provider)
  • currentProvider
  • reset()
  • sha3(string, options)
  • toHex(stringOrNumber)
  • toAscii(hexString)
  • fromAscii(textString, [padding])
  • toDecimal(hexString)
  • fromDecimal(number)
  • fromWei(numberStringOrBigNumber, unit)
  • toWei(numberStringOrBigNumber, unit)
  • toBigNumber(numberOrHexString)
  • isAddress(hexString)
  • net
    • listening/getListening
    • peerCount/getPeerCount
  • eth
    • defaultAccount
    • defaultBlock
    • syncing/getSyncing
    • isSyncing
    • coinbase/getCoinbase
    • hashrate/getHashrate
    • gasPrice/getGasPrice
    • accounts/getAccounts
    • mining/getMining
    • blockNumber/getBlockNumber
    • register(hexString) (Not implemented yet)
    • unRegister(hexString) (Not implemented yet)
    • getBalance(address)
    • getStorageAt(address, position)
    • getCode(address)
    • getBlock(hash/number)
    • getBlockTransactionCount(hash/number)
    • getUncle(hash/number)
    • getBlockUncleCount(hash/number)
    • getTransaction(hash)
    • getTransactionFromBlock(hashOrNumber, indexNumber)
    • getTransactionReceipt(hash)
    • getTransactionCount(address)
    • sendTransaction(object)
    • sendRawTransaction(object)
    • sign(object)
    • call(object)
    • estimateGas(object)
    • filter(array (, options) )
      • watch(callback)
      • stopWatching(callback)
      • get()
    • Contract(abiArray)
    • contract.myMethod()
    • contract.myEvent()
    • contract.allEvents()
    • getCompilers()
    • compile.lll(string)
    • compile.solidity(string)
    • compile.serpent(string)
    • namereg
    • sendIBANTransaction
    • iban
      • fromAddress
      • fromBban
      • createIndirect
      • isValid
      • isDirect
      • isIndirect
      • checksum
      • institution
      • client
      • address
      • toString
  • db
    • putString(name, key, value)
    • getString(- var rXArray = stringToNumberArray(form.rX.value); name, key)
    • putHex(name, key, value)
    • getHex(name, key)
  • shh
    • post(postObject)
    • newIdentity()
    • hasIdentity(hexString)
    • newGroup(_id, _who)
    • addToGroup(_id, _who)
    • filter(object/string)
      • watch(callback)
      • stopWatching(callback)
      • get(callback)