{"id":28467964,"url":"https://github.com/apeworx/ape-tokens","last_synced_at":"2026-01-18T12:39:52.125Z","repository":{"id":37777582,"uuid":"333311802","full_name":"ApeWorX/ape-tokens","owner":"ApeWorX","description":"Tokens converter plugin for the Ape Framework","archived":false,"fork":false,"pushed_at":"2025-05-31T03:04:18.000Z","size":76,"stargazers_count":10,"open_issues_count":9,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-31T12:08:47.518Z","etag":null,"topics":["ape","apeworx","python","tokenlist","tokens"],"latest_commit_sha":null,"homepage":"https://www.apeworx.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ApeWorX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-27T05:16:55.000Z","updated_at":"2025-05-06T03:34:22.000Z","dependencies_parsed_at":"2024-11-23T12:42:33.394Z","dependency_job_id":"54cfd5c6-a58a-424f-bce7-9daec7835678","html_url":"https://github.com/ApeWorX/ape-tokens","commit_stats":{"total_commits":24,"total_committers":8,"mean_commits":3.0,"dds":0.5416666666666667,"last_synced_commit":"1910101e430bb2a708c6f71cc121a978f1e7119b"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/ApeWorX/ape-tokens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApeWorX%2Fape-tokens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApeWorX%2Fape-tokens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApeWorX%2Fape-tokens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApeWorX%2Fape-tokens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ApeWorX","download_url":"https://codeload.github.com/ApeWorX/ape-tokens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApeWorX%2Fape-tokens/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262935969,"owners_count":23387291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ape","apeworx","python","tokenlist","tokens"],"created_at":"2025-06-07T08:06:08.071Z","updated_at":"2026-01-18T12:39:52.081Z","avatar_url":"https://github.com/ApeWorX.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quick Start\n\nA series of utilities for working with tokens, based on the [`py-tokenlists`](https://github.com/ApeWorX/py-tokenlists).\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.8 up to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install ape-tokens\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/ape-tokens.git\ncd ape-tokens\npython3 setup.py install\n```\n\n## Quick Usage\n\n### CLI Usage\n\nFirst, install a token list, such as the `1inch` token list, which contains many tokens that you can use:\n\n```bash\nape tokens install tokens.1inch.eth\n```\n\nTo see all the tokens you can use, run command:\n\n```bash\nape tokens list-tokens\n```\n\nTo see other available CLI commands, run:\n\n```bash\nape tokens --help\n```\n\n### Configuration\n\nYou can configure this plugin (and by extension, configure `py-tokenlists`) using the config file:\n\n```yaml\n# ape-config.yaml\ntokens:\n  default: \"My Default List\"\n  required:\n    - name: \"My Default List\"\n      uri: \"http://example.com/tokenlist.json\"\n```\n\nYou can also configure this plugin via Environment Variable:\n\n```sh\nAPE_TOKENS_DEFAULT=\"My Default List\"\nAPE_TOKENS_REQUIRED='[{\"name\":\"My Default List\",\"uri\":\"http://example.com/tokenlist.json\"}]'\n```\n\nConfiguration like this may be useful for operating in a cloud environment\n\n### Ape Console Extras\n\nThe `tokens` manager object is very useful for improving your ape experience.\nYou can install it as a [\"console namespace extra\"](https://docs.apeworx.io/ape/stable/userguides/console.html#namespace-extra) by adding the following lines to your project's `./ape_console_extras.py` or your global `$HOME/.ape/ape_console_extras.py`:\n\n```py\n...\n\ntry:\n    from ape_tokens import tokens\nexcept ImportError:\n    pass  # Plugin not installed, skip\n\n...\n```\n\nThis way, whenever you use `ape console` (with this plugin installed) you will have `tokens` available immediately without having to import it!\n\n### Python Usage\n\nOne of the main reasons to use the `ape-tokens` plugin is to have nicer UX for providing token amounts to contract transactions.\nFor example, let's say you have a smart-contract named `MyContract` with a function `provideLinkToken()` that takes a decimal value of `LINK` tokens.\nThe following is an example script that deploys the contract and makes a transaction by expressing the value of LINK as `8.23 LINK`:\n\n```python\nfrom ape import accounts, project\n\nmy_account = accounts[0]\ncontract = my_account.deploy(project.MyContract)\n\ntx = contract.provideLinkTokens(\"8.23 LINK\", sender=me)\n```\n\nAlternatively, if you need the converted value returned to you, you can use the `convert` tool from the root `ape` namespace:\n\n```python\nfrom ape import convert\n\nconvert(\"100.1234 BAT\", int)\n```\n\nThis 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:\n\n```python\ntx = swapper.swap(\"BAT\", \"LINK\", \"10 BAT\", sender=me)\n```\n\nTo get information about a token, including its contract address, you can do so by importing the `tokens` member from the root `ape_tokens` namespace:\n\n```python\nfrom ape_tokens import tokens\n\nbat = tokens[\"BAT\"]\n\nprint(bat.address)\nprint(bat.symbol())\n```\n\nYou can also work with the `tokens` object in an iterable context, such as iterating over a set of tokens in your token list:\n\n```python\nfrom ape_tokens import tokens\n\nfor token in tokens:\n    print(token.balanceOf(me))\n```\n\nOr in a mapping context (similar to using it like a dict):\n\n```python\nassert \"BAT\" in tokens\n\nif bat := tokens.get(\"BAT\"):\n    print(\"BAT is in our token list!\")\n```\n\n#### Testing\n\n`ape-tokens` also ships a test-token contract for using tokens in your Ape tests.\n\n```python\nfrom ape_tokens.testing import MockERC20\n\n\ndef test_deposit(accounts):\n    owner = accounts[0]\n    \n    # Setup some test tokens.\n    usdc = MockERC20.deploy(owner, \"USD Coin\", \"USDC\", 6, sender=owner)\n    weth = MockERC20.deploy(owner, \"Wrapped Ether\", \"WETH\", 18, sender=owner)\n    \n    ...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapeworx%2Fape-tokens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapeworx%2Fape-tokens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapeworx%2Fape-tokens/lists"}