Skip to content
A CLI tool to interact with web3 blockchains - Ethereum, GoChain, etc
Branch: master
Clone or download
Latest commit b81e581 Mar 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci upgrade Dockerfile and CI to go1.12 (#74) Feb 28, 2019
assets Gen cleanup (#84) Mar 20, 2019
contracts Improved docs (#48) Feb 6, 2019
abi_wrapper.go [WIP]Generate boilerplate or no code deploy common contracts #77 (#78) Mar 13, 2019
accounts.go Added web3 start command (#55) Feb 13, 2019
go.mod Added web3 start command (#55) Feb 13, 2019
go.sum Add an installer script #5 (#43) Feb 5, 2019
types.go support either tx hashes or full details; output tx input data in var… Feb 22, 2019
web3.go Add a send or transfer command for GO #62 (#75) Feb 28, 2019


Simple command line tool for interacting with web3 enabled blockchains - GoChain, Ethereum, etc. This repository also exports the backing golang package web3.

API Reference

Install web3

Quick one line install:

curl -LSs | sh

Install Docker (optional) - While not required for all commands, many of the developer commands require Docker so we recommend installing it.

More options


If you just plan to read from the blockchain, you do not need any GO tokens and you do not need to set your PRIVATE_KEY. If you plan to deploy contracts or write anything to the blockchain, you'll need tokens and you'll need to set your PRIVATE_KEY for the account that has those tokens.

Pick a network to use

a) Run a local node

Run this command to start a local node. It will print 10 addresses with keys upon starting that you can use to deploy and interact.

web3 start
export WEB3_NETWORK=localhost

b) Use the GoChain testnet

export WEB3_NETWORK=testnet

To do any write operations, get yourself some GO testnet tokens so you can deploy and interact with your contract.

c) Use the GoChain mainnet or another web3 network

export WEB3_NETWORK=gochain

You'll need mainnet GO for this which you can buy on various exchanges.

You can also point this to other web3 based networks such as Ethereum. Ethereum is supported by default and you can use one of the following: ethereum or ropsten.

Set Private Key (optional)

Required if you plan to deploy or write transactions.

export WEB3_PRIVATE_KEY=0x...

Deploy a contract

Copy contracts/hello.sol into your current directory.


web3 contract build hello.sol
web3 contract deploy Hello.bin

This will return a contract address, copy it and use below.

Read from a contract

Let's call a read function (which is free):

web3 contract call --address 0xCONTRACT_ADDRESS --abi Hello.abi --function hello

That should return: [Hello World].

Write to a contract

Now let's change the name:

web3 contract call --address 0xCONTRACT_ADDRESS --abi Hello.abi --function setName "Johnny"

And call the hello function again to see if the name changed:

web3 contract call --address 0xCONTRACT_ADDRESS --abi Hello.abi --function hello

Now it should return [Hello Johnny]



If it doesn't return Hello Johnny, you can check the logs and receipt with:

web3 rc TX_HASH


To automate testing using web3 CLI, enable the JSON format flag with --format json. This will return easily parseable results for your tests. Eg:

web3 --format json contract call --address 0xCONTRACT_ADDRESS --abi Hello.abi --function hello

And you'll get a JSON response like this:

  "response": [

List of available commands

Global parameters

$NETWORK as env variable or -network as command parameter - the name of the network. Available networks are:

  • gochain (default)
  • testnet
  • ethereum
  • ropsten
  • localhost

$RPC_URL as env variable or -rpc-url as command parameter - The network RPC URL (ie http://localhost:8545)

-verbose as command parameter - Verbose logging

Show information about a block

web3 block BLOCK_ID


  • BLOCK_ID - id of a block (omit for latest)

Show information about a transaction

web3 transaction TX_HASH


  • TX_HASH - hash of a transaction

Show information about an address

web3 transaction ADDRESS_HASH


  • ADDRESS_HASH - hash of the address

Build a smart contract

web3 contract build FILENAME.sol


  • FILENAME - the name of the .sol file, eg: hello.sol

Deploy a smart contract to a network

web3 contract deploy FILENAME.bin


  • FILENAME - the name of the .bin file
  • $WEB3_PRIVATE_KEY as env variable or -private-key as command parameter - the private key of the wallet

Call a function of a deployed contract


or using bundled abi files

web3 contract call --amount AMOUNT --address CONTRACT_ADDRESS --abi erc20|erc721 --function FUNCTION_NAME FUNCTION_PARAMETERS


  • CONTRACT_ADDRESS - the address of the deployed contract
  • CONTRACT_ABI_FILE - the abi file of the deployed contract (take into account that there are some bundled abi files like erc20 and erc721 so you could use them without downloading or compiling them)
  • FUNCTION_NAME - the name of the function you want to call
  • FUNCTION_PARAMETERS - the list of the function parameters
  • AMOUNT - amount of wei to be send with transaction (require only for paid transact functions)
  • $WEB3_PRIVATE_KEY as env variable or -private-key as command parameter - the private key of the wallet

List functions in an ABI

web3 contract list --abi CONTRACT_ABI_FILE


  • CONTRACT_ABI_FILE - the abi file of the compiled contract

Transfer amount to the address



  • RECIPIENT_ADDRESS - the address of the recepient
  • AMOUNT - the amount that should be send in the transaction ie - 1go (allowed units: go,eth,nanogo,gwei,attogo,wei)

Generate common contracts - ERC20, ERC721, etc

web3 generate contract [erc20/erc721] --name "TEST Tokens" --symbol "TEST"

See web3 generate contract --help for more information.

More installation options

Install a specific version

You can use the script to install a specific version:

curl -LSs | sh -s v0.0.9

Install using the Go language

go install

Build from source

Clone this repo:

git clone
cd web3
make build
./web3 help
You can’t perform that action at this time.