Interact with blockchains and smart contracts using the command line: no coding needed!

Table of contents

• Features
• Install
• Simple examples
• Advanced examples
• Smart Contract support
  • Read from a smart contract
  • Send a transaction to a smart contract
• Multi-chain support
• Use custom RPC
• Add custom chains
• Address book
• Wallet management
  • Default signer
  • Create new private keys
• Documentation
• Contributing
• Acknowledgements

Features

• Interact with Ethereum and EVM-compatible chains via your terminal
• Bypass sluggish and potentially compromised frontends
• No configuration needed
• Label addresses, tokens and contracts for ease of use
• Swap with Uniswap, TraderJoe, PancakeSwap, etc
• Support for the Compound V2 lending protocol and its forks (e.g. Eralend)
• Transfer tokens via their ticker
• Set Telegram alerts based on pending transactions, new blocks and contract events
• Replay transactions just with the tx hash
• Concatenate commands to build powerful scripts
• Import signers via private key or keyfile
• Thoroughly tested using the Ape Framework's testing framework
• Windows compatible

Soon:

• React to pending transactions, new blocks and contract events
• Set up scheduled buys and sells (DCA)
• Automatically buy when slippage is low enough
• Get notified on Telegram when a pair is liquid enough, or unbalanced
• Analyze on-chain data for tax or sleuthing purposes
• Claim and reinvest yield from DeFi protocols

Install

Make sure you have at least Python 3.9 installed, then run:

pip3 install -U web3cli

The same command will also upgrade web3cli to the latest version.

Windows user? Here's a tutorial for you!

Install via pipx

Fan of isolated environments? Install web3cli via pipx:

pipx install web3cli

To upgrade web3cli, run pipx upgrade web3cli.

Simple examples

• Get list of available commands:

  w3 --help

  or visit the Wiki page List of commands.

• Get help for a given command:

  w3 balance --help

• Get the ETH balance of any address:

  w3 balance 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae
  

• Save addresses with easy-to-rember tags:

  w3 address add unicef 0xa59b29d7dbc9794d1e7f45123c48b2b8d0a34636
  

  then use the tag in any command:

  w3 balance unicef
  

• Fetch blocks from the blockchain, in easy-to-read JSON format:

  w3 block latest
  w3 block finalized
  w3 block 6094305

• Fetch transactions & receipts from the blockchain:

  w3 tx get 0x3bbdcc2c7721521f7c767b7873ccb857f0816ac94e9f32c5601f4b15c87d1ef1
  w3 tx rc 0x3bbdcc2c7721521f7c767b7873ccb857f0816ac94e9f32c5601f4b15c87d1ef1

• Extract single fields from blocks or transactions, using jq (more details in the Wiki):

  w3 block latest | jq -r '.baseFeePerGas'

• Sign messages:

  w3 sign 'Hello world!'

• Get Keccak256 hashes starting from a text or a hex-string:

  w3 keccak-text 'Hello world!'
  w3 keccak-hex 'b495b1154ef1b2'

Advanced examples

• Send coins or tokens to any address:

  w3 send unicef 1 ETH      # send 1 ETH, ask for confirmation
  w3 send unicef 1 ETH gwei # send 1 gwei, ask for confirmation
  w3 send unicef 1 usdc     # send 1 USDC
  

• Swap tokens on a DEX:

  w3 swap uniswap_v2 1 usdc usdt     # swap 1 USDC for USDT on Uniswap
  w3avax swap traderjoe 1 usdc wavax # swap 1 USDC for WAVAX on TraderJoe
  

• Stream blocks, transactions and contract events as they happen in realtime:

  w3 subscribe blocks   # stream blocks as they are mined
  w3 subscribe pending  # stream pending transactions
  w3 subscribe events   # stream all contract events
  

  Streaming requires a websocket connection: specify one with the --rpc wss://... flag.

• Set a Telegram alert for when a specific event is emitted:

  # Get notified on Telegram when USDC is transferred
  transfer=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
  w3 subscribe events --telegram --contracts usdc --topics $transfer
  # Send a post notification when USDC is transferred
  w3 subscribe events --post https://www.example.com/ --contracts usdc --topics $transfer

  Telegram alerts require setting up a Telegram bot, please find instructions in the Wiki.

• Replay a given transactions on the blockchain:

  tx=`w3 send unicef 1 USDC --force` # send 1 USDC to Unicef
  w3 replay $tx                      # re-send 1 USDC to Unicef

Smart Contract support

web3cli comes preloaded with some popular smart contracts, including ERC20 tokens and Uniswap clones.

See the available contracts with w3 contract list:

w3 contract list               # contracts on Ethereum
w3 contract list --chain bnb   # contracts on BNB chain
w3 contract list --type erc20  # tokens on Ethereum

You can also add custom contracts with w3 contract add:

w3 contract add weth 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 --type erc20
w3 contract add sushi 0xd9e1cE17f2641f24aE83637ab66a2cca9C378B9F --type uniswap_v2

To add or list new tokens, you can use the w3 token shorthand:

w3 token add weth 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
w3 token list
w3 token delete weth

A more complex example: check USDT total supply on Arbitrum 100,000 blocks ago:

