web3.js

Ethereum JavaScript API

Comment

web3.js - Ethereum JavaScript API

Join the chat at https://gitter.im/ethereum/web3.jsnpm [![Build Status][travis-image]][travis-url] [![dependency status][dep-image]][dep-url] [![dev dependency status][dep-dev-image]][dep-dev-url] [![Coverage Status][coveralls-image]][coveralls-url] lerna

This is the Ethereum [JavaScript API][docs] 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][docs] for more.

Installation

Node

npm install web3

Yarn

yarn add web3

Meteor

Note: works only in the Browser for now. (PR welcome).

meteor add ethereum:web3

In the Browser

Use the prebuild dist/web3.min.js, or build using the [web3.js][repo] repository:

npm run-script build

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

Usage

// in node.js
var Web3 = require('web3');

var web3 = new Web3('ws://localhost:8546');
console.log(web3);
> {
    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';
const web3 = new Web3('ws://localhost:8546');

If you are using the types in a commonjs module like for example a node app you just have to enable esModuleInterop in your tsconfig compile option, also enable allowSyntheticDefaultImports for typesystem compatibility:

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

Documentation

Documentation can be found at [read the docs][docs].

Building

Requirements

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

Building (gulp)

Build only the web3.js package

npm run-script build

Or build all sub packages as well:

npm run-script build-all

This will put all the browser build files into the dist folder.

Testing (mocha)

npm test

Contributing

  • All contributions have to go into 1.x, or the 2.x branch
  • Please follow the code style of the other files, we use 4 spaces as tabs.

Community

Similar libraries in other languages

[repo]: https://github.com/ethereum/web3.js [docs]: http://web3js.readthedocs.io/ [npm-image]: https://badge.fury.io/js/web3.png [npm-url]: https://npmjs.org/package/web3 [travis-image]: https://travis-ci.org/ethereum/web3.js.svg [travis-url]: https://travis-ci.org/ethereum/web3.js [dep-image]: https://david-dm.org/ethereum/web3.js.svg [dep-url]: https://david-dm.org/ethereum/web3.js [dep-dev-image]: https://david-dm.org/ethereum/web3.js/dev-status.svg [dep-dev-url]: https://david-dm.org/ethereum/web3.js#info=devDependencies [coveralls-image]: https://coveralls.io/repos/ethereum/web3.js/badge.svg?branch=master [coveralls-url]: https://coveralls.io/r/ethereum/web3.js?branch=1.x [waffle-image]: https://badge.waffle.io/ethereum/web3.js.svg?label=ready&title=Ready [waffle-url]: https://waffle.io/ethereum/web3.js

Share this project:

Updates