Web3.js 4.x has been released. Checkout 4.x API documentation and migration guide for testing, early feedback and contributions.

This is the Ethereum JavaScript API which connects to the Generic JSON-RPC spec.

You need to run a local or remote Ethereum node to use this library.

Please read the documentation for more.

Installation

Node

Yarn

In the Browser

Use the prebuilt dist/web3.min.js, or build using the web3.js repository:

Then include dist/web3.min.js in your html file. This will expose Web3 on the window object.

Or via jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>

UNPKG:

<script src="https://unpkg.com/web3@latest/dist/web3.min.js"></script>

Usage

// In Node.js
const Web3 = require('web3');
const web3 = new Web3('ws://localhost:8546');
console.log(web3);
// Output
{
    eth: ... ,
    shh: ... ,
    utils: ...,
    ...
}

Additionally you can set a provider using web3.setProvider() (e.g. WebsocketProvider):

web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

There you go, now you can use it:

web3.eth.getAccounts().then(console.log);

Usage with TypeScript

We support types within the repo itself. Please open an issue here if you find any wrong types.

You can use web3.js as follows:

import Web3 from 'web3';
import { BlockHeader, Block } from 'web3-eth' // ex. package types
const web3 = new Web3('ws://localhost:8546');

If you are using the types in a commonjs module, like in a Node app, you just have to enable esModuleInterop and allowSyntheticDefaultImports in your tsconfig for typesystem compatibility:

"compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    ....

Troubleshooting and known issues.

Web3 and Create-react-app

If you are using create-react-app version >=5 you may run into issues building. This is because NodeJS polyfills are not included in the latest version of create-react-app.

Solution

• Install react-app-rewired and the missing modules

If you are using yarn:

yarn add --dev react-app-rewired process crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer

If you are using npm:

npm install --save-dev react-app-rewired crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process

• Create config-overrides.js in the root of your project folder with the content:

const webpack = require('webpack');

module.exports = function override(config) {
    const fallback = config.resolve.fallback || {};
    Object.assign(fallback, {
        "crypto": require.resolve("crypto-browserify"),
        "stream": require.resolve("stream-browserify"),
        "assert": require.resolve("assert"),
        "http": require.resolve("stream-http"),
        "https": require.resolve("https-browserify"),
        "os": require.resolve("os-browserify"),
        "url": require.resolve("url")
    })
    config.resolve.fallback = fallback;
    config.plugins = (config.plugins || []).concat([
        new webpack.ProvidePlugin({
            process: 'process/browser',
            Buffer: ['buffer', 'Buffer']
        })
    ])
    return config;
}

• Within package.json change the scripts field for start, build and test. Instead of react-scripts replace it with react-app-rewired

before:

"scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
},

after:

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
},

The missing Nodejs polyfills should be included now and your app should be functional with web3.

• If you want to hide the warnings created by the console:

In config-overrides.js within the override function, add:

config.ignoreWarnings = [/Failed to parse source map/];

Web3 and Angular

New solution

If you are using Angular version >11 and run into an issue building, the old solution below will not work. This is because polyfills are not included in the newest version of Angular.

• Install the required dependencies within your angular project:

npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify

• Within tsconfig.json add the following paths in compilerOptions so Webpack can get the correct dependencies

{
    "compilerOptions": {
        "paths" : {
        "crypto": ["./node_modules/crypto-browserify"],
        "stream": ["./node_modules/stream-browserify"],
        "assert": ["./node_modules/assert"],
        "http": ["./node_modules/stream-http"],
        "https": ["./node_modules/https-browserify"],
        "os": ["./node_modules/os-browserify"],
    }
}

• Add the following lines to polyfills.ts file:

import { Buffer } from 'buffer';

(window as any).global = window;
global.Buffer = Buffer;
global.process = {
    env: { DEBUG: undefined },
    version: '',
    nextTick: require('next-tick')
} as any;

Old solution

If you are using Ionic/Angular at a version >5 you may run into a build error in which modules crypto and stream are undefined

a workaround for this is to go into your node-modules and at /angular-cli-files/models/webpack-configs/browser.js change the node: false to node: {crypto: true, stream: true} as mentioned here

Another variation of this problem was an issue opned on angular-cli

Documentation

Documentation can be found at ReadTheDocs.

Building

Requirements

• Node.js
• npm

sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npm

Building (webpack)

Build the web3.js package:

Testing (mocha)

Contributing

Please follow the Contribution Guidelines and Review Guidelines.

This project adheres to the Release Guidelines.

Community

• Discord
• StackExchange

Similar libraries in other languages

• Haskell: hs-web3
• Java: web3j
• PHP: web3.php
• Purescript: purescript-web3
• Python: Web3.py
• Ruby: ethereum.rb
• Scala: web3j-scala

Semantic versioning

This project follows semver as closely as possible from version 1.3.0 onwards. Earlier minor version bumps might have included breaking behavior changes.