w3arb token supply usdt --block $(($(w3arb bnum)-100000))

For any given contract, see available functions and events with w3 abi functions and w3 abi events:

w3 abi fns weth           # functions on WETH token
w3 abi evs uniswap_v2     # events on Uniswap V2
w3 abi fns --abi abi.json # functions of an arbitrary ABI

Read from a smart contract

To read from a smart contract, use w3 call. For example, to get the total supply of the WETH token, run:

w3 call weth totalSupply

Function arguments are parsed automatically, so you can call balanceOf with:

w3 call weth balanceOf 0xA59B29d7dbC9794d1e7f45123C48b2b8d0a34636

You can also do more complex stuff like:

# get the amount of USDT you get for 100 USDC
w3 call uniswap_v2 getAmountsOut 100e6 usdc,usdt | jq -r '.[1]' 

Send a transaction to a smart contract

To write to the blockchain, use w3 transact. For example, to transfer 1 ETH to address, run:

w3 transact weth transfer <address> 1e18

To swap 1 USDC for USDT on Uniswap, accepting no less than 0.9 USDT in return, run:

w3 transact usdc approve uniswap_v2 1e6
w3 transact uniswap_v2 swapExactTokensForTokens 1e6 0.9e6 usdc,usdt <receiver address> 9e9

Multi-chain support

web3cli comes with out-of-the-box support for many chains. To see the list of available chains, visit the Wiki or run the command w3 chain list.

Pass the chain name using the flag --chain or the shorthand -c:

w3 balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3 --chain bnb  # bnb chain
w3 balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3 --chain avax # avax chain

You can also use one of the provided aliases, like w3bnb, w3avax, or w3arb:

w3bnb balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3  # bnb chain
w3avax balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3 # avax chain

If you are focussing on a specific chain, set it as the default:

w3 config set default_chain bnb
w3 balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3             # bnb chain
w3 balance 0x8894e0a0c962cb723c1976a4421c95949be2d4e3 --chain eth # eth chain

Use custom RPC

By default, web3cli will connect to the blockchain using a pre-configured public node. You can see the list of such nodes with the command w3 rpc list.

To use a custom mode, please specify the --rpc flag. For example, to use Ankr's node to Ethereum:

w3 block latest --rpc https://rpc.ankr.com/eth

Using a custom node is most useful in the following situations:

1. You want to use a node from a node provider, e.g. Infura:

   w3 block --rpc https://eth-mainnet.g.alchemy.com/v2/{YOUR-API-KEY}

2. You want to use a private node:

   w3 block --rpc http://127.0.0.1:8545
   w3 block --rpc ws://127.0.0.1:8546

3. You want to use a testnet chain:

   w3eth block --rpc https://rpc.ankr.com/eth_goerli
   w3bnb block --rpc https://data-seed-prebsc-1-s1.binance.org:8545/

Add custom chains

Add new chains with w3 chain add:

w3 chain add cronos 25 CRO --tx-type 2 --rpc https://evm.cronos.org

Use the custom chain with --chain:

w3 balance 0x7de9ab1e6a60ac7a70ce96d1d95a0dfcecf7bfb7 --chain cronos

List existing chains with w3 chain list, and delete them with w3 chain delete.

Address book

w3 can store tags just like you would do on etherscan.io or bscscan.com:

w3 address add ethereum_foundation 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae
w3 address add binance_hot_wallet 0x8894e0a0c962cb723c1976a4421c95949be2d4e3

You can use these tags instead of the actual addresses:

w3 balance ethereum_foundation
w3 balance binance_hot_wallet --chain bnb

To see the list of saved addresses, run w3 address list, to delete an address use w3 address delete.

Wallet management

Commands such as w3 send and w3 swap require that you specify who is going to sign the transactions. You can specify the signer with the --signer or -s flag:

w3 <command> --signer my-signer

Here, my_signer can be any of these things:

• The name or the address of a signer that you previously registered with w3 signer add my_signer. Signers created in this way are encrypted with the app key and stored in the database. At any time, you can see the list of registered users by running w3 signer list.
• The path to a file that you previously created with w3 keyfile create. A keyfile is a simple JSON file that contains your private key in password-encrypted form. Feel free to use keyfiles generated by other tools, like geth, parity, brownie, etc.
• The actual private key of the signer that you want to use. This is unsafe, use it at your own risk!

Please note that when the --signer flag is not provided, and there is only one registered signer, then this will be used.

Default signer

If you plan to use the same signer for a while, make it the default signer with the command:

w3 config set default_signer my_signer

In this way, you will not have to specify the --signer flag anymore.

Create new private keys

You can also create a brand new wallet on the go, without the need to provide a key, by using the --create flag:

w3 signer add my_wallet --create

The resulting private key will be printed to screen.

Documentation

Check the project's wiki on Github. In particular:

• 🫡 List of commands
• ⛓ All supported chains
• 📝 Configuration
• 🪟 Run web3cli on Windows
• ↪️ Output processing

Contributing

All contributions are welcome! To start improving web3cli, please refer to our contribution guide.

Acknowledgements

Thank you very much to the communities behind web3.py and the Ape Framework: web3cli would not exist without your efforts!