# Getting Started

bw is a command-line application, so you'll first need the files to run it. We have not released the tool openly at this point.

If you'd like access to the tool, contact us on Telegram (opens new window).

# Basic Usage

To see a list of global options and commands, you can run:


# Running a command

To run a command, simply give the name of the command as the first argument. For example, to use the private-key command run:

./bw private-key

# Walkthrough

This walkthrough will go over a few basic commands to get you started with bw. You should start by opening your terminal and connecting to the bw Server.

There is also a video walkthrough available.

# Reading token information

Let's start with something simple: reading some token information from the blockchain using the contract-call command.

Run the following command:

./bw contract-call name

The output will look something like this:

info: Network: Rinkeby
Food Coin

The first line begins with info:, which means it's just an informative log message. It's telling you the network bw is currently configured to use.

The second line is the actual output of the command, which in this case was Food Coin. That's the name of the token.

With that, we've read the name of the token from the blockchain!


The exact output you see may be slightly different, since it depends on bw's current configuration.

If you're seeing Network: Mainnet instead of Rinkeby and want to follow this walkthrough, you should edit the config.yaml file in the same directory and change the second line to read:

network: rinkeby

instead of mainnet.

We can read other information as well. All ERC20 tokens should have a symbol as well. We can read that the same way:

./bw contract-call symbol

The output is similar to before:

info: Network: Rinkeby

This time, it's giving us FC, which is the symbol of the Food Coin token.

# Reading token balances

We've read basic info on the token using contract-call. Those are simple and easy, because there's only one "name" in a contract.

We'd also like to read token balances for wallets, which can be done using the balanceOf function in ERC20 tokens. However, we need to tell the command which wallet's balance we want to know.

This can be provided by giving additional arguments to contract-call. In this case, I want to know the balance of the wallet 0x96cfe56665be4e5819416b352c4c86c525a7cf7d. I can do that by simply adding the address as an additional argument:

./bw contract-call balanceOf 0x96cfe56665be4e5819416b352c4c86c525a7cf7d

Here's the output from this command:

info: Network: Rinkeby

Okay, we have the balance, but there's an awful lot of zeroes. That's because Ethereum doesn't support decimals, so instead it's just a really big number. To get the value with decimals, you divide it:

bw has a utility to do this for you as well:

./bw from-wei 7000000000000000000



Note that this time it didn't show the info: Network line. That's because the from-wei conversion doesn't require connecting to Ethereum.


The above assumes the token you're working with has 18 decimals. If it has a different number of decimals, you can specify that with the from-wei command. For example, with 6 decimals:

./bw from-wei 7000000 -d 6

Because reading token balances is such a common need, bw has a simpler command that does the decimal conversion for you:

./bw balance 0x96cfe56665be4e5819416b352c4c86c525a7cf7d

Here's the output:

info: Network: Rinkeby

# Changing contracts

So far we've been using the default contract already configured in bw, but chances are you'll want to look at a different contract.

You can set the default contract bw uses by editing the config.yaml file and changing the value of contract_address:

# Address of the contract. This must be in quotes, otherwise it's interpreted 
# as a hex number
contract_address: "0xe8340FdfE79851e9E117b3033E147a654dbDb0Ae"

0xe8340FdfE79851e9E117b3033E147a654dbDb0Ae is the address for Food Coin. You can change it to any contract address you want.

Instead of editing config.yaml, you can also use a different contract address with the --address option. For example:

./bw --address 0xE595564689D6E0206b095915C219a8c7a130cF7B contract-call name


info: Network: Rinkeby
Rinkeby Roar

We're reading the name of the contract like in the beginning of this walkthrough, but this time the contract address is for Blockwell Roar on Rinkeby.

# Changing networks

Sooner or later you'll probably also want to look at different Ethereum networks. So far we've been looking at Rinkeby, let's switch over to the Main Ethereum Network.

Like with the contract address, you can change the network by either editing config.yaml:

# Name of the network to connect to. You can configure the specific nodes to use below.
network: rinkeby

If you change rinkeby to mainnet and save the file, bw will use the Main Network.

Alternatively, you can use the -n option and specify a network. Try running this command:

./bw --address 0xB8c77482e45F1F44dE1745F52C74426C631bDD52 -n mainnet \
    contract-call name

You should see the following output:

info: Network: Mainnet

With that command we asked it to use the Main Network with -n mainnet, and gave it the Binance token's contract address with --address 0xB8c77482e45F1F44dE1745F52C74426C631bDD52. "BNB" is what the Binance token has for a name.


You may have noticed that the command above is split into two lines, and has a \ at the end of it.

Using \ is a way in terminal to split your command on to multiple lines so it's easier to read. For example, these two commands are identical:

./bw contract-call name
./bw \
    contract-call \

Every time you want to use multiple lines for easier reading, just put in \ before you hit enter.

# Get all balances for a token

As the last part of this walkthrough, let's get a list of all wallets for a token and their balances. Run the following command:

./eth-tool -n rinkeby token-balances 0xe8340FdfE79851e9E117b3033E147a654dbDb0Ae

This will get all balances for Food Coin on Rinkeby. The output will start like this:

info: Network: Rinkeby
...lots more

That output may look confusing at first, but it's actually just CSV data that you can open as a spreadsheet in Excel or Google Sheets.

We'll want it in a file rather than the terminal though. Fortunately there's a handy terminal trick for that:

./eth-tool -n rinkeby --plain \ 
    token-balances 0xe8340FdfE79851e9E117b3033E147a654dbDb0Ae > foodcoin.csv

There are two changes from the previous command. First, we added --plain, which tells bw to not output any info, because that would interfere with the spreadsheet.

Secondly, the end has > foodcoin.csv. This is a standard method to tell your terminal that instead of showing the output, you want it to go into a file called foodcoin.csv.

After running that command, you should see the file in your current directory.


You'll probably want the csv file on your computer to load it into a spreadsheet, so here's how you can get it from the bw Server.

You can use a tool called scp that comes installed on most computers. Open another terminal on your own computer without connecting to the bw Server, and run the following command. Note! change "username" to what your actual username for bw.blockwell.ai is.

scp username@bw.blockwell.ai:~/bw/foodcoin.csv .

That may be a lot to unpack, but we're telling the tool we want to copy a file from the server bw.blockwell.ai. The file's location is ~/bw/foodcoin.csv. The last . just means we want to copy it to our current directory.