Skip to main content

Helper objects for generating ERC20s while testing a Brownie project.

Project description


Helper objects for generating ERC20s while testing a Brownie project.



via pipx

If you have installed Brownie using pipx, you need to add brownie-token-tester into the same virtual environment:

pipx inject eth-brownie brownie-token-tester

via pip

You can install the latest release via pip:

pip install brownie-token-tester

via setuptools

You can clone the repository and use setuptools for the most up-to-date version:

git clone
cd brownie-token-tester
python3 install

Quick Usage

Import the library from within a Brownie test, script or console:

from brownie_tokens import ERC20, MintableForkToken

You can then make use of the following functionality:


Deploys a generic ERC20 contract for testing purposes.

def ERC20(
    name: str = "Test Token",
    symbol: str = "TST",
    decimals: int = 18,
    success: Union[bool, None] = True,
    fail: Union[bool, str, None] = "revert",
) -> Contract:
  • The success kwarg is used to set the token's return value upon a successful call to approve, transfer or transferFrom. Valid values are True, False, and None.
  • The fail kwarg sets the token's behaviour upon failed calls to the above methods. Use "revert" if the transaction should revert, or True, False, and None to return a value without reverting.

The resulting deployment adheres to the ERC20 Token Standard and additionally implements one non-standard method:

def _mint_for_testing(target: address, amount: uint256): nonpayable

This method increases the balance of target by amount. It may be called by any account.


MintableForkToken is used to standardize the process of minting tokens when working in a forked mainnet environment. The MintableForkToken class inherits from and may be used interchangeably with the Contract class. It exposes one additional method, _mint_for_testing, with the same API as given above.

For tokens where custom logic is implemented, this is an actual minting event. For most tokens, the "minting" process involves a query to the Ethplorer API to get a list of top token holders, and then transferring their balances to target. If you want to exclude some holders from this process use skip_holders(*addresses). If you have too many requests at a time set $ETHPLORER_API_KEY(see as environment variable.

Tokens for which custom logic is currently implemented:

  • Aave tokens
  • DAI
  • EURS
  • LinkUSD
  • pBTC
  • Synthetix synths
  • renBTC
  • renZEC
  • rETH
  • RSV
  • USDC
  • USDN
  • USDT
  • tBTC
  • wBTC
  • wZEC


This project is still in early development and should be considered an alpha. Comments, questions, criticisms and pull requests are welcomed.


This project is licensed under the MIT license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

brownie-token-tester-0.3.2.tar.gz (9.8 kB view hashes)

Uploaded Source

Built Distribution

brownie_token_tester-0.3.2-py3-none-any.whl (9.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page