A series of utilities for working with tokens, based on the py-tokenlists.

• python3 version 3.8 up to 3.12.

You can install the latest release via pip:

pip install ape-tokens

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

git clone https://github.com/ApeWorX/ape-tokens.git
cd ape-tokens
python3 setup.py install

First, install a token list, such as the 1inch token list, which contains many tokens that you can use:

ape tokens install tokens.1inch.eth

To see all the tokens you can use, run command:

ape tokens list-tokens

To see other available CLI commands, run:

ape tokens --help

You can configure this plugin (and by extension, configure py-tokenlists) using the config file:

# ape-config.yaml
tokens:
  default: "My Default List"
  required:
    - name: "My Default List"
      uri: "http://example.com/tokenlist.json"

You can also configure this plugin via Environment Variable:

APE_TOKENS_DEFAULT="My Default List"
APE_TOKENS_REQUIRED='[{"name":"My Default List","uri":"http://example.com/tokenlist.json"}]'

Configuration like this may be useful for operating in a cloud environment

The tokens manager object is very useful for improving your ape experience. You can install it as a "console namespace extra" by adding the following lines to your project's ./ape_console_extras.py or your global $HOME/.ape/ape_console_extras.py:

...

try:
    from ape_tokens import tokens
except ImportError:
    pass  # Plugin not installed, skip

...

This way, whenever you use ape console (with this plugin installed) you will have tokens available immediately without having to import it!

One of the main reasons to use the ape-tokens plugin is to have nicer UX for providing token amounts to contract transactions. For example, let's say you have a smart-contract named MyContract with a function provideLinkToken() that takes a decimal value of LINK tokens. The following is an example script that deploys the contract and makes a transaction by expressing the value of LINK as 8.23 LINK:

from ape import accounts, project

my_account = accounts[0]
contract = my_account.deploy(project.MyContract)

tx = contract.provideLinkTokens("8.23 LINK", sender=me)

Alternatively, if you need the converted value returned to you, you can use the convert tool from the root ape namespace:

from ape import convert

convert("100.1234 BAT", int)

This plugin also provides a conversion function for addresses, for example if you want to use a .swap function that takes two address inputs which are expected to be tokens (as well as a 3rd argument which is an amount of the 1st token), you can do:

tx = swapper.swap("BAT", "LINK", "10 BAT", sender=me)

To get information about a token, including its contract address, you can do so by importing the tokens member from the root ape_tokens namespace:

from ape_tokens import tokens

bat = tokens["BAT"]

print(bat.address)
print(bat.symbol())

You can also work with the tokens object in an iterable context, such as iterating over a set of tokens in your token list:

from ape_tokens import tokens

for token in tokens:
    print(token.balanceOf(me))

Or in a mapping context (similar to using it like a dict):

assert "BAT" in tokens

if bat := tokens.get("BAT"):
    print("BAT is in our token list!")

ape-tokens also ships a test-token contract for using tokens in your Ape tests.

from ape_tokens.testing import MockERC20


def test_deposit(accounts):
    owner = accounts[0]
    
    # Setup some test tokens.
    usdc = MockERC20.deploy(owner, "USD Coin", "USDC", 6, sender=owner)
    weth = MockERC20.deploy(owner, "Wrapped Ether", "WETH", 18, sender=owner)
    
    ...